1 package com.atlassian.httpclient.api;
2
3 import com.atlassian.fugue.Option;
4
5 import java.io.InputStream;
6 import java.util.Map;
7
8 /**
9 * An abstract base class for HTTP messages (i.e. Request and Response) with support for
10 * header and entity management.
11 */
12 public interface Message {
13 /**
14 * Returns the IANA media type, minus charset information, for the current entity, if any.
15 * To access charset information, use <code>getContentCharset()</code>. To get the full
16 * Content-Type header value including charset if specified, use <code>getHeader("Content-Type")</code>.
17 *
18 * @return An IANA media type, or null
19 */
20 String getContentType();
21
22 /**
23 * Returns the currently set content charset value, if any.
24 *
25 * @return The current content charset
26 */
27 String getContentCharset();
28
29 /**
30 * Returns the current entity as an input stream, or null if not set. Use <code>hasEntity()</code>
31 * to check if this message has an entity value.
32 *
33 * @return An input stream for the current entity, or null if not set
34 * @throws IllegalStateException If the non-null entity has already been accessed once, through
35 * any accessor for this object
36 */
37 InputStream getEntityStream() throws IllegalStateException;
38
39 /**
40 * Returns the current entity in <code>String</code> form, if available, converting the underlying
41 * entity stream to a string using the currently set content charset, or defaulting to the HTTP
42 * standard of "ISO-8859-1" if no content charset has been specified.
43 *
44 * @return The entity string, or null if no entity has been set
45 * @throws IllegalStateException If the non-null entity has already been accessed once, through
46 * any accessor for this object. Also thrown if underlying body cannot be converted into a String
47 * @throws IllegalArgumentException If the entity exceeds the maximum size
48 */
49 String getEntity() throws IllegalStateException, IllegalArgumentException;
50
51 /**
52 * Returns whether or not an entity has been set on this object. Use this instead of calling
53 * an entity getter to test for presence of an entity, as the getters will affect this object's
54 * <code>hasReadEntity()</code> state.
55 *
56 * @return This object, for builder-style chaining
57 */
58 boolean hasEntity();
59
60 /**
61 * Returns whether or not the current entity property, if any, has been read from this object.
62 * If this method returns true, any further calls to entity property accessors on this object
63 * will result in an {@link IllegalStateException} being thrown.
64 *
65 * @return True if the entity has already been read
66 */
67 boolean hasReadEntity();
68
69 /**
70 * Returns a map of all headers that have been set on this object. If the content type property
71 * has been set, a full "Content-Type" header including content charset, if set, is generated as
72 * part of this map.
73 *
74 * @return The headers map
75 */
76 Map<String, String> getHeaders();
77
78 /**
79 * Returns the specified header by name. If "Content-Type" is requested, the value will be
80 * constructed from this object's content type and content charset properties, if set and
81 * as appropriate.
82 *
83 * @param name The name of the header to fetch
84 * @return The value of the named header, or null if not set
85 */
86 String getHeader(String name);
87
88 /**
89 * Returns the content length for the entity in the message. For requests, this would be the content length of the
90 * entity that you set, or the content length that you can set manually (e.g. for streamed entities). For responses,
91 * this would be the content length from the header.
92 *
93 * @return The content length as an option. None is returned if no content length has been set or not present.
94 */
95 Option<Long> getContentLength();
96 }