|
Oracle interMedia Java Classes for Servlets and JSP API Reference 10g Release 1 (10.1) Part No. B12249-01 | |||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--oracle.ord.im.OrdHttpUploadFormData
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.
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.
OrdHttpUploadFile
class for more information.Note on the use of non-Western European languages with form-based file uploading using HTML forms.
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 ">
Constructor Summary | |
OrdHttpUploadFormData() Creates an OrdHttpUploadFormData to parse a multipart/form-data request. | |
OrdHttpUploadFormData(javax.servlet.ServletRequest request) Creates an OrdHttpUploadFormData 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. |
OrdHttpUploadFile[] |
getFileParameterValues(java.lang.String parameterName) Returns an array of OrdHttpUploadFile objects that represent all the 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. |
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. |
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. |
boolean |
isUploadRequest() Tests if this 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 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. |
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 |
public OrdHttpUploadFormData()
public OrdHttpUploadFormData(javax.servlet.ServletRequest request)
request
- an object of type ServletRequest
.Method Detail |
public void setServletRequest(javax.servlet.ServletRequest request)
request
- an object of type ServletRequest
.public void setMaxMemory(int maxMemory, java.lang.String tempFileDir)
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(); }
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.maxMemory
is negative, or if tempFileDir
was specified as null
and the java.io.tmpdir
system property is not present.public void enableParameterTranslation(java.lang.String encoding)
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 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 valuegetParameterValues()
: parameter name argument and returned parameter valuesgetParameterNames()
: returned parameter namesgetFileParameter()
: parameter name argument onlygetFileParameterValues()
: parameter name argument onlygetFileParameterNames()
: returned parameter namesFor 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.
encoding
- a String
that specifies the character encoding.public boolean isUploadRequest()
true
if the request body was encoded using the multipart/form-data encoding format; otherwise false
.public void parseFormData() throws java.io.IOException
public java.lang.String getParameter(java.lang.String parameterName)
parameterName
- a String
that specifies the parameter name.String
or null
if the parameter does not exist.public java.lang.String[] getParameterValues(java.lang.String parameterName)
parameterName
- a String
that specifies the parameter name.String
s or null
if the parameter does not exist.public java.util.Enumeration getParameterNames()
Enumeration
of String
s.public OrdHttpUploadFile getFileParameter(java.lang.String parameterName)
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.parameterName
- the name of the uploaded file parameter as a String
.OrdHttpUploadFile
object or null
if the parameter does not exist.public OrdHttpUploadFile[] getFileParameterValues(java.lang.String parameterName)
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.parameterName
- the name of the uploaded file parameter as a String
.OrdHttpUploadFile
objects or null
if the parameter does not exist.public java.util.Enumeration getFileParameterNames()
Enumeration
of String
s.public void release()
|
Oracle interMedia Java Classes for Servlets and JSP API Reference 10g Release 1 (10.1) Part No. B12249-01 | |||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |