HTTPRequest (jShred Util 19 API)

java.lang.Object
- net.shredzone.jshred.net.HTTPRequest

```
public class HTTPRequest
extends Object
```
This class sends a HTTP request to a server, and returns an InputStream to the returned data.
All kind of parameters can be added to the request using addParameter(String, Object).
Example:
```
 HTTPRequest req = new HTTPRequest(url, HTTPRequest.POST);
 req.addParameter("user", username);
 req.addParameter("email", email);
 req.doRequest();
 Reader input = req.getContentReader();
 
```
All parameters will be sent UTF-8 encoded, as proposed by W3C.
GET requests are limited in their length. This class will not take care to keep within the allowed length. If you are in doubt, you should use POST request.
It is possible to pass a ProgressMonitor which will be used to show how many data has been transfered to the server. This is especially useful for file uploads.
Author:

Richard "Shred" Körber

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`HTTPRequest.DataProvider` A DataProvider provides a data stream to be sent by the `HTTPRequest`.
`static class`	`HTTPRequest.FileProvider` This `HTTPRequest.DataProvider` implementation uploads a `File` to the server.
`static class`	`HTTPRequest.InputStreamProvider` This `HTTPRequest.DataProvider` implementation transmits the given `InputStream`.
`static class`	`HTTPRequest.Method`

Constructor Summary

Constructors
Constructor and Description
`HTTPRequest(URL url)` Creates a new HTTPRequest using method GET.
`HTTPRequest(URL url, HTTPRequest.Method method)` Creates a new HTTPRequest.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addDataProvider(String name, HTTPRequest.DataProvider provider)` Adds a `HTTPRequest.DataProvider` to the HTTPRequest.
`void`	`addFile(String name, File file)` Adds a `File` to the HTTPRequest.
`void`	`addFile(String name, File file, String mimetype)` Adds a `File` to the HTTPRequest.
`void`	`addParameter(String name, boolean value)` Convenience call to add a boolean parameter to the HTTPRequest.
`void`	`addParameter(String name, Object value)` Adds a parameter to the HTTPRequest.
`int`	`doRequest()` Sends the request to the server.
`String`	`getCharset()` Gets the charset of the response.
`HttpURLConnection`	`getConnection()` Returns the `HttpURLConnection` object after `doRequest()` has been invoked.
`Reader`	`getContentReader()` Returns a `Reader` to the response body after a `doRequest()`.
`HTTPRequest.Method`	`getMethod()` Returns the method this request is sent with.
`InputStream`	`getResult()` Returns the server's response in an `InputStream` after a `doRequest()`.
`boolean`	`isPost()` Returns true if this request uses the POST method.
`void`	`setProgressMonitor(ProgressMonitor monitor, String transfer)` Defines a `ProgressMonitor` for the transmission process.
`void`	`setProgressMonitor(ProgressMonitor monitor, String transfer, int min, int max)` Defines a `ProgressMonitor` for the transmission process.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - HTTPRequest
```
public HTTPRequest(URL url)
```
    Creates a new HTTPRequest using method GET.
    
    Parameters:
    
    url - Target URL for the request.
  - HTTPRequest
```
public HTTPRequest(URL url,
                   HTTPRequest.Method method)
```
    Creates a new HTTPRequest.
    
    Parameters:
    
    url - Target URL for the request.
    
    method - HTTPRequest.Method: GET or POST
- Method Detail
  - addParameter
```
public void addParameter(String name,
                         Object value)
```
    Adds a parameter to the HTTPRequest. The Object.toString() result of the value is transferred to the server. The value is evaluated when doRequest() is invoked, NOT at the time you pass the parameter here. Keep this in mind!
    If a null was passed as value, the parameter will not be sent at all.
    Note that a parameter can only be passed once. If you add it again, it will replace the previous parameter with the same name. Also take care not to exceed the limits of a GET request. Use POST if you are in doubt.
    HTTPRequest will take care for proper encoding of the parameter names and values. You won't need to urlencode them.
    
    Parameters:
    
    name - Parameter name
    
    value - Parameter value, may be null
  - addParameter
```
public void addParameter(String name,
                         boolean value)
```
    Convenience call to add a boolean parameter to the HTTPRequest. If the boolean value is false, no parameter will be sent at all. If the boolean value is true, a "1" is transferred as parameter value to the server. This method somehow simulates a HTML checkbox.
    
    Parameters:
    
    name - Parameter name
    
    value - Parameter value
  - addFile
```
public void addFile(String name,
                    File file)
             throws FileNotFoundException
```
    Adds a File to the HTTPRequest. You must use POST requests in order to upload files to the server. The file will be sent using the mime type "application/octet-stream". The file is not kept in memory, but sent using a data stream during transmission, so HTTPRequest is also able to upload large files with a small memory print.
    
    Parameters:
    
    name - Parameter name
    
    file - File to be sent
    
    Throws:
    
    FileNotFoundException
  - addFile
```
public void addFile(String name,
                    File file,
                    String mimetype)
             throws FileNotFoundException
```
    Adds a File to the HTTPRequest. You must use POST requests in order to upload files to the server. The file is not kept in memory, but sent using a data stream during transmission, so HTTPRequest is also able to upload large files.
    
    Parameters:
    
    name - Parameter name
    
    file - File to be sent
    
    mimetype - Mime type of the file to be transmitted
    
    Throws:
    
    FileNotFoundException
  - addDataProvider
```
public void addDataProvider(String name,
                            HTTPRequest.DataProvider provider)
```
    Adds a HTTPRequest.DataProvider to the HTTPRequest. You must use POST requests in order to upload files to the server. The file is not kept in memory, but sent using a data stream during transmission, so HTTPRequest is also able to upload large files.
    
    Parameters:
    
    name - Parameter name
    
    provider - HTTPRequest.DataProvider of the data to be uploaded
  - getMethod
```
public HTTPRequest.Method getMethod()
```
    Returns the method this request is sent with.
    
    Returns:
    
    true:POST, false:GET
  - isPost
```
public boolean isPost()
```
    Returns true if this request uses the POST method.
    
    Returns:
    
    true: uses POST method
  - setProgressMonitor
```
public void setProgressMonitor(ProgressMonitor monitor,
                               String transfer)
```
    Defines a ProgressMonitor for the transmission process. After doRequest() connected to the server, the transfer string is shown as a note.
    The ProgressMonitor will start at the left corner during start of transmission, and will end in the right corner of the gauge.
    
    Parameters:
    
    monitor - ProgressMonitor to be used.
    
    transfer - Message to be shown after connection.
  - setProgressMonitor
```
public void setProgressMonitor(ProgressMonitor monitor,
                               String transfer,
                               int min,
                               int max)
```
    Defines a ProgressMonitor for the transmission process. After doRequest() connected to the server, the transfer string is shown as a note. During transmission, a value between min and max is shown according to the process of the transmission. After transmission, max will always be the current value of the ProgressMonitor.
    You can use min and max if the HTTPRequest is just one step in a chain of several steps to be shown in the ProgressMonitor.
    Note that the response transfer is not included in the ProgressMonitor. This is because there is no way to find out the response size from the server before the request has been entirely sent to it.
    
    Parameters:
    
    monitor - ProgressMonitor to be used.
    
    transfer - Message to be shown after connection.
    
    min - Minimum value during transmission
    
    max - Maximum value at the end of transmission
  - doRequest
```
public int doRequest()
              throws IOException,
                     MalformedURLException
```
    Sends the request to the server. You cannot reuse the request after it has been sent. If you have previously set a ProgressMonitor, it will be used.
    
    Returns:
    
    Return code of the server, see HttpURLConnection
    
    Throws:
    
    IOException - IO exception
    
    MalformedURLException - URL was malformed
  - getConnection
```
public HttpURLConnection getConnection()
```
    Returns the HttpURLConnection object after doRequest() has been invoked.
    
    Returns:
    
    HttpURLConnection or null if doRequest() was not invoked yet.
  - getResult
```
public InputStream getResult()
                      throws IOException
```
    Returns the server's response in an InputStream after a doRequest().
    
    Returns:
    
    InputStream of the server's response.
    
    Throws:
    
    IOException - if the InputStream could not be opened.
    
    Since:
    
    R13
  - getCharset
```
public String getCharset()
```
    Gets the charset of the response. This method will try to evaluate the "ContentType" header. If there was no such header, or if it did not contain a charset, null is returned.
    
    Returns:
    
    Charset of the response, or null
    
    Since:
    
    R4
  - getContentReader
```
public Reader getContentReader()
                        throws UnsupportedEncodingException,
                               IOException
```
    Returns a Reader to the response body after a doRequest(). The content charset sent by the server is used. If the given charset is not known, an exception will be raised. If no charset was given, "ISO-8859-1" is assumed.
    
    Returns:
    
    Reader to the response body.
    
    Throws:
    
    UnsupportedEncodingException - if the encoding given by the server, is not known to this Java platform.
    
    IOException - if an I/O exception occured
    
    Since:
    
    R4

Class HTTPRequest

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

HTTPRequest

HTTPRequest

Method Detail

addParameter

addParameter

addFile

addFile

addDataProvider

getMethod

isPost

setProgressMonitor

setProgressMonitor

doRequest

getConnection

getResult

getCharset

getContentReader