View Javadoc
1   /*
2    * ====================================================================
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *   http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing,
14   * software distributed under the License is distributed on an
15   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16   * KIND, either express or implied.  See the License for the
17   * specific language governing permissions and limitations
18   * under the License.
19   * ====================================================================
20   *
21   * This software consists of voluntary contributions made by many
22   * individuals on behalf of the Apache Software Foundation.  For more
23   * information on the Apache Software Foundation, please see
24   * <http://www.apache.org/>.
25   *
26   */
27  
28  package org.apache.http.entity;
29  
30  import java.io.Serializable;
31  import java.nio.charset.Charset;
32  import java.nio.charset.UnsupportedCharsetException;
33  import java.util.ArrayList;
34  import java.util.Collections;
35  import java.util.HashMap;
36  import java.util.LinkedHashMap;
37  import java.util.List;
38  import java.util.Locale;
39  import java.util.Map;
40  
41  import org.apache.http.Consts;
42  import org.apache.http.Header;
43  import org.apache.http.HeaderElement;
44  import org.apache.http.HttpEntity;
45  import org.apache.http.NameValuePair;
46  import org.apache.http.ParseException;
47  import org.apache.http.annotation.Contract;
48  import org.apache.http.annotation.ThreadingBehavior;
49  import org.apache.http.message.BasicHeaderValueFormatter;
50  import org.apache.http.message.BasicHeaderValueParser;
51  import org.apache.http.message.BasicNameValuePair;
52  import org.apache.http.message.ParserCursor;
53  import org.apache.http.util.Args;
54  import org.apache.http.util.CharArrayBuffer;
55  import org.apache.http.util.TextUtils;
56  
57  /**
58   * Content type information consisting of a MIME type and an optional charset.
59   * <p>
60   * This class makes no attempts to verify validity of the MIME type.
61   * The input parameters of the {@link #create(String, String)} method, however, may not
62   * contain characters {@code <">, <;>, <,>} reserved by the HTTP specification.
63   *
64   * @since 4.2
65   */
66  @Contract(threading = ThreadingBehavior.IMMUTABLE)
67  public final class ContentType implements Serializable {
68  
69      private static final long serialVersionUID = -7768694718232371896L;
70  
71      // constants
72      public static final ContentType APPLICATION_ATOM_XML = create(
73              "application/atom+xml", Consts.ISO_8859_1);
74      public static final ContentType APPLICATION_FORM_URLENCODED = create(
75              "application/x-www-form-urlencoded", Consts.ISO_8859_1);
76      public static final ContentType APPLICATION_JSON = create(
77              "application/json", Consts.UTF_8);
78      public static final ContentType APPLICATION_OCTET_STREAM = create(
79              "application/octet-stream", (Charset) null);
80      public static final ContentType APPLICATION_SVG_XML = create(
81              "application/svg+xml", Consts.ISO_8859_1);
82      public static final ContentType APPLICATION_XHTML_XML = create(
83              "application/xhtml+xml", Consts.ISO_8859_1);
84      public static final ContentType APPLICATION_XML = create(
85              "application/xml", Consts.ISO_8859_1);
86      public static final ContentType IMAGE_BMP = create(
87              "image/bmp");
88      public static final ContentType IMAGE_GIF= create(
89              "image/gif");
90      public static final ContentType IMAGE_JPEG = create(
91              "image/jpeg");
92      public static final ContentType IMAGE_PNG = create(
93              "image/png");
94      public static final ContentType IMAGE_SVG= create(
95              "image/svg+xml");
96      public static final ContentType IMAGE_TIFF = create(
97              "image/tiff");
98      public static final ContentType IMAGE_WEBP = create(
99              "image/webp");
100     public static final ContentType MULTIPART_FORM_DATA = create(
101             "multipart/form-data", Consts.ISO_8859_1);
102     public static final ContentType TEXT_HTML = create(
103             "text/html", Consts.ISO_8859_1);
104     public static final ContentType TEXT_PLAIN = create(
105             "text/plain", Consts.ISO_8859_1);
106     public static final ContentType TEXT_XML = create(
107             "text/xml", Consts.ISO_8859_1);
108     public static final ContentType WILDCARD = create(
109             "*/*", (Charset) null);
110 
111 
112     private static final Map<String, ContentType> CONTENT_TYPE_MAP;
113     static {
114 
115         final ContentType[] contentTypes = {
116             APPLICATION_ATOM_XML,
117             APPLICATION_FORM_URLENCODED,
118             APPLICATION_JSON,
119             APPLICATION_SVG_XML,
120             APPLICATION_XHTML_XML,
121             APPLICATION_XML,
122             IMAGE_BMP,
123             IMAGE_GIF,
124             IMAGE_JPEG,
125             IMAGE_PNG,
126             IMAGE_SVG,
127             IMAGE_TIFF,
128             IMAGE_WEBP,
129             MULTIPART_FORM_DATA,
130             TEXT_HTML,
131             TEXT_PLAIN,
132             TEXT_XML };
133         final HashMap<String, ContentType> map = new HashMap<String, ContentType>();
134         for (final ContentType contentType: contentTypes) {
135             map.put(contentType.getMimeType(), contentType);
136         }
137         CONTENT_TYPE_MAP = Collections.unmodifiableMap(map);
138     }
139 
140     // defaults
141     public static final ContentType DEFAULT_TEXT = TEXT_PLAIN;
142     public static final ContentType DEFAULT_BINARY = APPLICATION_OCTET_STREAM;
143 
144     private final String mimeType;
145     private final Charset charset;
146     private final NameValuePair[] params;
147 
148     ContentType(
149             final String mimeType,
150             final Charset charset) {
151         this.mimeType = mimeType;
152         this.charset = charset;
153         this.params = null;
154     }
155 
156     ContentType(
157             final String mimeType,
158             final Charset charset,
159             final NameValuePair[] params) {
160         this.mimeType = mimeType;
161         this.charset = charset;
162         this.params = params;
163     }
164 
165     public String getMimeType() {
166         return this.mimeType;
167     }
168 
169     public Charset getCharset() {
170         return this.charset;
171     }
172 
173     /**
174      * @since 4.3
175      */
176     public String getParameter(final String name) {
177         Args.notEmpty(name, "Parameter name");
178         if (this.params == null) {
179             return null;
180         }
181         for (final NameValuePair param: this.params) {
182             if (param.getName().equalsIgnoreCase(name)) {
183                 return param.getValue();
184             }
185         }
186         return null;
187     }
188 
189     /**
190      * Generates textual representation of this content type which can be used as the value
191      * of a {@code Content-Type} header.
192      */
193     @Override
194     public String toString() {
195         final CharArrayBuffer buf = new CharArrayBuffer(64);
196         buf.append(this.mimeType);
197         if (this.params != null) {
198             buf.append("; ");
199             BasicHeaderValueFormatter.INSTANCE.formatParameters(buf, this.params, false);
200         } else if (this.charset != null) {
201             buf.append("; charset=");
202             buf.append(this.charset.name());
203         }
204         return buf.toString();
205     }
206 
207     private static boolean valid(final String s) {
208         for (int i = 0; i < s.length(); i++) {
209             final char ch = s.charAt(i);
210             if (ch == '"' || ch == ',' || ch == ';') {
211                 return false;
212             }
213         }
214         return true;
215     }
216 
217     /**
218      * Creates a new instance of {@link ContentType}.
219      *
220      * @param mimeType MIME type. It may not be {@code null} or empty. It may not contain
221      *        characters {@code <">, <;>, <,>} reserved by the HTTP specification.
222      * @param charset charset.
223      * @return content type
224      */
225     public static ContentType create(final String mimeType, final Charset charset) {
226         final String normalizedMimeType = Args.notBlank(mimeType, "MIME type").toLowerCase(Locale.ROOT);
227         Args.check(valid(normalizedMimeType), "MIME type may not contain reserved characters");
228         return new ContentType(normalizedMimeType, charset);
229     }
230 
231     /**
232      * Creates a new instance of {@link ContentType} without a charset.
233      *
234      * @param mimeType MIME type. It may not be {@code null} or empty. It may not contain
235      *        characters {@code <">, <;>, <,>} reserved by the HTTP specification.
236      * @return content type
237      */
238     public static ContentType create(final String mimeType) {
239         return create(mimeType, (Charset) null);
240     }
241 
242     /**
243      * Creates a new instance of {@link ContentType}.
244      *
245      * @param mimeType MIME type. It may not be {@code null} or empty. It may not contain
246      *        characters {@code <">, <;>, <,>} reserved by the HTTP specification.
247      * @param charset charset. It may not contain characters {@code <">, <;>, <,>} reserved by the HTTP
248      *        specification. This parameter is optional.
249      * @return content type
250      * @throws UnsupportedCharsetException Thrown when the named charset is not available in
251      * this instance of the Java virtual machine
252      */
253     public static ContentType create(
254             final String mimeType, final String charset) throws UnsupportedCharsetException {
255         return create(mimeType, !TextUtils.isBlank(charset) ? Charset.forName(charset) : null);
256     }
257 
258     private static ContentType create(final HeaderElement helem, final boolean strict) {
259         return create(helem.getName(), helem.getParameters(), strict);
260     }
261 
262     private static ContentType create(final String mimeType, final NameValuePair[] params, final boolean strict) {
263         Charset charset = null;
264         for (final NameValuePair param: params) {
265             if (param.getName().equalsIgnoreCase("charset")) {
266                 final String s = param.getValue();
267                 if (!TextUtils.isBlank(s)) {
268                     try {
269                         charset =  Charset.forName(s);
270                     } catch (final UnsupportedCharsetException ex) {
271                         if (strict) {
272                             throw ex;
273                         }
274                     }
275                 }
276                 break;
277             }
278         }
279         return new ContentType(mimeType, charset, params != null && params.length > 0 ? params : null);
280     }
281 
282     /**
283      * Creates a new instance of {@link ContentType} with the given parameters.
284      *
285      * @param mimeType MIME type. It may not be {@code null} or empty. It may not contain
286      *        characters {@code <">, <;>, <,>} reserved by the HTTP specification.
287      * @param params parameters.
288      * @return content type
289      *
290      * @since 4.4
291      */
292     public static ContentType create(
293             final String mimeType, final NameValuePair... params) throws UnsupportedCharsetException {
294         final String type = Args.notBlank(mimeType, "MIME type").toLowerCase(Locale.ROOT);
295         Args.check(valid(type), "MIME type may not contain reserved characters");
296         return create(mimeType, params, true);
297     }
298 
299     /**
300      * Parses textual representation of {@code Content-Type} value.
301      *
302      * @param s text
303      * @return content type
304      * @throws ParseException if the given text does not represent a valid
305      * {@code Content-Type} value.
306      * @throws UnsupportedCharsetException Thrown when the named charset is not available in
307      * this instance of the Java virtual machine
308      */
309     public static ContentType parse(
310             final String s) throws ParseException, UnsupportedCharsetException {
311         Args.notNull(s, "Content type");
312         final CharArrayBuffer buf = new CharArrayBuffer(s.length());
313         buf.append(s);
314         final ParserCursor cursor = new ParserCursor(0, s.length());
315         final HeaderElement[] elements = BasicHeaderValueParser.INSTANCE.parseElements(buf, cursor);
316         if (elements.length > 0) {
317             return create(elements[0], true);
318         } else {
319             throw new ParseException("Invalid content type: " + s);
320         }
321     }
322 
323     /**
324      * Extracts {@code Content-Type} value from {@link HttpEntity} exactly as
325      * specified by the {@code Content-Type} header of the entity. Returns {@code null}
326      * if not specified.
327      *
328      * @param entity HTTP entity
329      * @return content type
330      * @throws ParseException if the given text does not represent a valid
331      * {@code Content-Type} value.
332      * @throws UnsupportedCharsetException Thrown when the named charset is not available in
333      * this instance of the Java virtual machine
334      */
335     public static ContentType get(
336             final HttpEntity entity) throws ParseException, UnsupportedCharsetException {
337         if (entity == null) {
338             return null;
339         }
340         final Header header = entity.getContentType();
341         if (header != null) {
342             final HeaderElement[] elements = header.getElements();
343             if (elements.length > 0) {
344                 return create(elements[0], true);
345             }
346         }
347         return null;
348     }
349 
350     /**
351      * Extracts {@code Content-Type} value from {@link HttpEntity}. Returns {@code null}
352      * if not specified or incorrect (could not be parsed)..
353      *
354      * @param entity HTTP entity
355      * @return content type
356      *
357      * @since 4.4
358      *
359      */
360     public static ContentType getLenient(final HttpEntity entity) {
361         if (entity == null) {
362             return null;
363         }
364         final Header header = entity.getContentType();
365         if (header != null) {
366             try {
367                 final HeaderElement[] elements = header.getElements();
368                 if (elements.length > 0) {
369                     return create(elements[0], false);
370                 }
371             } catch (final ParseException ex) {
372                 return null;
373             }
374         }
375         return null;
376     }
377 
378     /**
379      * Extracts {@code Content-Type} value from {@link HttpEntity} or returns the default value
380      * {@link #DEFAULT_TEXT} if not explicitly specified.
381      *
382      * @param entity HTTP entity
383      * @return content type
384      * @throws ParseException if the given text does not represent a valid
385      * {@code Content-Type} value.
386      * @throws UnsupportedCharsetException Thrown when the named charset is not available in
387      * this instance of the Java virtual machine
388      */
389     public static ContentType getOrDefault(
390             final HttpEntity entity) throws ParseException, UnsupportedCharsetException {
391         final ContentType contentType = get(entity);
392         return contentType != null ? contentType : DEFAULT_TEXT;
393     }
394 
395     /**
396      * Extracts {@code Content-Type} value from {@link HttpEntity} or returns the default value
397      * {@link #DEFAULT_TEXT} if not explicitly specified or incorrect (could not be parsed).
398      *
399      * @param entity HTTP entity
400      * @return content type
401      *
402      * @since 4.4
403      */
404     public static ContentType getLenientOrDefault(
405             final HttpEntity entity) throws ParseException, UnsupportedCharsetException {
406         final ContentType contentType = get(entity);
407         return contentType != null ? contentType : DEFAULT_TEXT;
408     }
409 
410 
411     /**
412      * Returns {@code Content-Type} for the given MIME type.
413      *
414      * @param mimeType MIME type
415      * @return content type or {@code null} if not known.
416      *
417      * @since 4.5
418      */
419     public static ContentType getByMimeType(final String mimeType) {
420         if (mimeType == null) {
421             return null;
422         }
423         return CONTENT_TYPE_MAP.get(mimeType);
424     }
425 
426     /**
427      * Creates a new instance with this MIME type and the given Charset.
428      *
429      * @param charset charset
430      * @return a new instance with this MIME type and the given Charset.
431      * @since 4.3
432      */
433     public ContentType withCharset(final Charset charset) {
434         return create(this.getMimeType(), charset);
435     }
436 
437     /**
438      * Creates a new instance with this MIME type and the given Charset name.
439      *
440      * @param charset name
441      * @return a new instance with this MIME type and the given Charset name.
442      * @throws UnsupportedCharsetException Thrown when the named charset is not available in
443      * this instance of the Java virtual machine
444      * @since 4.3
445      */
446     public ContentType withCharset(final String charset) {
447         return create(this.getMimeType(), charset);
448     }
449 
450     /**
451      * Creates a new instance with this MIME type and the given parameters.
452      *
453      * @param params
454      * @return a new instance with this MIME type and the given parameters.
455      * @since 4.4
456      */
457     public ContentType withParameters(
458             final NameValuePair... params) throws UnsupportedCharsetException {
459         if (params.length == 0) {
460             return this;
461         }
462         final Map<String, String> paramMap = new LinkedHashMap<String, String>();
463         if (this.params != null) {
464             for (final NameValuePair param: this.params) {
465                 paramMap.put(param.getName(), param.getValue());
466             }
467         }
468         for (final NameValuePair param: params) {
469             paramMap.put(param.getName(), param.getValue());
470         }
471         final List<NameValuePair> newParams = new ArrayList<NameValuePair>(paramMap.size() + 1);
472         if (this.charset != null && !paramMap.containsKey("charset")) {
473             newParams.add(new BasicNameValuePair("charset", this.charset.name()));
474         }
475         for (final Map.Entry<String, String> entry: paramMap.entrySet()) {
476             newParams.add(new BasicNameValuePair(entry.getKey(), entry.getValue()));
477         }
478         return create(this.getMimeType(), newParams.toArray(new NameValuePair[newParams.size()]), true);
479     }
480 
481 }