oracle.ord.im
Class OrdHttpUploadFile

java.lang.Object
oracle.ord.im.OrdHttpUploadFile

public class OrdHttpUploadFile

extends java.lang.Object

The OrdHttpUploadFile class facilitates the handling of uploaded files by providing an API that applications can call to load media data into Oracle Database. Form-based file uploading using HTML forms encodes form data and uploaded files in POST requests using the multipart/form-data format. The OrdHttpUploadFile class is used to represent an uploaded file that has been parsed by the OrdHttpUploadFormData class.

The OrdHttpUploadFile class provides methods to obtain information about the uploaded file, to access the contents of the file directly, and to facilitate loading the contents into an interMedia object in a database.

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 such a field. Depending on the requirements, applications can test the length of the file name, the length of the content, or both, to determine if a valid file name was entered by a user and if the file was successfully uploaded by the browser. For example, if a user does not enter a file name, the getOriginalFileName() method will return the file name whose length is zero. However, if a user enters either an invalid file name or the name of an empty (zero-length) file, the getOriginalFileName method will return the file name whose length is not zero, and the getContentLength() method will return the content length of the file as zero.

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.

Method Summary

int	getContentLength() Returns the length of the uploaded media file.
java.io.InputStream	getInputStream() Returns an InputStream object that can be used to read uploaded data directly.
java.lang.String	getMimeType() Returns the MIME type of the media file, as determined by the browser when the file is uploaded.
java.lang.String	getOriginalFileName() Returns the original file name, as provided by the browser.
java.lang.String	getSimpleFileName() Returns the simple file name, (that is, the name of the file and the extension).
java.io.File	getTempFile() Exists as an internal method only.
void	loadAudio(oracle.ord.im.OrdAudio audio) Loads the uploaded file into an OrdAudio Java object and sets the properties based on the audio data.
void	loadAudio(oracle.ord.im.OrdAudio audio, byte[][] ctx, boolean setComments) Loads the uploaded file into an OrdAudio Java object and sets the properties using an application-supplied, format plug-in context.
void	loadBlob(oracle.sql.BLOB blob) Loads the uploaded media file into a BLOB.
void	loadDoc(oracle.ord.im.OrdDoc doc) Loads the uploaded file into an OrdDoc Java object and sets the properties based on the contents of the document.
void	loadDoc(oracle.ord.im.OrdDoc doc, byte[][] ctx, boolean setComments) Loads the uploaded file into an OrdDoc Java object and sets the properties using an application-supplied, format plug-in context.
void	loadImage(oracle.ord.im.OrdImage image) Loads the uploaded file into an OrdImage Java object and sets the properties based on the image data.
void	loadImage(oracle.ord.im.OrdImage image, java.lang.String cmd) Loads the uploaded file into an OrdImage Java object and sets the properties according to an application-supplied command string.
void	loadVideo(oracle.ord.im.OrdVideo video) Loads the uploaded file into an OrdVideo Java object and sets the properties based on the video data.
void	loadVideo(oracle.ord.im.OrdVideo video, byte[][] ctx, boolean setComments) Loads the uploaded file into an OrdVideo Java object and sets the properties using an application-supplied, format plug-in context.
void	release() Releases all resources held by an OrdHttpUploadFile object.

Methods inherited from class java.lang.Object

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

Method Detail

getOriginalFileName

public java.lang.String getOriginalFileName()

Returns the original file name, as provided by the browser. If you do not supply a file name in HTML form, an empty String is returned.

Returns:

the file name, as a String.

getSimpleFileName

public java.lang.String getSimpleFileName()

Returns the simple file name, (that is, the name of the file and the extension). If you do not supply a file name in HTML form, an empty String is returned.

Returns:

the simple file name, as a String.

getMimeType

public java.lang.String getMimeType()

Returns the MIME type of the media file, as determined by the browser when the file is uploaded.

Some browsers return a default MIME type even if you do not supply a file name; therefore, the application should check the file name or content length to ensure the file was uploaded successfully.

Returns:

the MIME type of the file, as a String.

getContentLength

public int getContentLength()

Returns the length of the uploaded media file. If you enter an invalid file name, the name of a nonexistent file, or the name of an empty file, the length returned is zero.

Returns:

the length of the uploaded file.

getInputStream

public java.io.InputStream getInputStream()
                                   throws java.io.IOException

Returns an InputStream object that can be used to read uploaded data directly. Applications should close the stream with the close method when finished.

Returns:

an InputStream object, from which to read the contents.

Throws:

java.lang.IllegalStateException - if the uploaded file is no longer available because it has been released.

java.io.IOException - if an error occurs opening the temporary file.

loadImage

public void loadImage(oracle.ord.im.OrdImage image)
               throws java.sql.SQLException,
                      java.io.IOException

Loads the uploaded file into an OrdImage Java object and sets the properties based on the image data. This method loads the image data into the database and calls the OrdImage setProperties method to set the properties, such as the MIME type, length, height, and width. To use this method, the application fetches an initialized OrdImage object from the database, calls this method to load the image data into the database, and then updates the OrdImage object in the database.

If the call to the setProperties method fails because the image format is not recognized, this method sets the following properties:

• MIME type (to the value specified by the browser)
• content length (to the length of the uploaded file)
• update time (to the current date and time)

Parameters:

image - an object of type oracle.ord.im.OrdImage into which the image data will be loaded.

Throws:

java.io.IOException - if an error occurs reading or writing the media data.

java.sql.SQLException - if an unrecognized error occurs storing the media data.

java.lang.IllegalStateException - if the uploaded file is no longer available because it has been released.

loadImage

public void loadImage(oracle.ord.im.OrdImage image,
                      java.lang.String cmd)
               throws java.sql.SQLException,
                      java.io.IOException

Loads the uploaded file into an OrdImage Java object and sets the properties according to an application-supplied command string. To use this method, the application fetches an initialized OrdImage object from the database, calls this method to load the image data into the database, and then updates the OrdImage object in the database.

Parameters:

image - an object of type oracle.ord.im.OrdImage into which the image data will be loaded.

cmd - a String that specifies the properties to be set.

Throws:

java.io.IOException - if an error occurs reading or writing the media data.

java.sql.SQLException - if an unrecognized error occurs storing the media data.

java.lang.IllegalStateException - if the uploaded file is no longer available because it has been released.

loadAudio

public void loadAudio(oracle.ord.im.OrdAudio audio)
               throws java.sql.SQLException,
                      java.io.IOException

Loads the uploaded file into an OrdAudio Java object and sets the properties based on the audio data. This method loads the audio data into the database and calls the OrdAudio setProperties method to set the properties, such as the MIME type. This method does not use any existing format plug-in context information and does not set any comments when setting the properties. To use this method, the application fetches an initialized OrdAudio object from the database, calls this method to load the audio data into the database, and then updates the OrdAudio object in the database.

If the call to the setProperties method fails because the audio format is not recognized, this method sets the following properties:

• MIME type (to the value specified by the browser)
• update time (to the current date and time)

Parameters:

audio - an object of type oracle.ord.im.OrdAudio into which the audio data will be loaded.

Throws:

java.io.IOException - if an error occurs reading or writing the media data.

java.sql.SQLException - if an unrecognized error occurs storing the media data.

java.lang.IllegalStateException - if the uploaded file is no longer available because it has been released.

loadAudio

public void loadAudio(oracle.ord.im.OrdAudio audio,
                      byte[][] ctx,
                      boolean setComments)
               throws java.sql.SQLException,
                      java.io.IOException

Loads the uploaded file into an OrdAudio Java object and sets the properties using an application-supplied, format plug-in context. This method loads the audio data into the database and calls the OrdAudio setProperties method to set the properties, such as the MIME type. The application provides the format plug-in context information and chooses whether or not to set the comments in the OrdAudio object. To use this method, the application fetches an initialized OrdAudio object from the database, calls this method to load the audio data into the database, and then updates the OrdAudio object in the database.

If the call to the setProperties method fails because the audio format is not recognized, this method sets the following properties:

• MIME type (to the value specified by the browser)
• update time (to the current date and time)

Parameters:

audio - an object of type oracle.ord.im.OrdAudio into which the audio data will be loaded.

ctx - the format plug-in context information.

setComments - a boolean value indicating whether or not to set the comments in the OrdAudio object.

Throws:

java.io.IOException - if an error occurs reading or writing the media data.

java.sql.SQLException - if an unrecognized error occurs storing the media data.

java.lang.IllegalStateException - if the uploaded file is no longer available because it has been released.

loadVideo

public void loadVideo(oracle.ord.im.OrdVideo video)
               throws java.sql.SQLException,
                      java.io.IOException

Loads the uploaded file into an OrdVideo Java object and sets the properties based on the video data. This method loads the video data into the database and calls the OrdVideo setProperties method to set the properties, such as the MIME type. This method does not use any existing format plug-in context information and does not set any comments when setting the properties. To use this method, the application fetches an initialized OrdVideo object from the database, calls this method to load the video data into the database, and then updates the OrdVideo object in the database.

If the call to the setProperties method fails because the video format is not recognized, this method sets the following properties:

• MIME type (to the value specified by the browser)
• update time (to the current date and time)

Parameters:

video - an object of type oracle.ord.im.OrdVideo into which the video data will be loaded.

Throws:

java.io.IOException - if an error occurs reading or writing the media data.

java.sql.SQLException - if an unrecognized error occurs storing the media data.

java.lang.IllegalStateException - if the uploaded file is no longer available because it has been released.

loadVideo

public void loadVideo(oracle.ord.im.OrdVideo video,
                      byte[][] ctx,
                      boolean setComments)
               throws java.sql.SQLException,
                      java.io.IOException

Loads the uploaded file into an OrdVideo Java object and sets the properties using an application-supplied, format plug-in context. This method loads the video data into the database and calls the OrdVideo setProperties method to set the properties, such as the MIME type. The application provides the format plug-in context information and chooses whether or not to set the comments in the OrdVideo object. To use this method, the application fetches an initialized OrdVideo object from the database, calls this method to load the video data into the database, and then updates the OrdVideo object in the database.

If the call to the setProperties method fails because the video format is not recognized, this method sets the following properties:

• MIME type (to the value specified by the browser)
• update time (to the current date and time)

Parameters:

video - an object of type oracle.ord.im.OrdVideo into which the video data will be loaded.

ctx - the format plug-in context information.

setComments - a boolean value indicating whether or not to set the comments in the OrdVideo object.

Throws:

java.io.IOException - if an error occurs reading or writing the media data.

java.sql.SQLException - if an unrecognized error occurs storing the media data.

java.lang.IllegalStateException - if the uploaded file is no longer available because it has been released.

loadDoc

public void loadDoc(oracle.ord.im.OrdDoc doc)
             throws java.sql.SQLException,
                    java.io.IOException

Loads the uploaded file into an OrdDoc Java object and sets the properties based on the contents of the document. This method loads the document into the database and calls the OrdDoc setProperties method to set the properties, such as the MIME type. This method does not use any existing format plug-in context information and does not set any comments when setting the properties. To use this method, the application fetches an initialized OrdDoc object from the database, calls this method to load the document into the database, and then updates the OrdDoc object in the database.

If the call to the setProperties method fails because the document format is not recognized, this method sets the following properties:

• MIME type (to the value specified by the browser)
• content length (to the length of the uploaded file)
• update time (to the current date and time)

Parameters:

doc - an object of type oracle.ord.im.OrdDoc into which the document will be loaded.

Throws:

java.io.IOException - if an error occurs reading or writing the media data.

java.sql.SQLException - if an unrecognized error occurs storing the media data.

java.lang.IllegalStateException - if the uploaded file is no longer available because it has been released.

loadDoc

public void loadDoc(oracle.ord.im.OrdDoc doc,
                    byte[][] ctx,
                    boolean setComments)
             throws java.sql.SQLException,
                    java.io.IOException

Loads the uploaded file into an OrdDoc Java object and sets the properties using an application-supplied, format plug-in context. This method loads the document into the database and calls the OrdDoc setProperties method to set the properties, such as the MIME type. The application provides the format plug-in context information and chooses whether or not to set the comments in the OrdDoc object. To use this method, the application fetches an initialized OrdDoc object from the database, calls this method to load the document into the database, and then updates the OrdDoc object in the database.

If the call to the setProperties method fails because the document format is not recognized, this method sets the following properties:

• MIME type (to the value specified by the browser)
• content length (to the length of the uploaded file)
• update time (to the current date and time)

Parameters:

doc - an object of type oracle.ord.im.OrdDoc into which the document will be loaded.

ctx - the format plug-in context information.

setComments - a boolean value indicating whether or not to set the comments in the OrdDoc object.

Throws:

java.io.IOException - if an error occurs reading or writing the media data.

java.sql.SQLException - if an unrecognized error occurs storing the media data.

java.lang.IllegalStateException - if the uploaded file is no longer available because it has been released.

loadBlob

public void loadBlob(oracle.sql.BLOB blob)
              throws java.sql.SQLException,
                     java.io.IOException

Loads the uploaded media file into a BLOB.

Parameters:

blob - an object of type oracle.sql.BLOB into which the data will be loaded.

Throws:

java.io.IOException - if an error occurs reading or writing the media data.

java.sql.SQLException - if an unrecognized error occurs storing the media data.

java.lang.IllegalStateException - if the uploaded file is no longer available because it has been released.

release

public void release()

Releases all resources held by an OrdHttpUploadFile object. Specifically, this method releases the memory used to hold the contents of an uploaded file or deletes the temporary file used to hold the contents of the uploaded file. An application can optimize memory usage by calling this method to release any allocated memory, making it a candidate for garbage collection, after the application has finished processing an uploaded file.

getTempFile

public java.io.File getTempFile()

Exists as an internal method only. Applications should not call this method.