hu.scelightapi.util.httppost

Interface IHttpPost

All Superinterfaces:

java.lang.AutoCloseable

public interface IHttpPost
extends java.lang.AutoCloseable

An interface that allows interaction with standard HTTP servers using the POST method.

Parameters are sent as if they would be part of an HTML form. The content-type ("Content-Type" request property) of the request will be set to "application/x-www-form-urlencoded;charset=UTF-8".

Its usefulness includes -but is not limited to- uploading/downloading files without having to use Multi-part requests. The following examples will demonstrate these.

Instances can be acquired by IFactory.newHttpPost(java.net.URL, java.util.Map).

Example #1: Upload a file encoded with Base64:

 

 String url = "http://some.site.com/upload";
 Path file = Paths.get( "c:/downloads/mine.txt" );
 Map< String, String > paramsMap = new HashMap< String, String >();
 paramsMap.put( "fileName", file.getFileName().toString() );
 try {
        paramsMap.put( "fileBase64", utils.toBase64String( Files.readAllBytes( file ) ) );
 } catch ( IOException ie ) {
 }
 // Add other parameters you need...
 paramsMap.put( "someOtherThing", "some other value" );
 
 try ( IHttpPost httpPost = factory.newHttpPost( url, paramsMap ) ) {
        if ( httpPost.connect() ) {
                if ( httpPost.doPost() )
                        logger.info( "File sent successfully, server response: " + httpPost.getResponse() );
                else
                        logger.error( "Failed to send file!" );
        } else
                logger.error( "Failed to connect!" );
 } catch ( Exception e ) {
        logger.error( "Unexpected file upload error!", e );
 }
 
 

Example #2: Download a file from a server:

 

 String url = "http://some.site.com/download";
 Map< String, String > paramsMap = new HashMap< String, String >();
 String fileName = "somefile.txt";
 paramsMap.put( "fileName", fileName );
 // Add other parameters you need...
 paramsMap.put( "userId", "someUserId" );
 
 try ( IHttpPost httpPost = factory.newHttpPost( url, paramsMap ) ) {
        if ( httpPost.connect() ) {
                if ( httpPost.doPost() ) {
                        // Note: we could simply acquire a suitable file provider by:
                        // factory.newSimpleFileProvider( Paths.get( "c:/downloads", fileName ), null );
                        // but this is to demonstrate the use and possibilities of IFileProvider
                        boolean result = httpPost.saveAttachmentToFile( new IFileProvider() {
                                public Path getFile( HttpURLConnection httpUrlConnection ) {
                                        Path file = Paths.get( "c:/downloads", fileName );
                                        logger.info( "Saving file to: " + file );
                                        return file;
                                }
                                
                                public Long getLastModified( HttpURLConnection httpUrlConnection ) {
                                        // We assume here that the server sends the file last modified value as a header field named "X-file-date":
                                        String fileDateString = httpUrlConnection.getHeaderField( "X-file-date" );
                                        return fileDateString == null ? null : Long.valueOf( fileDateString );
                                }
                        } );
                        if ( result )
                                logger.info( "Attachment saved successfully to file: " + file );
                } else
                        logger.error( "Failed to send request!" );
        } else
                logger.error( "Failed to connect!" );
 } catch ( Exception e ) {
        logger.error( "Unexpected file download error!", e );
 }
 
 

Author:

Andras Belicza

See Also:

IFactory.newHttpPost(java.net.URL, java.util.Map)

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	DEFAULT_CHARSET Default charset to be used.

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Closes this IHttpPost, releases all allocated resources.
boolean	connect() Connects to the provided URL.
boolean	connect(java.lang.Runnable beforeConnectionConnectTask) Connects to the provided URL.
boolean	doPost() Posts the parameters to the server.
java.net.HttpURLConnection	getConnection() Returns the underlying HttpURLConnection.
java.lang.String	getRequestCharset() Returns the charset of the request.
java.lang.String	getResponse() Gets the response from the server.
java.util.List<java.lang.String>	getResponseLines() Gets the response from the server as a list of lines.
int	getServerResponseCode() Returns the HTTP response code of the server.
java.lang.String	getServerResponseMessage() Returns the HTTP response message of the server.
State	getState() Returns the internal state of the connection/communication.
boolean	isInternalStateCheckingEnabled() Tells if internal state checking is enabled.
boolean	isServerResponseOk() Tells if the the HTTP response code is OK (HTTP 200).
boolean	saveAttachmentToFile(IFileProvider fileProvider, byte[]... buffer) Saves the attachment of the response, the content is treated as application/octet-stream.
void	setInternalStateCheckingEnabled(boolean enabled) Sets whether internal state checking should be performed.
void	setRequestCharset(java.lang.String charset) Sets the charset of the request.
void	setRequestProperty(java.lang.String key, java.lang.String value) Sets a request property.

Field Detail

DEFAULT_CHARSET

static final java.lang.String DEFAULT_CHARSET

Default charset to be used.

See Also:

Constant Field Values

Method Detail

setInternalStateCheckingEnabled

void setInternalStateCheckingEnabled(boolean enabled)

Sets whether internal state checking should be performed.

You may want to disable internal state checking if you want to tweak the HttpURLConnection.

Parameters:

enabled - the internal state checking value to be set

isInternalStateCheckingEnabled

boolean isInternalStateCheckingEnabled()

Tells if internal state checking is enabled. Internal state checking is enabled by default.

Returns:

true if internal state checking is enabled; false otherwise

getState

State getState()

Returns the internal state of the connection/communication.

Returns:

the internal state of the connection/communication

setRequestCharset

void setRequestCharset(java.lang.String charset)
                       throws java.lang.IllegalStateException

Sets the charset of the request.

This will set the request property "Accept-Charset" to charset.

It must be called before connect(). If charset is not set, the DEFAULT_CHARSET will be used.

Parameters:

charset - charset of the request to be set

Throws:

java.lang.IllegalStateException - if internal state checking is enabled and the internal state is not State.NOT_CONNECTED

getRequestCharset

java.lang.String getRequestCharset()

Returns the charset of the request. The default charset of the request is DEFAULT_CHARSET.

Returns:

the charset of the request

setRequestProperty

void setRequestProperty(java.lang.String key,
                      java.lang.String value)
                        throws java.lang.IllegalStateException

Sets a request property.

The properties will be passed to the underlying HttpURLConnection before it's connect() method is called.

It must be called before connect().

Parameters:

key - the property key

value - the property value

Throws:

java.lang.IllegalStateException - if internal state checking is enabled and the internal state is not State.NOT_CONNECTED

getConnection

java.net.HttpURLConnection getConnection()

Returns the underlying HttpURLConnection.

This method may return null if called before connect() or if called when connect() returned false.

Returns:

the underlying HttpURLConnection

connect

boolean connect()
                throws java.lang.IllegalStateException

Connects to the provided URL.

Only one connect method (connect() or connect(Runnable)) can be called and only once.

Returns:

true if connection was successful; false otherwise

Throws:

java.lang.IllegalStateException - if internal state checking is enabled and the internal state is not State.NOT_CONNECTED

See Also:

connect(Runnable)

connect

boolean connect(java.lang.Runnable beforeConnectionConnectTask)
                throws java.lang.IllegalStateException

Connects to the provided URL.

Only one connect method (connect() or connect(Runnable)) can be called and only once.

Parameters:

beforeConnectionConnectTask - task to be executed right before calling URLConnection.connect()

Returns:

true if connection was successful; false otherwise

Throws:

java.lang.IllegalStateException - if internal state checking is enabled and the internal state is not State.NOT_CONNECTED

See Also:

connect()

doPost

boolean doPost()
               throws java.lang.IllegalStateException

Posts the parameters to the server.

The parameters will be encoded using the charset set by setRequestCharset(String) (defaults to "UTF-8" ).

Can only be called if connect() returned true.

Returns:

true if the operation was successful; false otherwise

Throws:

java.lang.IllegalStateException - if internal state checking is enabled and the internal state is not State.CONNECTED

isServerResponseOk

boolean isServerResponseOk()
                           throws java.lang.IllegalStateException

Tells if the the HTTP response code is OK (HTTP 200).

Can only be called after doPost() and before close().

Returns:

true if the the HTTP response code is OK; false otherwise

Throws:

java.lang.IllegalStateException - if internal state checking is enabled and doPost() has not been called or close() has been called

See Also:

getServerResponseCode(), getServerResponseMessage()

getServerResponseCode

int getServerResponseCode()
                          throws java.lang.IllegalStateException

Returns the HTTP response code of the server.

Can only be called after doPost() and before close().

Returns:

the HTTP response code of the server

Throws:

java.lang.IllegalStateException - if internal state checking is enabled and doPost() has not been called or close() has been called

See Also:

isServerResponseOk(), getServerResponseMessage()

getServerResponseMessage

java.lang.String getServerResponseMessage()
                                          throws java.lang.IllegalStateException

Returns the HTTP response message of the server.

Can only be called after doPost() and before close().

Returns:

the HTTP response code of the server

Throws:

java.lang.IllegalStateException - if internal state checking is enabled and doPost() has not been called or close() has been called

See Also:

isServerResponseOk(), getServerResponseCode()

getResponse

java.lang.String getResponse()
                             throws java.lang.IllegalStateException

Gets the response from the server.

Can only be called after doPost().

If the server returned an error, this will return the error page provided by the server.

Returns:

the server response, or null if error occurred

Throws:

java.lang.IllegalStateException - if internal state checking is enabled and the internal state is not State.REQUEST_SENT

See Also:

getResponseLines(), saveAttachmentToFile(IFileProvider, byte[][])

getResponseLines

java.util.List<java.lang.String> getResponseLines()
                                                  throws java.lang.IllegalStateException

Gets the response from the server as a list of lines.

Can only be called after doPost().

If the server returned an error, this will return the error page provided by the server.

Returns:

the server response as a list of lines, or null if error occurred

Throws:

java.lang.IllegalStateException - if internal state checking is enabled and the internal state is not State.REQUEST_SENT

See Also:

getResponse(), saveAttachmentToFile(IFileProvider, byte[][])

saveAttachmentToFile

boolean saveAttachmentToFile(IFileProvider fileProvider,
                           byte[]... buffer)
                             throws java.lang.IllegalStateException

Saves the attachment of the response, the content is treated as application/octet-stream.

Can only be called if doPost() returned true.

A IFileProvider is used to get a file to save the attachment to.

Parameters:

fileProvider - file provider to specify a file to save to

buffer - optional buffer to use for IO read/write operations

Returns:

true if the attachment was saved successfully; false otherwise

Throws:

java.lang.IllegalStateException - if internal state checking is enabled and the internal state is not State.REQUEST_SENT

See Also:

IFileProvider, IFactory.newSimpleFileProvider(java.nio.file.Path, Long), getResponse(), getResponseLines()

close

void close()

Closes this IHttpPost, releases all allocated resources.

Specified by:

close in interface java.lang.AutoCloseable