oracle.ord.im
Class OrdHttpUploadFile

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

public class OrdHttpUploadFile

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 OrdHttpUploadFile class is used to represent an uploaded file parsed from such a request 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 OrdImage, OrdAudio, OrdVideo or OrdDoc object in a database.

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. Depending on the requirements, applications can test either the length of the file name, the length of the content, or a combination, 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 length of the file name String returned by getOriginalFileName() will be zero. However, if a user enters an invalid file name or the name of an empty (zero-length) file, then the content length returned by getContentLength() will be zero, even though the length of the file name will be non-zero.

Method Summary

int	getContentLength() Returns the length of the uploaded media.
java.io.InputStream	getInputStream() Returns an InputStream object, which can be used to read uploaded data directly.
java.lang.String	getMimeType() Returns the MIME type 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, just the file name and the extension.
java.io.File	getTempFile() Internal: Applications should not use this method.
void	loadAudio(OrdAudio audio) Loads the uploaded file into an OrdAudio Java object and sets the properties based on the audio data.
void	loadAudio(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 file into a BLOB.
void	loadDoc(OrdDoc doc) Loads the uploaded file into an OrdDoc Java object and sets the properties based on the contents of the document.
void	loadDoc(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(OrdImage image) Loads the uploaded file into an OrdImage Java object and sets the properties based on the image contents.
void	loadImage(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(OrdVideo video) Loads the uploaded file into an OrdVideo Java object and sets the properties based on the video data.
void	loadVideo(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 the 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 a user does not enter a file name, an empty (zero-length) String is returned.

Returns:

the file name as a String.

getSimpleFileName

public java.lang.String getSimpleFileName()

Returns the simple file name, that is, just the file name and the extension. If a user does not enter a file name, an empty (zero-length) String is returned.

Returns:

the simple file name as a String.

getMimeType

public java.lang.String getMimeType()

Returns the MIME type as determined by the browser when the file is uploaded. Note that some browsers return a default MIME type even if a user does not enter a file name. Therefore, applications should check the file name or content length to determine if a file was uploaded successfully.

Returns:

the MIME type as a String.

getContentLength

public int getContentLength()

Returns the length of the uploaded media. Note that zero is returned if the user entered an invalid file name, the name of a non-existent file, or the name of an empty (zero-length) file.

Returns:

file length.

getInputStream

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

Returns an InputStream object, which can be used to read uploaded data directly. Applications should call the stream's close() method when finished. For example:

  OrdImage dbImage =
      (OrdImage)rset.getCustomDatum( 1, OrdImage.getFactory() );
  OrdHttpUploadFile uploadImage = formData.getFileParameter( "photo" );
  InputStream photoInputStream = uploadImage.getInputStream();
  try
  {
      dbImage.loadDataFromInputStream( photoInputStream );
  }
  finally
  {
      photoInputStream.close();
  }

Returns:

an InputStream, from which the contents can be read.

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(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 contents. This method loads the image content into the database and calls the OrdImage.setProperties() method to set the image's 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 content into the database, and then updates the OrdImage object in the database.
If the setProperties() method fails because the image format is not recognized, loadImage 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 oracle.ord.im.OrdImage object into which the image is to be loaded.

Throws:

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

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

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

loadImage

public void loadImage(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 content into the database, and then updates the OrdImage object in the database.

Parameters:

image - an oracle.ord.im.OrdImage object into which the image is to be loaded.

cmd - a String that specifies the properties to set.

Throws:

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

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

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

loadAudio

public void loadAudio(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 setProperties method fails because the audio format is not recognized, loadAudio sets the following properties:

• MIME type - to the value specified by the browser
• Update time - to the current date and time

Parameters:

audio - an oracle.ord.im.OrdAudio object into which the audio data is to be loaded.

Throws:

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

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

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

loadAudio

public void loadAudio(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 setProperties method fails because the audio format is not recognized, loadAudio sets the following properties:

• MIME type - to the value specified by the browser
• Update time - to the current date and time

Parameters:

audio - an oracle.ord.im.OrdAudio object into which the audio data is to 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 audio data.

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

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

loadVideo

public void loadVideo(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 setProperties method fails because the video format is not recognized, then 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 oracle.ord.im.OrdVideo object into which the video data is to be loaded.

Throws:

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

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

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

loadVideo

public void loadVideo(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 setProperties method fails because the video format is not recognized, loadVideo sets the following properties:

• MIME type - to the value specified by the browser
• Update time - to the current date and time

Parameters:

video - an oracle.ord.im.OrdVideo object into which the video data is to 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 video data.

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

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

loadDoc

public void loadDoc(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 setProperties method fails because the document format is not recognized, then 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 oracle.ord.im.OrdDoc object into which the document is to be loaded.

Throws:

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

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

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

loadDoc

public void loadDoc(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 setProperties method fails because the document format is not recognized, loadDoc 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 oracle.ord.im.OrdDoc object into which the document is to 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 document.

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

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 file into a BLOB.

Parameters:

blob - a BLOB into which the data is to be loaded.

Throws:

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

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

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

release

public void release()

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

getTempFile

public java.io.File getTempFile()

Internal: Applications should not use this method.