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.Locale;
34  
35  import org.apache.http.Consts;
36  import org.apache.http.Header;
37  import org.apache.http.HeaderElement;
38  import org.apache.http.HttpEntity;
39  import org.apache.http.NameValuePair;
40  import org.apache.http.ParseException;
41  import org.apache.http.annotation.Immutable;
42  import org.apache.http.message.BasicHeaderValueFormatter;
43  import org.apache.http.message.BasicHeaderValueParser;
44  import org.apache.http.message.ParserCursor;
45  import org.apache.http.util.Args;
46  import org.apache.http.util.CharArrayBuffer;
47  import org.apache.http.util.TextUtils;
48  
49  /**
50   * Content type information consisting of a MIME type and an optional charset.
51   * <p/>
52   * This class makes no attempts to verify validity of the MIME type.
53   * The input parameters of the {@link #create(String, String)} method, however, may not
54   * contain characters <">, <;>, <,> reserved by the HTTP specification.
55   *
56   * @since 4.2
57   */
58  @Immutable
59  public final class ContentType implements Serializable {
60  
61      private static final long serialVersionUID = -7768694718232371896L;
62  
63      // constants
64      public static final ContentType APPLICATION_ATOM_XML = create(
65              "application/atom+xml", Consts.ISO_8859_1);
66      public static final ContentType APPLICATION_FORM_URLENCODED = create(
67              "application/x-www-form-urlencoded", Consts.ISO_8859_1);
68      public static final ContentType APPLICATION_JSON = create(
69              "application/json", Consts.UTF_8);
70      public static final ContentType APPLICATION_OCTET_STREAM = create(
71              "application/octet-stream", (Charset) null);
72      public static final ContentType APPLICATION_SVG_XML = create(
73              "application/svg+xml", Consts.ISO_8859_1);
74      public static final ContentType APPLICATION_XHTML_XML = create(
75              "application/xhtml+xml", Consts.ISO_8859_1);
76      public static final ContentType APPLICATION_XML = create(
77              "application/xml", Consts.ISO_8859_1);
78      public static final ContentType MULTIPART_FORM_DATA = create(
79              "multipart/form-data", Consts.ISO_8859_1);
80      public static final ContentType TEXT_HTML = create(
81              "text/html", Consts.ISO_8859_1);
82      public static final ContentType TEXT_PLAIN = create(
83              "text/plain", Consts.ISO_8859_1);
84      public static final ContentType TEXT_XML = create(
85              "text/xml", Consts.ISO_8859_1);
86      public static final ContentType WILDCARD = create(
87              "*/*", (Charset) null);
88  
89      // defaults
90      public static final ContentType DEFAULT_TEXT = TEXT_PLAIN;
91      public static final ContentType DEFAULT_BINARY = APPLICATION_OCTET_STREAM;
92  
93      private final String mimeType;
94      private final Charset charset;
95      private final NameValuePair[] params;
96  
97      ContentType(
98              final String mimeType,
99              final Charset charset) {
100         this.mimeType = mimeType;
101         this.charset = charset;
102         this.params = null;
103     }
104 
105     ContentType(
106             final String mimeType,
107             final Charset charset,
108             final NameValuePair[] params) {
109         this.mimeType = mimeType;
110         this.charset = charset;
111         this.params = params;
112     }
113 
114     public String getMimeType() {
115         return this.mimeType;
116     }
117 
118     public Charset getCharset() {
119         return this.charset;
120     }
121 
122     /**
123      * @since 4.3
124      */
125     public String getParameter(final String name) {
126         Args.notEmpty(name, "Parameter name");
127         if (this.params == null) {
128             return null;
129         }
130         for (final NameValuePair param: this.params) {
131             if (param.getName().equalsIgnoreCase(name)) {
132                 return param.getValue();
133             }
134         }
135         return null;
136     }
137 
138     /**
139      * Generates textual representation of this content type which can be used as the value
140      * of a <code>Content-Type</code> header.
141      */
142     @Override
143     public String toString() {
144         final CharArrayBuffer buf = new CharArrayBuffer(64);
145         buf.append(this.mimeType);
146         if (this.params != null) {
147             buf.append("; ");
148             BasicHeaderValueFormatter.INSTANCE.formatParameters(buf, this.params, false);
149         } else if (this.charset != null) {
150             buf.append("; charset=");
151             buf.append(this.charset.name());
152         }
153         return buf.toString();
154     }
155 
156     private static boolean valid(final String s) {
157         for (int i = 0; i < s.length(); i++) {
158             final char ch = s.charAt(i);
159             if (ch == '"' || ch == ',' || ch == ';') {
160                 return false;
161             }
162         }
163         return true;
164     }
165 
166     /**
167      * Creates a new instance of {@link ContentType}.
168      *
169      * @param mimeType MIME type. It may not be <code>null</code> or empty. It may not contain
170      *        characters <">, <;>, <,> reserved by the HTTP specification.
171      * @param charset charset.
172      * @return content type
173      */
174     public static ContentType create(final String mimeType, final Charset charset) {
175         final String type = Args.notBlank(mimeType, "MIME type").toLowerCase(Locale.ROOT);
176         Args.check(valid(type), "MIME type may not contain reserved characters");
177         return new ContentType(type, charset);
178     }
179 
180     /**
181      * Creates a new instance of {@link ContentType} without a charset.
182      *
183      * @param mimeType MIME type. It may not be <code>null</code> or empty. It may not contain
184      *        characters <">, <;>, <,> reserved by the HTTP specification.
185      * @return content type
186      */
187     public static ContentType create(final String mimeType) {
188         return new ContentType(mimeType, (Charset) null);
189     }
190 
191     /**
192      * Creates a new instance of {@link ContentType}.
193      *
194      * @param mimeType MIME type. It may not be <code>null</code> or empty. It may not contain
195      *        characters <">, <;>, <,> reserved by the HTTP specification.
196      * @param charset charset. It may not contain characters <">, <;>, <,> reserved by the HTTP
197      *        specification. This parameter is optional.
198      * @return content type
199      * @throws UnsupportedCharsetException Thrown when the named charset is not available in
200      * this instance of the Java virtual machine
201      */
202     public static ContentType create(
203             final String mimeType, final String charset) throws UnsupportedCharsetException {
204         return create(mimeType, !TextUtils.isBlank(charset) ? Charset.forName(charset) : null);
205     }
206 
207     private static ContentType create(final HeaderElement helem, final boolean strict) {
208         final String mimeType = helem.getName();
209         final NameValuePair[] params = helem.getParameters();
210 
211         Charset charset = null;
212         for (final NameValuePair param: params) {
213             if (param.getName().equalsIgnoreCase("charset")) {
214                 final String s = param.getValue();
215                 if (!TextUtils.isBlank(s)) {
216                     try {
217                         charset =  Charset.forName(s);
218                     } catch (UnsupportedCharsetException ex) {
219                         if (strict) {
220                             throw ex;
221                         }
222                     }
223                 }
224                 break;
225             }
226         }
227         return new ContentType(mimeType, charset, params != null && params.length > 0 ? params : null);
228     }
229 
230     /**
231      * Parses textual representation of <code>Content-Type</code> value.
232      *
233      * @param s text
234      * @return content type
235      * @throws ParseException if the given text does not represent a valid
236      * <code>Content-Type</code> value.
237      * @throws UnsupportedCharsetException Thrown when the named charset is not available in
238      * this instance of the Java virtual machine
239      */
240     public static ContentType parse(
241             final String s) throws ParseException, UnsupportedCharsetException {
242         Args.notNull(s, "Content type");
243         final CharArrayBuffer buf = new CharArrayBuffer(s.length());
244         buf.append(s);
245         final ParserCursor cursor = new ParserCursor(0, s.length());
246         final HeaderElement[] elements = BasicHeaderValueParser.INSTANCE.parseElements(buf, cursor);
247         if (elements.length > 0) {
248             return create(elements[0], true);
249         } else {
250             throw new ParseException("Invalid content type: " + s);
251         }
252     }
253 
254     /**
255      * Extracts <code>Content-Type</code> value from {@link HttpEntity} exactly as
256      * specified by the <code>Content-Type</code> header of the entity. Returns <code>null</code>
257      * if not specified.
258      *
259      * @param entity HTTP entity
260      * @return content type
261      * @throws ParseException if the given text does not represent a valid
262      * <code>Content-Type</code> value.
263      * @throws UnsupportedCharsetException Thrown when the named charset is not available in
264      * this instance of the Java virtual machine
265      */
266     public static ContentType get(
267             final HttpEntity entity) throws ParseException, UnsupportedCharsetException {
268         if (entity == null) {
269             return null;
270         }
271         final Header header = entity.getContentType();
272         if (header != null) {
273             final HeaderElement[] elements = header.getElements();
274             if (elements.length > 0) {
275                 return create(elements[0], true);
276             }
277         }
278         return null;
279     }
280 
281     /**
282      * Extracts <code>Content-Type</code> value from {@link HttpEntity}. Returns <code>null</code>
283      * if not specified or incorrect (could not be parsed)..
284      *
285      * @param entity HTTP entity
286      * @return content type
287      *
288      * @since 4.4
289      *
290      */
291     public static ContentType getLenient(final HttpEntity entity) {
292         if (entity == null) {
293             return null;
294         }
295         final Header header = entity.getContentType();
296         if (header != null) {
297             try {
298                 final HeaderElement[] elements = header.getElements();
299                 if (elements.length > 0) {
300                     return create(elements[0], false);
301                 }
302             } catch (ParseException ex) {
303                 return null;
304             }
305         }
306         return null;
307     }
308 
309     /**
310      * Extracts <code>Content-Type</code> value from {@link HttpEntity} or returns the default value
311      * {@link #DEFAULT_TEXT} if not explicitly specified.
312      *
313      * @param entity HTTP entity
314      * @return content type
315      * @throws ParseException if the given text does not represent a valid
316      * <code>Content-Type</code> value.
317      * @throws UnsupportedCharsetException Thrown when the named charset is not available in
318      * this instance of the Java virtual machine
319      */
320     public static ContentType getOrDefault(
321             final HttpEntity entity) throws ParseException, UnsupportedCharsetException {
322         final ContentType contentType = get(entity);
323         return contentType != null ? contentType : DEFAULT_TEXT;
324     }
325 
326     /**
327      * Extracts <code>Content-Type</code> value from {@link HttpEntity} or returns the default value
328      * {@link #DEFAULT_TEXT} if not explicitly specified or incorrect (could not be parsed).
329      *
330      * @param entity HTTP entity
331      * @return content type
332      *
333      * @since 4.4
334      */
335     public static ContentType getLenientOrDefault(
336             final HttpEntity entity) throws ParseException, UnsupportedCharsetException {
337         final ContentType contentType = get(entity);
338         return contentType != null ? contentType : DEFAULT_TEXT;
339     }
340 
341     /**
342      * Creates a new instance with this MIME type and the given Charset.
343      *
344      * @param charset charset
345      * @return a new instance with this MIME type and the given Charset.
346      * @since 4.3
347      */
348     public ContentType withCharset(final Charset charset) {
349         return create(this.getMimeType(), charset);
350     }
351 
352     /**
353      * Creates a new instance with this MIME type and the given Charset name.
354      *
355      * @param charset name
356      * @return a new instance with this MIME type and the given Charset name.
357      * @throws UnsupportedCharsetException Thrown when the named charset is not available in
358      * this instance of the Java virtual machine
359      * @since 4.3
360      */
361     public ContentType withCharset(final String charset) {
362         return create(this.getMimeType(), charset);
363     }
364 
365 }