public final class PostRequest extends Object
This class will automatically format the body of the request as
"application/x-www-form-urlencoded" or as
"multipart/form-data" depending on the types, String or
FileContent
, of the parameters added to the request object.
This class is typically used as follows:
PostRequest req = new PostRequest(); req.addParameter("_charset_", ""); req.addParameter("person", "John X Doe"); req.addParameter("photo", new FileContentImpl(new File("photos/john_x_doe.jpg"))); HttpURLConnection connection = req.post(url); checkResponse(connection);
IMPORTANT:
if the name of an <input> element of type "hidden" is
"_charset_"
, the input's value is automatically set
by the user agent (here PostRequest
) to the
character encoding being used to submit the form (here specified using
setCharacterEncoding(java.lang.String)
).
Modifier and Type | Class and Description |
---|---|
static class |
PostRequest.Header
A header.
|
static class |
PostRequest.Parameter
A parameter.
|
Modifier and Type | Field and Description |
---|---|
static String |
DEFAULT_CHAR_ENCODING
The character encoding returned by default by
getCharacterEncoding() . |
Constructor and Description |
---|
PostRequest()
Constructs a PostRequest having no parameters.
|
Modifier and Type | Method and Description |
---|---|
void |
addHeader(String name,
String value)
Convenience method: append specified header to the header list.
|
void |
addParameter(String name,
Object value)
Convenience method: append specified parameter to the parameter list.
|
static int |
checkResponse(HttpURLConnection connection)
Convenience function: throws an IOException having a detailed
error message if the service returns a response code greater
or equal to 300.
|
String |
getCharacterEncoding()
Returns the form submission encoding.
|
List<PostRequest.Header> |
getHeaderList()
Returns the header list.
|
List<PostRequest.Parameter> |
getParameterList()
Returns the parameter list.
|
boolean |
isMultipartRequest()
Returns
true if the body of the request will be formatted
using the "multipart/form-data" encoding algorithm;
false if it will be formatted using
the "application/x-www-form-urlencoded" encoding algorithm. |
static String |
loadTextResponse(HttpURLConnection connection,
String defaultCharset)
Convenience function: reads the text body of the response
to the POST request.
|
static void |
main(String[] args)
A HTTP POST command-line utility.
|
static HttpURLConnection |
openConnection(URL url)
Low-level helper: opens a connection to the service having
specified URL.
|
HttpURLConnection |
post(URL url)
Post this request to the service having specified URL.
|
static void |
saveResponse(HttpURLConnection connection,
File saveDir,
String baseName)
Convenience function: saves to specified file the response
to the POST request.
|
void |
setCharacterEncoding(String encoding)
Specifies the character encoding used to escape accented characters
in "application/x-www-form-urlencoded".
|
public static final String DEFAULT_CHAR_ENCODING
getCharacterEncoding()
. By default, it's "UTF-8".public void addParameter(String name, Object value)
name
- name of the parametervalue
- value of the parameter.
Generally a FileContent
or a String. Any other kind of object
will be transmitted as a String by using value.toString()
.
getParameterList()
public List<PostRequest.Parameter> getParameterList()
public boolean isMultipartRequest()
true
if the body of the request will be formatted
using the "multipart/form-data" encoding algorithm;
false
if it will be formatted using
the "application/x-www-form-urlencoded" encoding algorithm.public void addHeader(String name, String value)
name
- name of the headervalue
- value of the headergetHeaderList()
public List<PostRequest.Header> getHeaderList()
public void setCharacterEncoding(String encoding)
encoding
- specifies the form submission encoding; for example
"ISO-8859-1" or "UTF-8".
Specifying null
is equivalent to resetting the encoding
to the default value.
Important:encoding must be an ASCII-compatible character encoding.
getCharacterEncoding()
,
DEFAULT_CHAR_ENCODING
public String getCharacterEncoding()
public HttpURLConnection post(URL url) throws IOException
Will automatically format the body of the request as
"application/x-www-form-urlencoded" or as
"multipart/form-data" depending on the types, String or
FileContent
, of the parameters added to the request object.
url
- http: or http: URL of the serviceIOException
- if an I/O problem or a network problem occursaddParameter(java.lang.String, java.lang.Object)
public static HttpURLConnection openConnection(URL url) throws IOException
url
- http: or http: URL of the serviceIOException
- if a network problem occurspublic static int checkResponse(HttpURLConnection connection) throws IOException
connection
- connection to the serviceIOException
- if an I/O problem or a network problem occurspost(java.net.URL)
public static String loadTextResponse(HttpURLConnection connection, String defaultCharset) throws IOException
Expects the tContent-Type header of the response to start with "text/". Examples: "text/plain", "text/html", etc.
connection
- connection to the servicedefaultCharset
- which charset to use when this is not
specified in the response.
May be null
in which the platform native encoding is used.null
if
there is no body or if the body does not contain textIOException
- if an I/O problem or a network problem occurspublic static void saveResponse(HttpURLConnection connection, File saveDir, String baseName) throws IOException
connection
- connection to the servicesaveDir
- the save directorybaseName
- a default basename for the save file.
Specify null
to obtain this basename from the
Content-Disposition header possibly contained in the response.
IOException
- if an I/O problem or a network problem occurspublic static void main(String[] args)