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.client.entity;
29  
30  import java.io.File;
31  import java.io.InputStream;
32  import java.io.Serializable;
33  import java.util.Arrays;
34  import java.util.List;
35  
36  import org.apache.http.HttpEntity;
37  import org.apache.http.NameValuePair;
38  import org.apache.http.annotation.NotThreadSafe;
39  import org.apache.http.entity.AbstractHttpEntity;
40  import org.apache.http.entity.BasicHttpEntity;
41  import org.apache.http.entity.ByteArrayEntity;
42  import org.apache.http.entity.ContentType;
43  import org.apache.http.entity.FileEntity;
44  import org.apache.http.entity.InputStreamEntity;
45  import org.apache.http.entity.SerializableEntity;
46  import org.apache.http.entity.StringEntity;
47  
48  /**
49   * Builder for {@link HttpEntity} instances.
50   * <p/>
51   * Several setter methods of this builder are mutually exclusive. In case of multiple invocations
52   * of the following methods only the last one will have effect:
53   * <ul>
54   *   <li>{@link #setText(String)}</li>
55   *   <li>{@link #setBinary(byte[])}</li>
56   *   <li>{@link #setStream(java.io.InputStream)}</li>
57   *   <li>{@link #setSerializable(java.io.Serializable)}</li>
58   *   <li>{@link #setParameters(java.util.List)}</li>
59   *   <li>{@link #setParameters(org.apache.http.NameValuePair...)}</li>
60   *   <li>{@link #setFile(java.io.File)}</li>
61   * </ul>
62   *
63   * @since 4.3
64   */
65  @NotThreadSafe
66  public class EntityBuilder {
67  
68      private String text;
69      private byte[] binary;
70      private InputStream stream;
71      private List<NameValuePair> parameters;
72      private Serializable serializable;
73      private File file;
74      private ContentType contentType;
75      private String contentEncoding;
76      private boolean chunked;
77      private boolean gzipCompress;
78  
79      EntityBuilder() {
80          super();
81      }
82  
83      public static EntityBuilder create() {
84          return new EntityBuilder();
85      }
86  
87      private void clearContent() {
88          this.text = null;
89          this.binary = null;
90          this.stream = null;
91          this.parameters = null;
92          this.serializable = null;
93          this.file = null;
94      }
95  
96      /**
97       * Returns entity content as a string if set using {@link #setText(String)} method.
98       */
99      public String getText() {
100         return text;
101     }
102 
103     /**
104      * Sets entity content as a string. This method is mutually exclusive with
105      * {@link #setBinary(byte[])},
106      * {@link #setStream(java.io.InputStream)} ,
107      * {@link #setSerializable(java.io.Serializable)} ,
108      * {@link #setParameters(java.util.List)},
109      * {@link #setParameters(org.apache.http.NameValuePair...)}
110      * {@link #setFile(java.io.File)} methods.
111      */
112     public EntityBuilder setText(final String text) {
113         clearContent();
114         this.text = text;
115         return this;
116     }
117 
118     /**
119      * Returns entity content as a byte array if set using
120      * {@link #setBinary(byte[])} method.
121      */
122     public byte[] getBinary() {
123         return binary;
124     }
125 
126     /**
127      * Sets entity content as a byte array. This method is mutually exclusive with
128      * {@link #setText(String)},
129      * {@link #setStream(java.io.InputStream)} ,
130      * {@link #setSerializable(java.io.Serializable)} ,
131      * {@link #setParameters(java.util.List)},
132      * {@link #setParameters(org.apache.http.NameValuePair...)}
133      * {@link #setFile(java.io.File)} methods.
134      */
135     public EntityBuilder setBinary(final byte[] binary) {
136         clearContent();
137         this.binary = binary;
138         return this;
139     }
140 
141     /**
142      * Returns entity content as a {@link InputStream} if set using
143      * {@link #setStream(java.io.InputStream)} method.
144      */
145     public InputStream getStream() {
146         return stream;
147     }
148 
149     /**
150      * Sets entity content as a {@link InputStream}. This method is mutually exclusive with
151      * {@link #setText(String)},
152      * {@link #setBinary(byte[])},
153      * {@link #setSerializable(java.io.Serializable)} ,
154      * {@link #setParameters(java.util.List)},
155      * {@link #setParameters(org.apache.http.NameValuePair...)}
156      * {@link #setFile(java.io.File)} methods.
157      */
158     public EntityBuilder setStream(final InputStream stream) {
159         clearContent();
160         this.stream = stream;
161         return this;
162     }
163 
164     /**
165      * Returns entity content as a parameter list if set using
166      * {@link #setParameters(java.util.List)} or
167      * {@link #setParameters(org.apache.http.NameValuePair...)} methods.
168      */
169     public List<NameValuePair> getParameters() {
170         return parameters;
171     }
172 
173     /**
174      * Sets entity content as a parameter list. This method is mutually exclusive with
175      * {@link #setText(String)},
176      * {@link #setBinary(byte[])},
177      * {@link #setStream(java.io.InputStream)} ,
178      * {@link #setSerializable(java.io.Serializable)} ,
179      * {@link #setFile(java.io.File)} methods.
180      */
181     public EntityBuilder setParameters(final List<NameValuePair> parameters) {
182         clearContent();
183         this.parameters = parameters;
184         return this;
185     }
186 
187     /**
188      * Sets entity content as a parameter list. This method is mutually exclusive with
189      * {@link #setText(String)},
190      * {@link #setBinary(byte[])},
191      * {@link #setStream(java.io.InputStream)} ,
192      * {@link #setSerializable(java.io.Serializable)} ,
193      * {@link #setFile(java.io.File)} methods.
194      */
195     public EntityBuilder setParameters(final NameValuePair... parameters) {
196         return setParameters(Arrays.asList(parameters));
197     }
198 
199     /**
200      * Returns entity content as a {@link Serializable} if set using
201      * {@link #setSerializable(java.io.Serializable)} method.
202      */
203     public Serializable getSerializable() {
204         return serializable;
205     }
206 
207     /**
208      * Sets entity content as a {@link Serializable}. This method is mutually exclusive with
209      * {@link #setText(String)},
210      * {@link #setBinary(byte[])},
211      * {@link #setStream(java.io.InputStream)} ,
212      * {@link #setParameters(java.util.List)},
213      * {@link #setParameters(org.apache.http.NameValuePair...)}
214      * {@link #setFile(java.io.File)} methods.
215      */
216     public EntityBuilder setSerializable(final Serializable serializable) {
217         clearContent();
218         this.serializable = serializable;
219         return this;
220     }
221 
222     /**
223      * Returns entity content as a {@link File} if set using
224      * {@link #setFile(java.io.File)} method.
225      */
226     public File getFile() {
227         return file;
228     }
229 
230     /**
231      * Sets entity content as a {@link File}. This method is mutually exclusive with
232      * {@link #setText(String)},
233      * {@link #setBinary(byte[])},
234      * {@link #setStream(java.io.InputStream)} ,
235      * {@link #setParameters(java.util.List)},
236      * {@link #setParameters(org.apache.http.NameValuePair...)}
237      * {@link #setSerializable(java.io.Serializable)} methods.
238      */
239     public EntityBuilder setFile(final File file) {
240         clearContent();
241         this.file = file;
242         return this;
243     }
244 
245     /**
246      * Returns {@link ContentType} of the entity, if set.
247      */
248     public ContentType getContentType() {
249         return contentType;
250     }
251 
252     /**
253      * Sets {@link ContentType} of the entity.
254      */
255     public EntityBuilder setContentType(final ContentType contentType) {
256         this.contentType = contentType;
257         return this;
258     }
259 
260     /**
261      * Returns content encoding of the entity, if set.
262      */
263     public String getContentEncoding() {
264         return contentEncoding;
265     }
266 
267     /**
268      * Sets content encoding of the entity.
269      */
270     public EntityBuilder setContentEncoding(final String contentEncoding) {
271         this.contentEncoding = contentEncoding;
272         return this;
273     }
274 
275     /**
276      * Returns <code>true</code> if entity is to be chunk coded, <code>false</code> otherwise.
277      */
278     public boolean isChunked() {
279         return chunked;
280     }
281 
282     /**
283      * Makes entity chunk coded.
284      */
285     public EntityBuilder chunked() {
286         this.chunked = true;
287         return this;
288     }
289 
290     /**
291      * Returns <code>true</code> if entity is to be GZIP compressed, <code>false</code> otherwise.
292      */
293     public boolean isGzipCompress() {
294         return gzipCompress;
295     }
296 
297     /**
298      * Makes entity GZIP compressed.
299      */
300     public EntityBuilder gzipCompress() {
301         this.gzipCompress = true;
302         return this;
303     }
304 
305     private ContentType getContentOrDefault(final ContentType def) {
306         return this.contentType != null ? this.contentType : def;
307     }
308 
309     /**
310      * Creates new instance of {@link HttpEntity} based on the current state.
311      */
312     public HttpEntity build() {
313         final AbstractHttpEntity e;
314         if (this.text != null) {
315             e = new StringEntity(this.text, getContentOrDefault(ContentType.DEFAULT_TEXT));
316         } else if (this.binary != null) {
317             e = new ByteArrayEntity(this.binary, getContentOrDefault(ContentType.DEFAULT_BINARY));
318         } else if (this.stream != null) {
319             e = new InputStreamEntity(this.stream, 1, getContentOrDefault(ContentType.DEFAULT_BINARY));
320         } else if (this.parameters != null) {
321             e = new UrlEncodedFormEntity(this.parameters,
322                     this.contentType != null ? this.contentType.getCharset() : null);
323         } else if (this.serializable != null) {
324             e = new SerializableEntity(this.serializable);
325             e.setContentType(ContentType.DEFAULT_BINARY.toString());
326         } else if (this.file != null) {
327             e = new FileEntity(this.file, getContentOrDefault(ContentType.DEFAULT_BINARY));
328         } else {
329             e = new BasicHttpEntity();
330         }
331         if (e.getContentType() != null && this.contentType != null) {
332             e.setContentType(this.contentType.toString());
333         }
334         e.setContentEncoding(this.contentEncoding);
335         e.setChunked(this.chunked);
336         if (this.gzipCompress) {
337             return new GzipCompressingEntity(e);
338         }
339         return e;
340     }
341 
342 }