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  package org.apache.http.util;
28  
29  import java.io.UnsupportedEncodingException;
30  
31  import org.apache.http.Consts;
32  
33  /**
34   * The home for utility methods that handle various encoding tasks.
35   *
36   *
37   * @since 4.0
38   */
39  public final class EncodingUtils {
40  
41      /**
42       * Converts the byte array of HTTP content characters to a string. If
43       * the specified charset is not supported, default system encoding
44       * is used.
45       *
46       * @param data the byte array to be encoded
47       * @param offset the index of the first byte to encode
48       * @param length the number of bytes to encode
49       * @param charset the desired character encoding
50       * @return The result of the conversion.
51       */
52      public static String getString(
53          final byte[] data,
54          int offset,
55          int length,
56          String charset
57      ) {
58  
59          if (data == null) {
60              throw new IllegalArgumentException("Parameter may not be null");
61          }
62  
63          if (charset == null || charset.length() == 0) {
64              throw new IllegalArgumentException("charset may not be null or empty");
65          }
66  
67          try {
68              return new String(data, offset, length, charset);
69          } catch (UnsupportedEncodingException e) {
70              return new String(data, offset, length);
71          }
72      }
73  
74  
75      /**
76       * Converts the byte array of HTTP content characters to a string. If
77       * the specified charset is not supported, default system encoding
78       * is used.
79       *
80       * @param data the byte array to be encoded
81       * @param charset the desired character encoding
82       * @return The result of the conversion.
83       */
84      public static String getString(final byte[] data, final String charset) {
85          if (data == null) {
86              throw new IllegalArgumentException("Parameter may not be null");
87          }
88          return getString(data, 0, data.length, charset);
89      }
90  
91      /**
92       * Converts the specified string to a byte array.  If the charset is not supported the
93       * default system charset is used.
94       *
95       * @param data the string to be encoded
96       * @param charset the desired character encoding
97       * @return The resulting byte array.
98       */
99      public static byte[] getBytes(final String data, final String charset) {
100 
101         if (data == null) {
102             throw new IllegalArgumentException("data may not be null");
103         }
104 
105         if (charset == null || charset.length() == 0) {
106             throw new IllegalArgumentException("charset may not be null or empty");
107         }
108 
109         try {
110             return data.getBytes(charset);
111         } catch (UnsupportedEncodingException e) {
112             return data.getBytes();
113         }
114     }
115 
116     /**
117      * Converts the specified string to byte array of ASCII characters.
118      *
119      * @param data the string to be encoded
120      * @return The string as a byte array.
121      */
122     public static byte[] getAsciiBytes(final String data) {
123 
124         if (data == null) {
125             throw new IllegalArgumentException("Parameter may not be null");
126         }
127 
128         try {
129             return data.getBytes(Consts.ASCII.name());
130         } catch (UnsupportedEncodingException e) {
131             throw new Error("HttpClient requires ASCII support");
132         }
133     }
134 
135     /**
136      * Converts the byte array of ASCII characters to a string. This method is
137      * to be used when decoding content of HTTP elements (such as response
138      * headers)
139      *
140      * @param data the byte array to be encoded
141      * @param offset the index of the first byte to encode
142      * @param length the number of bytes to encode
143      * @return The string representation of the byte array
144      */
145     public static String getAsciiString(final byte[] data, int offset, int length) {
146 
147         if (data == null) {
148             throw new IllegalArgumentException("Parameter may not be null");
149         }
150 
151         try {
152             return new String(data, offset, length, Consts.ASCII.name());
153         } catch (UnsupportedEncodingException e) {
154             throw new Error("HttpClient requires ASCII support");
155         }
156     }
157 
158     /**
159      * Converts the byte array of ASCII characters to a string. This method is
160      * to be used when decoding content of HTTP elements (such as response
161      * headers)
162      *
163      * @param data the byte array to be encoded
164      * @return The string representation of the byte array
165      */
166     public static String getAsciiString(final byte[] data) {
167         if (data == null) {
168             throw new IllegalArgumentException("Parameter may not be null");
169         }
170         return getAsciiString(data, 0, data.length);
171     }
172 
173     /**
174      * This class should not be instantiated.
175      */
176     private EncodingUtils() {
177     }
178 
179 }