oracle.ord.im
Class OrdHttpUploadFormData

java.lang.Object
oracle.ord.im.OrdHttpUploadFormData

public class OrdHttpUploadFormData

extends java.lang.Object

The OrdHttpUploadFormData class facilitates the processing of POST requests using the multipart/form-data format. Form-based file uploading using HTML forms encodes form data and uploaded files in POST requests using this format. The OrdHttpUploadFormData class parses the POST data and makes 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(java.lang.String), getFileParameterValues(java.lang.String) 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 OrdHttpUploadFile objects, see the 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).

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 OrdHttpUploadFile, 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 the 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 the OrdHttpUploadFile class for more information.

A Note on the Use of Non-Western European Languages

The Microsoft Internet Explorer browser allows data to 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 chacter 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 ">

Prerequisites

In order to run interMedia methods for servlets and JSP, you will need to import classes from the oracle.ord.im package into your Java file.

You may also need to import classes from the following Java packages:

 java.sql.
 java.io.
 javax.servlet.
 javax.servlet.http.
 oracle.jdbc.
 oracle.sql.

Constructor Summary

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

OrdHttpUploadFormData(javax.servlet.ServletRequest request)
Creates an OrdHttpUploadFormData object to parse a multipart/form-data request.

Method Summary

void	enableParameterTranslation(java.lang.String encoding) 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.
OrdHttpUploadFile	getFileParameter(java.lang.String parameterName) Returns information about an uploaded file identified by parameter name, as an OrdHttpUploadFile object.
java.util.Enumeration	getFileParameterNames() Returns an Enumeration of the names of all the input fields of type file in an HTML form, or an empty Enumeration if there are no input fields of type file.
OrdHttpUploadFile[]	getFileParameterValues(java.lang.String parameterName) Returns an array of OrdHttpUploadFile objects that represents all files uploaded using the specified parameter name.
java.lang.String	getParameter(java.lang.String parameterName) 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.
java.util.Enumeration	getParameterNames() Returns an Enumeration of all the query string parameter names and all the text-based form field parameter names in the request, or an empty Enumeration if there are no query string parameters and no text-based form field parameters.
java.lang.String[]	getParameterValues(java.lang.String parameterName) 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.
boolean	isUploadRequest() Tests if the request was encoded using the multipart/form-data encoding format.
void	parseFormData() Parses the body of a POST request encoded using the multipart/form-data encoding.
void	release() Releases all resources held by an OrdHttpUploadFormData object, including temporary files used to hold the contents of uploaded files.
void	setMaxMemory(int maxMemory, java.lang.String tempFileDir) Specifies the maximum amount of memory that the contents of uploaded files can consume before the contents are stored in a temporary directory.
void	setServletRequest(javax.servlet.ServletRequest request) Specifies the ServletRequest object for the request.

Methods inherited from class java.lang.Object

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

Constructor Detail

OrdHttpUploadFormData

public OrdHttpUploadFormData()

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

OrdHttpUploadFormData

public OrdHttpUploadFormData(javax.servlet.ServletRequest request)

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

Parameters:

request - an object of type ServletRequest.

Method Detail

setServletRequest

public void setServletRequest(javax.servlet.ServletRequest request)

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.

setMaxMemory

public void setMaxMemory(int maxMemory,
                         java.lang.String tempFileDir)

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 int that specifies the maximum amount of memory to be consumed by all uploaded files in a request before the contents of uploaded files are stored in temporary files.

tempFileDir - a String that specifies the temporary file directory where temporary files will be stored. This parameter is optional if the java.io.tmpdir system property is present.

Throws:

java.lang.IllegalArgumentException - if maxMemory parameter is negative, or if the tempFileDir parameter was specified as null and the java.io.tmpdir system property is not present.

enableParameterTranslation

public void enableParameterTranslation(java.lang.String encoding)

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(java.lang.String): parameter name argument and returned parameter value
• getParameterValues(java.lang.String): parameter name argument and returned parameter values
• getParameterNames(): returned parameter names
• getFileParameter(java.lang.String): parameter name argument only
• getFileParameterValues(java.lang.String): 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. 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.

isUploadRequest

public boolean isUploadRequest()

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

Returns:

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

Throws:

java.lang.IllegalStateException - if HttpServletRequest has not been specified.

parseFormData

public void parseFormData()
                   throws java.io.IOException

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

Throws:

java.lang.IllegalStateException - if ServletRequest has not been specified.

java.io.IOException - if an error occurs reading the request body or writing a temporary file.

OrdHttpUploadException - if an error occurs parsing the multipart/form-data message.

getParameter

public java.lang.String getParameter(java.lang.String parameterName)

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.

Returns:

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

Throws:

java.lang.IllegalStateException - if ServletRequest has not been specified, if the multipart form data has not been parsed, or if the upload request has been released.

getParameterValues

public java.lang.String[] getParameterValues(java.lang.String parameterName)

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.

Returns:

the parameter values, as an array of Strings, or null if the parameter does not exist.

Throws:

java.lang.IllegalStateException - if ServletRequest has not been specified, if the multipart form data has not been parsed, or if the upload request has been released.

getParameterNames

public java.util.Enumeration getParameterNames()

Returns an Enumeration of all the query string parameter names and all the text-based form field 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.

Returns:

a list of parameter names, as an Enumeration of Strings.

Throws:

java.lang.IllegalStateException - if ServletRequest has not been specified, if the multipart form data has not been parsed, or if the upload request has been released.

getFileParameter

public OrdHttpUploadFile getFileParameter(java.lang.String parameterName)

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 a user enters a valid file name into the field.

Parameters:

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

Returns:

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

Throws:

java.lang.IllegalStateException - if ServletRequest has not been specified, if the multipart form data has not been parsed, or if the upload request has been released.

getFileParameterValues

public OrdHttpUploadFile[] getFileParameterValues(java.lang.String parameterName)

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 into the field.

Parameters:

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

Returns:

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

Throws:

java.lang.IllegalStateException - if ServletRequest has not been specified, if the multipart form data has not been parsed, or if the upload request has been released.

getFileParameterNames

public java.util.Enumeration getFileParameterNames()

Returns an Enumeration of the names of all the 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 a user enters a valid file name into the field.

Returns:

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

Throws:

java.lang.IllegalStateException - if ServletRequest has not been specified, if the multipart form data has not been parsed, or if the upload request has been released.

release

public void release()

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.