com.softwareag.mobile.runtime.toolkit.rest

Class AbstractMultipartRestOperation

java.lang.Object

com.softwareag.mobile.runtime.toolkit.operations.AbstractSynchronizableOperation

com.softwareag.mobile.runtime.toolkit.rest.AbstractRestOperation

com.softwareag.mobile.runtime.toolkit.rest.AbstractMultipartRestOperation

All Implemented Interfaces:

com.softwareag.mobile.runtime.comms.IConnectionCallback, IOperation

public abstract class AbstractMultipartRestOperation
extends AbstractRestOperation

The AbstractMultipartRestOperation is an extension of AbstractRestOperation that adds support for HTTP multipart POST or PUT requests. This is especially helpful for example to upload documents, pictures, etc. to HTTP backends. When using AbstractMultipartRestOperations you need to add "parts" to before calling AbstractRestOperation.execute(). A part can be either

• a raw byte[] in addBytePart(byte[], String, String, boolean)
• a path to a local file in addFilePart(String, String, String, boolean)
• an Image in addImageFilePart(Image, String, String, String, boolean)

For every part added to the mulitpart request you need to at least provide a Content-Type and field name to describe and identify the content of the part. When sending files, a filename is additionally required. Sample use of an AgileApps Live document picture upload:

 Image img = ...;
 UpdatePhotoRequest request = new UpdatePhotoRequest()
 request.addOperationDelegate(this);

 // Base64 encoding is optional
 request.addQueryParameter("isBase64Encoded", "true");

 StringBuffer xmlData = new StringBuffer();
 xmlData.append("<platform><record>\r\n");
 xmlData.append("<photo>photo.png</photo>\r\n");
 xmlData.append("</record></platform>\r\n");
 request.addBytePart(xmlData.toString().getBytes(), "__xml_data__",
                     "application/xml", false);

 request.addImageFilePart(img, "photo.png", "photo", "image/png", true);
 request.execute();
 

This will create a multipart request with the following request body:

 --------JcMVA2WSWXI4NYVuxny0nYd6XW81h_N6pD\r\n
 Content-Disposition: form-data; name="__xml_data__"\r\n
 Content-Type: application/xml\r\n
 \r\n
 <platform><record>\r\n
 <photo>photo.png</photo>\r\n
 </record></platform>\r\n

 --------JcMVA2WSWXI4NYVuxny0nYd6XW81h_N6pD
 Content-Disposition: form-data; name="photo"; filename="photo.png"
 Content-Type: image/png
 \r\n
 iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAIAAAACUFjqAAABQUlEQVR42g....\r\n
 --------JcMVA2WSWXI4NYVuxny0nYd6XW81h_N6pD--\r\n
 

AbstractMultipartRestOperation will automatically generate a boundary. You can set a custom boundary by using setBoundaryString(String) or setBoundaryPrefix(String) and setBoundaryLength(int).

Version:

10.3.0.0002-0443

Field Summary

Fields inherited from class com.softwareag.mobile.runtime.toolkit.operations.AbstractSynchronizableOperation

OPERATION_FAILED, OPERATION_SUCCESSFUL

Constructor Summary

Constructors

Constructor and Description
AbstractMultipartRestOperation()

Method Summary

Modifier and Type	Method and Description
boolean	addBytePart(byte[] content, java.lang.String fieldName, java.lang.String contentType, boolean encodeBase64) Adds a new part to the multipart request body by reading the data from a given content byte array of raw data.
boolean	addFilePart(byte[] content, java.lang.String fileName, java.lang.String fieldName, java.lang.String contentType, boolean encodeBase64) Adds a new part to the multipart request body by reading the data from a given content byte array of raw data.
boolean	addFilePart(java.lang.String fileName, java.lang.String fieldName, java.lang.String contentType, boolean encodeBase64) Adds a new part to the multipart request body by reading the data from a file that is part of the applications resources.
boolean	addImageFilePart(javax.microedition.lcdui.Image image, java.lang.String fileName, java.lang.String fieldName, java.lang.String contentType, boolean encodeBase64) Adds a new part to the multipart request body by reading the data from an Image instance.
int	getBoundaryLength() Returns the total length of the boundary String.
java.lang.String	getBoundaryPrefix() Returns the prefix used for generating the request boundary.
java.lang.String	getBoundaryString() Returns the boundary used by this AbstractMultipartRequest.
void	setBoundaryLength(int boundaryLength) Sets the new total length of the boundary for auto generation.
void	setBoundaryPrefix(java.lang.String boundaryPrefix) Sets a new prefix used for generating boundaries.
void	setBoundaryString(java.lang.String boundaryString) Sets the boundary to a new value.

Methods inherited from class com.softwareag.mobile.runtime.toolkit.rest.AbstractRestOperation

addHeaderParameter, addHeaderParameter, addHeaderParameter, addHeaderParameter, addQueryParameter, addQueryParameter, addQueryParameter, addQueryParameter, execute, getHeader, getHeaderParameters, getHTTPMethod, getHttpResponse, getPostData, getQueryParameters, getUrl, isExecuteAsynchronous, onResponse, reset, setExecuteAsynchronous, setHttpMethod, setPostData, setPostData, setResponse, setUrl, toString

Methods inherited from class com.softwareag.mobile.runtime.toolkit.operations.AbstractSynchronizableOperation

addOperationDelegate, getOperationDelegates, getResponse, removeOperationDelegate, setCacheHandler, setResponse

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AbstractMultipartRestOperation

public AbstractMultipartRestOperation()

Method Detail

addFilePart

public boolean addFilePart(java.lang.String fileName,
                           java.lang.String fieldName,
                           java.lang.String contentType,
                           boolean encodeBase64)
                    throws java.io.IOException

Adds a new part to the multipart request body by reading the data from a file that is part of the applications resources.

Parameters:

fileName - the name of the file to read from the applications resources

fieldName - the name of the field used in Content-Disposition name attribute

contentType - the content type of the data contained in the part being added

encodeBase64 - true if the data must be added Base64 encoded, false if the data will be transferred raw (as is)

Returns:

true if the part was successfully added to the HTTP request body, false if there was an error.

Throws:

java.io.IOException - if writing to the request body fails.

addImageFilePart

public boolean addImageFilePart(javax.microedition.lcdui.Image image,
                                java.lang.String fileName,
                                java.lang.String fieldName,
                                java.lang.String contentType,
                                boolean encodeBase64)
                         throws java.io.IOException

Adds a new part to the multipart request body by reading the data from an Image instance.

The image data itself will be encoded depending on the contentType before added to the request body. Currently only image/png is supported by default. If you need to do other image encodings, encode the image data and use addFilePart(byte[], String, String, String, boolean)

When adding an Image a fileName must be provided as it is expected that we are doing a file upload.

Parameters:

image - the Image instance to be encoded and added to the request body

fileName - the name of the image file used in Content-Disposition filename attribute

fieldName - the name of the field used in Content-Disposition name attribute

contentType - the content type of the data contained in the part being added. Currently only image/png is supported

encodeBase64 - true if the data must be added Base64 encoded, false if the data will be transferred raw (as is)

Returns:

true if the part was successfully added to the HTTP request body, false if there was an error.

Throws:

java.io.IOException - if writing to the request body fails.

addFilePart

public boolean addFilePart(byte[] content,
                           java.lang.String fileName,
                           java.lang.String fieldName,
                           java.lang.String contentType,
                           boolean encodeBase64)
                    throws java.io.IOException

Adds a new part to the multipart request body by reading the data from a given content byte array of raw data. A fileName must be provided as the data is added as a file.

Parameters:

content - the raw data byte array to be added to the request body

fileName - the name of the file used in Content-Disposition filename attribute

fieldName - the name of the field used in Content-Disposition name attribute

contentType - the content type of the data contained in the part being added. Currently only image/png is supported

encodeBase64 - true if the data must be added Base64 encoded, false if the data will be transferred raw (as is)

Returns:

true if the part was successfully added to the HTTP request body, false if there was an error.

Throws:

java.io.IOException - if writing to the request body fails.

addBytePart

public boolean addBytePart(byte[] content,
                           java.lang.String fieldName,
                           java.lang.String contentType,
                           boolean encodeBase64)
                    throws java.lang.Exception

Adds a new part to the multipart request body by reading the data from a given content byte array of raw data. The data represents the value of the given fieldName attribute and is not considered to be a file.

Parameters:

content - the raw data byte array to be added to the request body

fieldName - the name of the field used in Content-Disposition name attribute

contentType - the content type of the data contained in the part being added. Currently only image/png is supported

encodeBase64 - true if the data must be added Base64 encoded, false if the data will be transferred raw (as is)

Returns:

true if the part was successfully added to the HTTP request body, false if there was an error.

Throws:

java.lang.Exception - if writing to the request body fails.

getBoundaryString

public java.lang.String getBoundaryString()

Returns the boundary used by this AbstractMultipartRequest. If the boundary is null a new random boundary will be created and returned. You can use setBoundaryString(String) to set a custom boundary. The generation of a boundary uses getBoundaryPrefix() and getBoundaryLength().

Returns:

the boundary used by the request as String

setBoundaryString

public void setBoundaryString(java.lang.String boundaryString)

Sets the boundary to a new value. You do not need to set the boundary manually as it will be generated automatically. Use this method only if you want to provide a custom boundary.

Make sure to not change the boundary after adding the first part to the request. The boundary must be the same for all parts!

Parameters:

boundaryString - new boundary to be used in the request and must be HTTP conform

getBoundaryPrefix

public java.lang.String getBoundaryPrefix()

Returns the prefix used for generating the request boundary.

Returns:

the boundary prefix as String

setBoundaryPrefix

public void setBoundaryPrefix(java.lang.String boundaryPrefix)

Sets a new prefix used for generating boundaries. This might not actually change the boundary if called to late. Make sure to set a new prefix before adding the first part to the request.

Parameters:

boundaryPrefix - the new prefix used to generated the request boundary as String

getBoundaryLength

public int getBoundaryLength()

Returns the total length of the boundary String. The max value is 70 as defined in the HTTP standard.

Returns:

the total length of the boundary String including the boundary prefix

setBoundaryLength

public void setBoundaryLength(int boundaryLength)

Sets the new total length of the boundary for auto generation. This might not actually change the boundary if called to late. Make sure to set the new length before adding the first part to the request.

Parameters:

boundaryLength - the new total length of the auto generated boundary including prefix