oracle.ord.im
Class OrdHttpUploadFormData

java.lang.Object
  |
  +--oracle.ord.im.OrdHttpUploadFormData

public class OrdHttpUploadFormData

extends java.lang.Object

Form-based 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 JavaServer 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. The following example illustrates 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 photo.
  //
  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 image = (OrdImage)rset.getORAData( 1, OrdImage.getORADataFactory());

  //
  // Load the photo into the database and set the properties.
  //
photo.loadImage( image );

  //
  // 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, image );
  stmt.setString( 2 id );
  stmt.execute();
  stmt.close();

  //
  // Commit the changes.
  //
  conn.commit();

Note on the handling of query string parameters and text-based HTML form field parameters.

Note on the handling of FILE-type HTML form field parameters.

Note on the use of non-Western European languages with form-based file uploading using HTML forms.

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

OrdHttpUploadFormData

public OrdHttpUploadFormData()

Creates an OrdHttpUploadFormData 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 to parse a multipart/form-data request.

Parameters:

request - an object of type ServletRequest.

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. To do so, use a try-block with a call to the release() method in the finally clause. For example:

  OrdHttpUploadFormData formData = new OrdHttpUploadFormData( request );
  try
  {
formData.setMaxMemory( 65536, null );
formData.parseFormData();
      ...
OrdHttpUploadFile photo = formData.getFileParameter( "photo" );
photo.loadImage( image );
      ...
  }
  finally
  {
formData.release();
  }

Parameters:

maxMemory - an 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 using temporary files.

tempFileDir - a String that specifies the temporary file directory -- optional if the java.io.tmpdir system property is present.

Throws:

java.lang.IllegalArgumentException - if maxMemory is negative, or if tempFileDir 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 multi-byte 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 if the application contains code that handles the translation of parameter names and values.
• The enableParameterTranslation method MUST be called PRIOR to calling parseFormData.

Calling enableParameterTranslation 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 functionality 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 this 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; otherwise false.

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. Does nothing if the request is not an upload request.

Throws:

java.lang.IllegalStateException - if HttpServletRequest 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. Returns null if the parameter does not exist. The request's query string parameters are merged with the text-based form field parameters by the parseFormData method. Calls the getParameter method in the ServletRequest class if the request is not a multipart/form-data upload request.

Parameters:

parameterName - a String that specifies the parameter name.

Returns:

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

Throws:

java.lang.IllegalStateException - 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.

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 parameters with the specified parameter name. The request's query string parameters are merged with the text-based form field parameters by the parseFormData method. Returns null if the parameter does not exist. Calls the getParameterValues method in the ServletRequest class if not a multipart/form-data upload request.

Parameters:

parameterName - a String that specifies the parameter name.

Returns:

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

Throws:

java.lang.IllegalStateException - 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.

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. Returns an empty Enumeration if there are no query string parameters and there are no text-based form field parameters. The request's query string parameters are merged with the text-based form field parameters by the parseFormData method. Calls the getParameterNames method in the ServletRequest class if not a multipart/form-data upload request.

Returns:

list of parameter names as an Enumeration of Strings.

Throws:

java.lang.IllegalStateException - 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.

getFileParameter

public OrdHttpUploadFile getFileParameter(java.lang.String parameterName)

Returns information about an uploaded file identified by parameter name as an OrdHttpUploadFile object. Note that every input field of type FILE in an HTML form will produce a parameter of type OrdUploadFile, whether or not a user enters a valid file name into such a field.

Parameters:

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

Returns:

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

Throws:

java.lang.IllegalStateException - 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.

getFileParameterValues

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

Returns an array of OrdHttpUploadFile objects that represent all the files uploaded using the specified parameter name. Note that every input field of type FILE in an HTML form will produce a parameter of type OrdUploadFile, whether or not a user enters a valid file name into such a field.

Parameters:

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

Returns:

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

Throws:

java.lang.IllegalStateException - 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.

getFileParameterNames

public java.util.Enumeration getFileParameterNames()

Returns an Enumeration of the names of all the input fields of type FILE in an HTML form. Note that every input field of type FILE in an HTML form will produce a parameter of type OrdUploadFile, whether or not a user enters a valid file name into such a field. Returns an empty Enumeration if there are no input fields of type FILE.

Returns:

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

Throws:

java.lang.IllegalStateException - 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.

release

public void release()

Releases all the resources owned by an OrdHttpUploadFormData object, including any temporary files used to hold the contents of uploaded files; therefore, this method MUST be called if the application enables the use of temporary files.