OrdHttpUploadFormData Class

This section presents reference information on the methods of the oracle.ord.im.OrdHttpUploadFormData class.

File uploading using HTML forms encodes form data and uploaded files in POST requests using the multipart/form-data format. The OrdHttpUploadFormData class facilitates the processing of such requests by parsing the POST data and making the contents of regular form fields and uploaded files readily accessible to a Java servlet or JSP page. The OrdHttpUploadFormData class provides methods to access text-based form field parameters that are identical to the getParameter( ), getParameterValues( ), and getParameterNames( ) methods provided by the ServletRequest class. Access to uploaded files is provided by a similar set of methods, namely getFileParameter( ), getFileParameterValues( ), and getFileParameterNames( ). The OrdHttpUploadFile objects returned by the getFileParameter( ) and getFileParameterValues( ) methods provide simple access to the MIME type, length, and contents of each uploaded file.

For more information on the OrdHttpUploadFile class, see OrdHttpUploadFile Class.

The following is an example of how to use the OrdHttpUploadFormData class:

// Create an OrdHttpUploadFormData object and use it to parse the

// multipart/form-data message.

//

OrdHttpUploadFormData formData = new OrdHttpUploadFormData( request );

formData.parseFormData( );


// Get the description, location, and photograph.

//

String id = formData.getParameter("id");

String description = formData.getParameter("description");

String location = formData.getParameter("location");

OrdHttpUploadFile photo = formData.getFileParameter("photo");


// Prepare and execute a SQL statement to insert a new row into

// the table and return the sequence number for the new row.

// Disable auto-commit to allow the LOB to be written correctly.

//

conn.setAutoCommit(false);

PreparedStatement stmt = conn.prepareStatement("insert into photo_album (id, 

     description, location, photo) " + " values (?, ?, ?, ORDSYS.ORDIMAGE.INIT( ))");

stmt.setString(1, id);

stmt.setString(2, description);

stmt.setString(3, location);

stmt.executeUpdate( );


// Prepare and execute a SQL statement to fetch the new OrdImage

// object from the database.

//

stmt = conn.prepareStatement("select photo from photo_album where id = ? for 

     update");

stmt.setString(1, id);

OracleResultSet rset = (OracleResultSet)stmt.executeQuery( );

if (!rset.next( )){

     throw new ServletException("new row not found in table");

}

OrdImage media = (OrdImage)rset.getORAData(1, OrdImage.getORADataFactory( ));


// Load the photograph into the database and set the properties.

//

photo.loadImage(media);


// Prepare and execute a SQL statement to update the image object.

//

stmt = (OraclePreparedStatement)conn.prepareStatement("update photo_album set 

     photo = ? where id = ?");

stmt.setORAData(1, media);

stmt.setString(2 id);

stmt.execute( );

stmt.close( );


// Commit the changes.

//

conn.commit( );

A Note on the Handling of Query String Parameters and Text-Based HTML Form Field Parameters

Every parameter in the optional query string of a request produces a corresponding parameter of type String, whether or not any data is associated with the parameter name. Likewise, every text-based input field in an HTML form also produces a corresponding parameter of type String, whether or not any data is entered into a field. When processing query string parameters and text-based input fields, applications can test the length of the corresponding String object to determine if any data is present.

The parseFormData( ) method merges all query string and form field parameters into a single set of ordered parameters, where the query string parameters are processed first, followed by the form field parameters. Thus, query string parameters take precedence over form field parameters. For example, if a request is made with a query string of arg=hello&arg=world and the values 'greetings' and 'everyone' are entered into two HTML form fields named 'arg,' then the resulting parameter set would include the following entry: arg=(hello, world, greetings, everyone).

A Note on the Handling of FILE-Type HTML Form Field Parameters

Every input field of type FILE in an HTML form produces a corresponding parameter of type OrdUploadFile, whether or not a valid file name is entered into the field. When processing a field of type FILE, applications can test either the length of the file name, the length of content, or a combination of the two to determine if a valid file name was entered by a user, and if the file was successfully uploaded by the browser. See OrdHttpUploadFile Class for more information.

A Note on the Use of Non-Western European Languages

The Microsoft Internet Explorer browser lets data be entered into an HTML form using a character set encoding that is different from that being used to view the form. For example, it is possible to copy Japanese Shift_JIS character set data from one browser window and paste it into a form being viewed using the Western European (ISO) character set in a different browser window. In this situation, Internet Explorer can sometimes transmit the form data twice in such a way that the multipart/form-data parser cannot detect the duplicated data. Furthermore, the non-Western European language form data is sometimes sent as a Unicode escape sequence, sometimes in its raw binary form, and sometimes duplicated using both formats in different portions of the POST data.

Although this same problem does not exist with the Netscape browser, care must still be taken to ensure that the correct character set is being used. For example, although it is possible to copy Japanese Shift_JIS character set data from one browser window and paste it into a form being viewed using the Western European (ISO) character set in a different browser window, when the data is pasted into the form field, the two bytes that comprise each Japanese Shift_JIS character are stored as two individual Western European (ISO) characters.

Therefore, care must be taken to view an HTML form using the correct character set, no matter which Web browser is used. For example, the HTML META tag can be used to specify the character set as follows:

<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=Shift_JIS">

enableParameterTranslation(String)

Format

public void enableParameterTranslation(java.lang.String encoding)

Description

Enables the translation of all HTML form parameter names and all text-based HTML form parameter values using the specified character encoding when parsing the body of a multipart/form-data POST request.

Character encoding of request parameters is not well defined in the HTTP specification. Most servlet containers interpret them using the servlet default encoding, ISO-8859-1. Therefore, to provide an API that is compatible with such servlet containers, by default, the OrdHttpUploadFormData class also interprets multipart/form-data request parameters using the default encoding, ISO-8859-1.

Applications that process requests and responses using other character encodings can, prior to calling the parseFormData( ) method, call the enableParameterTranslation( ) method to specify the character encoding to be used to translate the names of all HTML form parameters, and the values of all text-based HTML form parameters when parsing the body of a multipart/form-data POST request.

Notes:

Query string parameters that accompany multipart/form-data POST requests are not translated prior to being merged into the list of multipart/form-data parameters. This is because there is no way to determine if the underlying servlet container or JSP engine has decoded the query string or translated the parameter names and values already. Therefore, the application is responsible for translating any multibyte query string parameter names or values in the case where the underlying servlet container or JSP engine does not perform the translation.
The contents of uploaded files are never translated; nor is the associated content type attribute, which is always represented using the ISO-8859-1 character encoding. However, the file name attribute of an uploaded file is translated.
Query string parameters in GET requests and query string and POST data parameters in application/x-www-form-urlencoded POST requests are never translated.
To correctly handle the translation of HTML form parameter names and values, applications must call the enableParameterTranslation( ) method for multipart/form-data POST requests, even if the servlet container or JSP engine translates parameter names and values for GET requests and application/x-www-form-urlencoded POST requests.
Do not call the enableParameterTranslation( ) method if the application contains code that handles the translation of parameter names and values.
The enableParameterTranslation( ) method must be called before calling the parseFormData( ) method.

Calling the enableParameterTranslation( ) method with a character encoding other than ISO-8859-1 affects the following methods when called for multipart/form-data POST requests:

getParameter( ): parameter name argument and returned parameter value
getParameterValues( ): parameter name argument and returned parameter values
getParameterNames( ): returned parameter names
getFileParameter( ): parameter name argument only
getFileParameterValues( ): parameter name argument only
getFileParameterNames( ): returned parameter names

For GET requests and application/x-www-form-urlencoded POST requests, calls to the getParameter( ), getParameterValues( ), and getParameterNames( ) methods are passed directly to the underlying servlet container or JSP engine. Please consult the servlet container or JSP engine documentation for information regarding any parameter translation functions that might be supported by the servlet container or JSP engine.

Parameters

encoding: A String that specifies the character encoding.

Return Value

None.

Exceptions

None.

Examples

None.

getFileParameter(String)

Format

public OrdHttpUploadFile getFileParameter(String parameterName)

Description

Returns information about an uploaded file identified by parameter name, as an OrdHttpUploadFile object.

Every input field of type FILE in an HTML form will produce a parameter of type OrdHttpUploadFile, whether or not you enter a valid file name into the field.

Parameters

parameterName: The name of the uploaded file parameter, as a String.

Return Value

This method returns the uploaded file parameter, as an OrdHttpUploadFile object, or null if the parameter does not exist.

Exceptions

java.lang.IllegalStateException

This exception is thrown if the ServletRequest object has not been specified, if the multipart form data has not been parsed, or if the upload request has been released.

Examples

None.

getFileParameterNames( )

Format

public java.util.Enumeration getFileParameterNames( )

Description

Returns an Enumeration of the names of all input fields of type FILE in an HTML form, or an empty Enumeration if there are no input fields of type FILE.

Every input field of type FILE in an HTML form will produce a parameter of type OrdHttpUploadFile, whether or not you enter a valid file name into the field.

Parameters

None.

Return Value

This method returns a list of uploaded file parameter names, as an Enumeration of Strings.

Exceptions

java.lang.IllegalStateException

This exception is thrown if the ServletRequest object has not been specified, if the multipart form data has not been parsed, or if the upload request has been released.

Examples

None.

getFileParameterValues(String)

Format

public OrdHttpUploadFile[ ] getFileParameterValues(String parameterName)

Description

Returns an array of OrdHttpUploadFile objects that represents all files uploaded using the specified parameter name. Every input field of type FILE in an HTML form will produce a parameter of type OrdHttpUploadFile, whether or not you enter a valid file name in the field.

Parameters

parameterName: The name of the uploaded file parameter, as a String.

Return Value

This method returns the uploaded file parameters, as an array of OrdHttpUploadFile objects, or null if the parameter does not exist.

Exceptions

java.lang.IllegalStateException

This exception is thrown if the ServletRequest object has not been specified, if the multipart form data has not been parsed, or if the upload request has been released.

Examples

None.

getParameter(String)

Format

public String getParameter(String parameterName)

Description

Returns the value of the first query string parameter or text-based form field parameter with the specified name, or null if the parameter does not exist. The query string parameters of the request are merged with the text-based form field parameters by the parseFormData( ) method.

This method calls the getParameterName( ) method in the ServletRequest class if the request is not a multipart/form-data upload request.

Parameters

parameterName: The name of the parameter, as a String.

Return Value

This method returns the value of the specified parameter, as a String, or null if the parameter does not exist.

Exceptions

java.lang.IllegalStateException

This exception is thrown if the ServletRequest object has not been specified, if the multipart form data has not been parsed, or if the upload request has been released.

Examples

None.

getParameterNames( )

Format

public java.util.Enumeration getParameterNames( )

Description

Returns an Enumeration of all the query string parameter names and all the text-based form field data parameter names in the request, or an empty Enumeration if there are no query string parameters and no text-based form field parameters. The query string parameters of the request are merged with the text-based form field parameters by the parseFormData( ) method.

This method calls the getParameterNames( ) method in the ServletRequest class if the request is not a multipart/form-data upload request.

Parameters

None.

Return Value

This method returns a list of parameter names, as an Enumeration of Strings.

Exceptions

java.lang.IllegalStateException

This exception is thrown if the ServletRequest object has not been specified, if the multipart form data has not been parsed, or if the upload request has been released.

Examples

None.

getParameterValues(String)

Format

public String[ ] getParameterValues(String parameterName)

Description

Returns an array of String objects containing the values of all the query string parameters and text-based form field data parameters with the specified parameter name, or null if the parameter does not exist. The query string parameters of the request are merged with the text-based form field parameters by the parseFormData( ) method.

This method calls the getParameterValues( ) method in the ServletRequest class if the request is not a multipart/form-data upload request.

Parameters

parameterName: The name of the parameter, as a String.

Return Value

This method returns the parameter value, as a String, or null if the parameter does not exist.

Exceptions

java.lang.IllegalStateException

This exception is thrown if the ServletRequest object has not been specified, if the multipart form data has not been parsed, or if the upload request has been released.

Examples

None.

isUploadRequest( )

Format

public boolean isUploadRequest( )

Description

Tests if the request was encoded using the multipart/form-data encoding format.

Parameters

None.

Return Value

This method returns true if the request body was encoded using the multipart/form-data encoding format; false otherwise.

Exceptions

java.lang.IllegalStateException

This exception is thrown if the ServletRequest object has not been specified.

Examples

None.

OrdHttpUploadFormData( )

Format

public OrdHttpUploadFormData( )

Description

Creates an OrdHttpFormData object to parse a multipart/form-data request. Subsequently, the application must specify the ServletRequest object.

Parameters

None.

Return Value

None.

Exceptions

None.

Examples

None.

OrdHttpUploadFormData(ServletRequest)

Format

public OrdHttpUploadFormData(javax.servlet.ServletRequest request)

Description

Creates an OrdHttpUploadFormData object to parse a multipart/form-data request.

Parameters

request: An object of type ServletRequest.

Return Value

None.

Exceptions

None.

Examples

None.

parseFormData( )

Format

public void parseFormData( )

Description

Parses the body of a POST request that is encoded using the multipart/form-data encoding. If the request is not an upload request, this method does nothing.

Parameters

None.

Return Value

None.

Exceptions

java.lang.IllegalStateException

This exception is thrown if the ServletRequest object has not been specified.

java.io.IOException

This exception is thrown if an error occurs reading the request body or writing a temporary file.

OrdHttpUploadException

This exception is thrown if an error occurs parsing the multipart/form-data message.

Examples

None.

release( )

Format

public void release( )

Description

Releases all resources held by an OrdHttpUploadFormData object, including temporary files used to hold the contents of uploaded files. An application that enables the use of temporary files must call this method.

Parameters

None.

Return Value

None.

Exceptions

None.

Examples

None.

setMaxMemory(int, String)

Format

public void setMaxMemory(int maxMemory, String tempFileDir)

Description

Specifies the maximum amount of memory that the contents of uploaded files can consume before the contents are stored in a temporary directory.

By default, the contents of uploaded files are held in memory until stored in a database by the application. If users upload large files, such as large video clips, then it may be desirable to limit the amount of memory consumed, and to store temporarily the contents of such files on disk, before the contents are written to a database.

Note:

Applications that use this mechanism must ensure that any temporary files are deleted when no longer required by using the release( ) method. See the release( ) method for more information.

Parameters

maxMemory: An integer that specifies the maximum amount of memory to be consumed by all uploaded files in a request before the contents of the uploaded files are stored in temporary files.
tempFileDir: A String that specifies the temporary file directory where you will store temporary files. This parameter is optional if the java.io.tmpdir system property is present.

Return Value

None.

Exceptions

java.lang.IllegalArgumentException

This exception is thrown if the maxMemory parameter is negative, or if the tempFileDir parameter was specified as null and the java.io.tmpdir system property is not present.

Examples

None.

setServletRequest(ServletRequest)

Format

public void setServletRequest(javax.servlet.ServletRequest request)

Description

Specifies the ServletRequest object for the request. The ServletRequest object must be specified either in the constructor, or by calling this method before parsing the request.

Parameters

request: An object of type ServletRequest.

Return Value

None.

Exceptions

None.

Examples

None.