1 package com.atlassian.httpclient.api;
2
3 import java.io.InputStream;
4 import java.util.Map;
5
6 public interface Common<B extends Common<B>> {
7
8 /**
9 * Sets an HTTP header on this object. If the header's name is "Content-Type", the value
10 * will be parsed into this object's content type and content charset properties, as
11 * appropriate.
12 *
13 * @param name The name of the header to be set
14 * @param value The value of the header to be set
15 * @return This object, for builder-style chaining
16 */
17 B setHeader(String name, String value);
18
19 /**
20 * Copies the specified map of HTTP headers into this object. It will also parse any included
21 * Content-Type header into its constituent parts of IANA media type and content charset, updating
22 * those properties as appropriate.
23 *
24 * @param headers A map of HTTP headers
25 * @return This object, for builder-style chaining
26 */
27 B setHeaders(Map<String, String> headers);
28
29 /**
30 * Sets this object's entity stream from a string. Using this method of setting the entity
31 * automatically sets this object's content charset property to "UTF-8" if the entity is not null.
32 *
33 * @param entity An entity string
34 * @return This object, for builder-style chaining
35 */
36 B setEntity(String entity);
37
38 /**
39 * Sets this object's entity as an input stream. Invocations of this method reset this object's
40 * <code>hasReadEntity()</code> state to <code>false</code>. It is recommended to also set this
41 * object's content charset property when setting an entity stream for a textual media type (or
42 * using the overloaded form that takes both the entity stream and charset in the same call).
43 * Clients of this object should assume the HTTP standard of <code>ISO-8859-1 (latin-1)</code>
44 * for the content charset property if a textual media type is set but no explcit charset was
45 * provided for this message. A charset should NOT be provided for entity streams targetting
46 * binary media types.
47 *
48 * @param entityStream An entity input stream ready to be read
49 * @return This object, for builder-style chaining
50 */
51 B setEntityStream(InputStream entityStream);
52
53 /**
54 * Sets the charset for this object's entity, if any. This value is ignored during headeer access
55 * if no entity is present or if the content type property is not set.
56 *
57 * @param contentCharset The entity's charset value, or null
58 * @return This object, for builder-style chaining
59 */
60 B setContentCharset(String contentCharset);
61
62 /**
63 * Sets the IANA media type, for the current entity, if any. If the <code>contentType</code> argument
64 * also contains charset information, this method will have the side effect of parsing the charset
65 * out and storing the component parts independently. The method <code>getContentCharset()</code> can
66 * be used to retrieve extracted content charset, if present, and <code>getHeader("Content-Type")</code>
67 * can be used to retrieve the entire Content-Type header, complete with charset information, if set.
68 * The content type property is required when an entity is present.
69 *
70 * @param contentType An IANA media type with optional charset information
71 * @return This object, for builder-style chaining
72 */
73 B setContentType(String contentType);
74
75 /**
76 * Sets this object's entity as an input stream, encoded with the specified charset. Invocations of
77 * this method reset this object's <code>hasReadEntity()</code> state to <code>false</code>. This
78 * method should only be called for entity streams targetting textual media types -- that is, it's
79 * nonsensical to set the charset of an entity stream for binary media types (e.g. image/*, etc).
80 *
81 * @param entityStream An entity input stream ready to be read
82 * @param charset The charset in which the entity stream is encoded
83 * @return This object, for builder-style chaining
84 */
85 B setEntityStream(InputStream entityStream, String charset);
86 }