Oracle® interMedia Java Classes Reference 10g Release 1 (10.1) Part Number B10830-01 |
|
|
View PDF |
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( );
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).
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.
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">
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:
|
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
A String that specifies the character encoding.
Return Value
None.
Exceptions
None.
Examples
None.
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
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.
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.
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
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.
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
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.
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.
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
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.
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.
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.
Format
public OrdHttpUploadFormData(javax.servlet.ServletRequest request)
Description
Creates an OrdHttpUploadFormData object to parse a multipart/form-data request.
Parameters
An object of type ServletRequest.
Return Value
None.
Exceptions
None.
Examples
None.
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.
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.
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
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.
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.
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
An object of type ServletRequest.
Return Value
None.
Exceptions
None.
Examples
None.