Skip navigation links

Oracle Multimedia Servlets and JSP Java API Reference
11g Release 1 (11.1)

Part No. B28412-01


oracle.ord.im
Class OrdHttpUploadFormData

java.lang.Object
  extended by 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

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:

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.

Skip navigation links

Oracle Multimedia Servlets and JSP Java API Reference
11g Release 1 (11.1)

Part No. B28412-01


Copyright © 1999, 2007, Oracle. All rights reserved.