oracle.ord.im
Class OrdHttpResponseHandler

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

Direct Known Subclasses:

OrdHttpJspResponseHandler

public class OrdHttpResponseHandler

extends java.lang.Object

The OrdHttpResponseHandler class facilitates the retrieval of multimedia data from an Oracle database and its delivery to a browser or other HTTP client from a Java Servlet.

Note

An interMedia Java object, such as an OrdImage object, is not dependent on the JDBC statement or result set from which it was obtained. However, an interMedia Java object is dependent on the JDBC connection using which the SQL statement was executed or from which the result set was obtained. Therefore, having obtained an interMedia Java object from the database, an application must not release the JDBC connection before delivering the multimedia data to the browser.

The following example illustrates how to use the OrdHttpResponseHandler class to retrieve an image from a database and deliver it to a browser:

  PreparedStatement stmt = conn.prepareStatement(
      "select photo from photo_album where id = ?" );
  stmt.setString( 1, request.getParameter( "photo_id" ) );
  OracleResultSet rset = (OracleResultSet)stmt.executeQuery();
  if ( rset.next() )
  {
      OrdImage img = (OrdImage)rset.getCustomDatum( 1, OrdImage.getFactory() );
      OrdHttpResponseHandler handler =
          new OrdHttpResponseHandler( request, response );
      handler.sendImage( img );
  }
  else
  {
      response.setStatus( response.SC_NOT_FOUND );
  }
  rset.close();
  stmt.close();

Note on the use of charsets other than ISO-8859-1 (Latin-1).

If you wish to retrieve from an OrdDoc object a text-based document with a charset other than ISO-8859-1 (also called Latin-1) and deliver that document to a browser, then your application must specify the charset name in the HTTP Content-Type header.

If the charset specification is included in the MIME type attribute in the OrdDoc object, then your application need only call the sendDoc() method to retrieve the document and deliver it to the browser. For example, for an HTML page written in Japanese, the MIME type might be stored in the OrdDoc object as:

    text/html; charset=Shift_JIS

In this case, calling sendDoc() will send the appropriate Content-Type header allowing the browser to display the page correctly.
However, if the MIME type in the OrdDoc object does not include the charset specification, then you must call one of the sendResponse methods and specify the MIME type explicitly. For example, if the MIME type for an HTML page written in Japanese is stored in the OrdDoc object as:

    text/html

and the charset name is specified in a separate column, then the application must append the charset specification to the MIME type before calling a sendResponse method. For example:

  OraclePreparedStatement stmt =
      (OraclePreparedStatement)conn.prepareStatement(
          "select doc, charset from documents where id = ?" );
  stmt.setString( 1, request.getParameter("id") );
  OracleResultSet rset = (OracleResultSet)stmt.executeQuery();
  if ( rset.next() )
  {
      OrdDoc doc = (OrdDoc)rset.getCustomDatum( 1, OrdDoc.getFactory() );
      String charset = rset.getString( 2 );
      String mimeType = doc.getMimeType() + "; charset=" + charset;
      OrdHttpResponseHandler handler =
                      new OrdHttpResponseHandler( request, response );
      handler.sendResponse( mimeType, doc.getContentLength(),
                            doc.getContent(), doc.getUpdateTime() );
  }
  else
  {
      response.setStatus( response.SC_NOT_FOUND );
  }
  rset.close();
  stmt.close();

Field Summary

Type	Field
static int	DEFAULT_BUFFER_SIZE The OrdHttpResponseHandler class uses a default buffer size of 32768 to retrieve LOB data from the database and deliver it to the client.

Constructor Summary

OrdHttpResponseHandler()
Creates an OrdHttpResponseHandler object to handle the response to a multimedia retrieval request.

OrdHttpResponseHandler(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
Creates an OrdHttpResponseHandler object to handle the response to a multimedia retrieval request and specifies the HttpServletRequest and HttpServletResponse objects for the response handler.

Method Summary

Type	Method
void	sendAudio(OrdAudio media) Retrieves an audio clip from an OrdAudio object and delivers it to the browser.
void	sendDoc(OrdDoc media) Retrieves media data from an OrdDoc object and delivers it to the browser.
void	sendImage(OrdImage media) Retrieves an image from an OrdImage object and delivers it to the browser.
void	sendResponse(java.lang.String contentType, int length, oracle.sql.BFILE bfile, java.sql.Timestamp lastModified) Builds an HTTP response header, then retrieves the contents of the BFILE from the database and delivers it to the browser.
void	sendResponse(java.lang.String contentType, int length, oracle.sql.BLOB blob, java.sql.Timestamp lastModified) Builds an HTTP response header, then retrieves the contents of the BLOB from the database and delivers it to the browser.
void	sendResponse(java.lang.String contentType, int length, java.io.InputStream in, java.sql.Timestamp lastModified) Builds an HTTP response header, then retrieves the contents from the InputStream and delivers it to the browser.
void	sendResponseBody(int length, oracle.sql.BFILE bfile) Retrieves the contents of a BFILE from the database and delivers it as the response body to the client.
void	sendResponseBody(int length, oracle.sql.BLOB blob) Retrieves the contents of a BLOB from the database and delivers it as the response body to the client.
void	sendResponseBody(int length, java.io.InputStream in) Retrieves the contents from the InputStream and delivers it to the client.
void	sendVideo(OrdVideo media) Retrieves a video clip from an OrdVideo object and delivers it to the browser.
void	setBufferSize(int bufferSize) Sets the buffer size for LOB read and response write operations.
void	setServletRequest(javax.servlet.http.HttpServletRequest request) Specifies the HttpServletRequest object for this response handler.
void	setServletResponse(javax.servlet.http.HttpServletResponse response) Specifies the HttpServletResponse object for this response handler.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_BUFFER_SIZE

public static final int DEFAULT_BUFFER_SIZE

The OrdHttpResponseHandler class uses a default buffer size of 32768 to retrieve LOB data from the database and deliver it to the client. This value can be overridden using the setBufferSize() method.

Constructor Detail

OrdHttpResponseHandler

public OrdHttpResponseHandler()

Creates an OrdHttpResponseHandler object to handle the response to a multimedia retrieval request. The application must subsequently specify the HttpServletResponse object by calling setServletResponse(), and can optionally specify the HttpServletRequest object by calling setServletRequest().

OrdHttpResponseHandler

public OrdHttpResponseHandler(javax.servlet.http.HttpServletRequest request,
                              javax.servlet.http.HttpServletResponse response)

Creates an OrdHttpResponseHandler object to handle the response to a multimedia retrieval request and specifies the HttpServletRequest and HttpServletResponse objects for the response handler.

Parameters:

request - an object of type HttpServletRequest.

response - an object of type HttpServletResponse.

Method Detail

setServletRequest

public void setServletRequest(javax.servlet.http.HttpServletRequest request)

Specifies the HttpServletRequest object for this response handler. You must call this method if you did not specify the HttpServletRequest object in the constructor and you want to call any of the send methods other than the sendResponseBody methods. You do not need to call this method if you call only the sendResponseBody methods.

Parameters:

request - an object of type HttpServletRequest.

setServletResponse

public void setServletResponse(javax.servlet.http.HttpServletResponse response)

Specifies the HttpServletResponse object for this response handler. You must call this method before calling any of the send methods if you did not specify the HttpServletResponse object in the constructor

Parameters:

response - an object of type HttpServletResponse.

sendImage

public void sendImage(OrdImage media)
               throws javax.servlet.ServletException,
                      java.sql.SQLException,
                      java.io.IOException

Retrieves an image from an OrdImage object and delivers it to the browser. This method supports browser content caching by supporting the If-Modified-Since and Last-Modified headers.

Parameters:

image - an object of type oracle.ord.im.OrdImage.

Throws:

IllegalStateException - if HttpServletRequest or HttpServletResponse has not been specified

OrdHttpResponseException - if the source type is not recognized.

ServletException - if an error occurs accessing the binary output stream.

java.sql.SQLException - if an error occurs obtaining an InputStream to read the image data.

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

sendAudio

public void sendAudio(OrdAudio media)
               throws javax.servlet.ServletException,
                      java.sql.SQLException,
                      java.io.IOException

Retrieves an audio clip from an OrdAudio object and delivers it to the browser. This method supports browser content caching by supporting the If-Modified-Since and Last-Modified headers.

Parameters:

audio - an object of type oracle.ord.im.OrdAudio.

Throws:

IllegalStateException - if HttpServletRequest or HttpServletResponse has not been specified

OrdHttpResponseException - if the source type is not recognized.

ServletException - if an error occurs accessing the binary output stream.

java.sql.SQLException - if an error occurs obtaining an InputStream to read the audio data.

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

sendVideo

public void sendVideo(OrdVideo media)
               throws javax.servlet.ServletException,
                      java.sql.SQLException,
                      java.io.IOException

Retrieves a video clip from an OrdVideo object and delivers it to the browser. This method supports browser content caching by supporting the If-Modified-Since and Last-Modified headers.

Parameters:

video - an object of type oracle.ord.im.OrdVideo.

Throws:

IllegalStateException - if HttpServletRequest or HttpServletResponse has not been specified

OrdHttpResponseException - if the source type is not recognized.

ServletException - if an error occurs accessing the binary output stream.

java.sql.SQLException - if an error occurs obtaining an InputStream to read the video data.

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

sendDoc

public void sendDoc(OrdDoc media)
             throws javax.servlet.ServletException,
                    java.sql.SQLException,
                    java.io.IOException

Retrieves media data from an OrdDoc object and delivers it to the browser. This method supports browser content caching by supporting the If-Modified-Since and Last-Modified headers.

Parameters:

doc - an object of type oracle.ord.im.OrdDoc.

Throws:

IllegalStateException - if HttpServletRequest or HttpServletResponse has not been specified

OrdHttpResponseException - if the source type is not recognized.

ServletException - if an error occurs accessing the binary output stream.

java.sql.SQLException - if an error occurs obtaining an InputStream to read the media data.

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

sendResponse

public void sendResponse(java.lang.String contentType,
                         int length,
                         oracle.sql.BLOB blob,
                         java.sql.Timestamp lastModified)
                  throws javax.servlet.ServletException,
                         java.sql.SQLException,
                         java.io.IOException

Builds an HTTP response header, then retrieves the contents of the BLOB from the database and delivers it to the browser. This method supports browser content caching by supporting the If-Modified-Since and Last-Modified headers.

Parameters:

contentType - a String that specifies the content's MIME type.

length - an int that specifies the length of the data.

blob - an oracle.sql.BLOB from which the multimedia data is retrieved.

lastModified - a java.sql.Timestamp that specifies the date/time when the data was last modified, or null if no last modified date/time is available.

Throws:

IllegalStateException - if HttpServletRequest or HttpServletResponse has not been specified.

java.lang.IllegalArgumentException - if the length is negative.

ServletException - if an error occurs accessing the binary output stream.

java.sql.SQLException - if an error occurs obtaining an InputStream to read the multimedia data.

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

sendResponse

public void sendResponse(java.lang.String contentType,
                         int length,
                         oracle.sql.BFILE bfile,
                         java.sql.Timestamp lastModified)
                  throws javax.servlet.ServletException,
                         java.sql.SQLException,
                         java.io.IOException

Builds an HTTP response header, then retrieves the contents of the BFILE from the database and delivers it to the browser. This method supports browser content caching by supporting the If-Modified-Since and Last-Modified headers.

Parameters:

contentType - a String that specifies the content's MIME type.

length - an int that specifies the length of the data.

bfile - an oracle.sql.BFILE from which the multimedia data is retrieved.

lastModified - a java.sql.Timestamp that specifies the date/time when the data was last modified, or null if no last modified date/time is available.

Throws:

IllegalStateException - if HttpServletRequest or HttpServletResponse has not been specified.

java.lang.IllegalArgumentException - if the length is negative.

ServletException - if an error occurs accessing the binary output stream.

java.sql.SQLException - if an error occurs obtaining an InputStream to read the multimedia data.

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

sendResponse

public void sendResponse(java.lang.String contentType,
                         int length,
                         java.io.InputStream in,
                         java.sql.Timestamp lastModified)
                  throws javax.servlet.ServletException,
                         java.io.IOException

Builds an HTTP response header, then retrieves the contents from the InputStream and delivers it to the browser. This method supports browser content caching by supporting the If-Modified-Since and Last-Modified headers.

Parameters:

contentType - a String that specifies the content's MIME type.

length - an int that specifies the length of the data.

in - an InputStream from which the multimedia data is retrieved.

lastModified - a java.sql.Timestamp that specifies the date/time when the data was last modified, or null if no last modified date/time is available.

Throws:

IllegalStateException - if HttpServletRequest or HttpServletResponse has not been specified.

java.lang.IllegalArgumentException - if the length is negative.

ServletException - if an error occurs accessing the binary output stream.

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

sendResponseBody

public void sendResponseBody(int length,
                             oracle.sql.BLOB blob)
                      throws javax.servlet.ServletException,
                             java.sql.SQLException,
                             java.io.IOException

Retrieves the contents of a BLOB from the database and delivers it as the response body to the client. The caller is responsible for building the HTTP header.

Parameters:

length - an int that specifies the length of the data.

blob - an oracle.sql.BLOB from which the content is retrieved.

Throws:

IllegalStateException - if HttpServletRequest has not been specified.

java.lang.IllegalArgumentException - if the length is negative.

ServletException - if an error occurs accessing the binary output stream.

java.sql.SQLException - if an error occurs obtaining an InputStream to read the multimedia data.

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

sendResponseBody

public void sendResponseBody(int length,
                             oracle.sql.BFILE bfile)
                      throws javax.servlet.ServletException,
                             java.sql.SQLException,
                             java.io.IOException

Retrieves the contents of a BFILE from the database and delivers it as the response body to the client. The caller is responsible for building the HTTP header.

Parameters:

length - an int that specifies the length of the data.

bfile - an oracle.sql.BFILE from which the content is retrieved.

Throws:

IllegalStateException - if HttpServletRequest has not been specified.

java.lang.IllegalArgumentException - if the length is negative.

ServletException - if an error occurs accessing the binary output stream.

java.sql.SQLException - if an error occurs obtaining an InputStream to read the multimedia data.

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

sendResponseBody

public void sendResponseBody(int length,
                             java.io.InputStream in)
                      throws javax.servlet.ServletException,
                             java.io.IOException

Retrieves the contents from the InputStream and delivers it to the client. The caller is responsible for building the HTTP header.

Parameters:

length - content length.

in - an InputStream from which the multimedia data is retrieved.

Throws:

IllegalStateException - if HttpServletRequest has not been specified.

java.lang.IllegalArgumentException - if the length is negative.

ServletException - if an error occurs accessing the binary output stream.

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

setBufferSize

public void setBufferSize(int bufferSize)
                   throws java.lang.IllegalArgumentException

Sets the buffer size for LOB read and response write operations.

Parameters:

bufferSize - an int that specifies the buffer size.

Throws:

java.lang.IllegalArgumentException - if the buffer size is negative or zero.