Keel 2.1RC2

org.keel.comm
Class BinaryWrapper

java.lang.Object
  extended byorg.keel.comm.BinaryWrapper
All Implemented Interfaces:
java.io.Serializable

public class BinaryWrapper
extends java.lang.Object
implements java.io.Serializable

Handles the transfer and serializatoin issues BLOBs and other binary objects between Keel's client and server sides. Designed specifically to handle both VERY large objects (1GB+) as well as small binary objects. Based partly on the DefaultFileItem object from the Jarkarta Commons Fileupload project. This class can handle both local (e.g. single-VM deployments) and remote requests and responses with binary objects, of basically any size. Small objects ("small" being less than the adjustable threshold) can be handled in-memory as a simple byte array. Larger objects will be written to a file, and passed as a URL reference to this file. The client-side must then access this URL in order to access the content. (For secure content, ensure that the URL is accessible only to the user running the web/application server (e.g. Tomcat), not to the end-user (e.g. with the browser) directly. BinaryWrapper is "two-way", that is, used for both uploaded files (binary objects coming from the client) and binary responses (such as PDF's or charts, images, etc) coming from the server as the result of execution of Models. For use in Models, use a BinaryWrapper as the content of an Output.

Author:
Stephen Davidson, Michael Nash - extended to use URLs for cross-vm communications
See Also:
Serialized Form

Field Summary
protected  byte[] cachedContent
          Cached content, if below the threshold (or setKeepInMemory was called)
protected  java.lang.String contentFileName
          External filename for content - not retained when serialized
protected  java.lang.String contentType
          The content type passed by the browser, or null if not defined (this is typically a mime type and subtype).
private static int counter
          Counter used in unique identifier generation.
private  java.lang.Process currentProcess
          Handle to the current process, if any
private  java.lang.String execPath
          A BinaryWrapper can be a reference to an external process (e.g.
protected  java.lang.String fileName
          The original filename in originating filesystem.
private  int mode
          The current mode of this BinaryWrapper.
private static int MODE_EXECUTABLE
          This BinaryWrapper represents an executable task, no stored content at all.
private static int MODE_INMEMORY
          The content is stored in memory
private static int MODE_KEEPINMEMORY
          Content is stored in memory, no matter what it's size (see the setKeepInMemory() method)
private static int MODE_UNKNOWN
          The mode of this BinaryWrapper has not yet been determined
private static int MODE_URL
          The content is stored at a URL location
protected  java.io.File repository
          The directory in which uploaded and temporary files will be stored, if stored on disk.
protected  long size
          When the content is supplied, we know it's size.
protected  int sizeThreshold
          The threshold above which contents will be stored on disk.
private  java.lang.String url
          The URL to access the content from the "receiving" side of this BinaryWrapper
private  java.lang.String urlPrefix
          If the content we're dealing with is larger than the threshold (defined above), then we must write it to disk on the originating system and read it back from a URL on the destination side.
 
Constructor Summary
BinaryWrapper()
          Create an uninitialized BinaryWrapper
 
Method Summary
 void close()
          Closes and flushes the underlying output stream.
 void delete()
          Deletes the underlying storage for a file item, including deleting any associated temporary disk file.
protected  void finalize()
          Call release to clean up if we have not already
 byte[] get()
          Returns the data as an array of bytes.
 java.lang.String getContentType()
          Returns the content type passed by the browser or null if not defined.
 java.lang.String getFileName()
          Retrieve the "filename" property of this BinaryWrapper.
 java.io.InputStream getInputStream()
          Returns an InputStreamthat can be used to retrieve the contents of this BinaryWrapper.
 java.io.OutputStream getOutputStream()
          Returns an OutputStreamthat can be used for storing the contents of the file.
 long getSize()
          Returns the size of the content, if we know it.
 java.lang.String getString()
          Returns the contents of the file as a String, using the default character encoding.
 java.lang.String getString(java.lang.String encoding)
          Returns the contents of the file as a String, using the specified encoding.
 boolean isExecutable()
          Does this BinaryWrapper refer to some external executable program in order to get it's content?
 boolean isInMemory()
          Provides a hint as to whether or not the file contents will be read from memory.
 void loadFromStream(java.io.InputStream is)
          Load the content of this BinaryWrapper from the specified input stream.
 void loadFromURL(java.lang.String url)
           
private  java.lang.String modeToString(int mode)
          Convert the specified mode value into a string
 void release()
          Removes the file contents from the temporary storage.
 void setContent(byte[] newContent)
          Set the content cache directly.
 void setContentType(java.lang.String newType)
          Specify the content type of the content to be transferred.
 void setExecutablePath(java.lang.String newPath)
          Specify a path to an executable from which this BinaryWrapper get's it's content.
 void setFileName(java.lang.String newName)
          Specify the "filename" for this content.
 void setKeepInMemory()
          Insist that the data be kept in memory, no matter the size.
 void setRepository(java.io.File newRepository)
          Specify the file repository used to hold content in temporary files if it's size exceeds the threshold size.
 void setThreshold(int newThreshold)
          The threshold, in bytes, below which items will be retained in memory and above which they will be stored as a file.
 void setURLPrefix(java.lang.String newUrlPrefix)
           
 java.lang.String toString()
          Return this BinaryWrapper as a string description, useful for debugging
 void writeToFile(java.lang.String fileName)
          Convenience method to write the contents to the specified filename
 void writeToStream(java.io.OutputStream bout)
          Write the current content to the specified output stream
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

counter

private static int counter
Counter used in unique identifier generation.


MODE_UNKNOWN

private static final int MODE_UNKNOWN
The mode of this BinaryWrapper has not yet been determined

See Also:
Constant Field Values

MODE_INMEMORY

private static final int MODE_INMEMORY
The content is stored in memory

See Also:
Constant Field Values

MODE_URL

private static final int MODE_URL
The content is stored at a URL location

See Also:
Constant Field Values

MODE_EXECUTABLE

private static final int MODE_EXECUTABLE
This BinaryWrapper represents an executable task, no stored content at all.

See Also:
Constant Field Values

MODE_KEEPINMEMORY

private static final int MODE_KEEPINMEMORY
Content is stored in memory, no matter what it's size (see the setKeepInMemory() method)

See Also:
Constant Field Values

mode

private int mode
The current mode of this BinaryWrapper.


contentType

protected java.lang.String contentType
The content type passed by the browser, or null if not defined (this is typically a mime type and subtype).


fileName

protected java.lang.String fileName
The original filename in originating filesystem. Used for uploaded files


contentFileName

protected transient java.lang.String contentFileName
External filename for content - not retained when serialized


size

protected long size
When the content is supplied, we know it's size. Store this info


sizeThreshold

protected int sizeThreshold
The threshold above which contents will be stored on disk.


repository

protected java.io.File repository
The directory in which uploaded and temporary files will be stored, if stored on disk. Storage to disk only happens if the content size exceeds the threshold, and setKeepInMemory is not called). If we use this feature, the "urlPrefix" below must be set for the client to be able to retrieve the content. The default values are suitable for a single-VM deploy, or a multi-VM deploy on the same server.


urlPrefix

private java.lang.String urlPrefix
If the content we're dealing with is larger than the threshold (defined above), then we must write it to disk on the originating system and read it back from a URL on the destination side. To do this we need a urlPrefix accessible from this server by all destination. This URL prefix has a direct relationship with the repository path, defined above. See the note in the class Javadoc regaring security.


url

private java.lang.String url
The URL to access the content from the "receiving" side of this BinaryWrapper


cachedContent

protected byte[] cachedContent
Cached content, if below the threshold (or setKeepInMemory was called)


execPath

private java.lang.String execPath
A BinaryWrapper can be a reference to an external process (e.g. some other, possibly even non-Java executable application) which will supply the output for this BinaryWrapper. If the execPath is not null, then this BinaryWrapper is pointing to such an executable. This must be used with caution, as the server on which the executable is run may be different from where the request originates!


currentProcess

private transient java.lang.Process currentProcess
Handle to the current process, if any

Constructor Detail

BinaryWrapper

public BinaryWrapper()
Create an uninitialized BinaryWrapper

Method Detail

setKeepInMemory

public void setKeepInMemory()
Insist that the data be kept in memory, no matter the size. If there is no opportunity to use external storage. This essentially disregards the threshold setting.


setFileName

public void setFileName(java.lang.String newName)
Specify the "filename" for this content. Note that this is an informative name, not necessarily where the content is really stored!

Parameters:
newName - Name to set the filename property to

getFileName

public java.lang.String getFileName()
Retrieve the "filename" property of this BinaryWrapper. Note that this is an informative name, not necessarily where the content is in fact stored! For "uploaded" files, this is the original filename specified by the browser.

Returns:
The filename property of this BinaryWrapper.

setContentType

public void setContentType(java.lang.String newType)
Specify the content type of the content to be transferred. This is usually the mime-type used by the browser to display this content.

Parameters:
newType - The mime type of the content of this BinaryWrapper

setRepository

public void setRepository(java.io.File newRepository)
Specify the file repository used to hold content in temporary files if it's size exceeds the threshold size.

Parameters:
newRepository - A File object indicating a writeable directory.

setThreshold

public void setThreshold(int newThreshold)
The threshold, in bytes, below which items will be retained in memory and above which they will be stored as a file. Ignored if setKeelInMemory is called.

Parameters:
newThreshold - A new size in bytes to use as the threshold.

setContent

public void setContent(byte[] newContent)
Set the content cache directly. Makes no attempt to store the content externally unless it is over the threshold size.

Parameters:
newContent - A byte array of content (which may not be null or zero-length)

setExecutablePath

public void setExecutablePath(java.lang.String newPath)
Specify a path to an executable from which this BinaryWrapper get's it's content. You can supply command-line arguments as part of the string, as necessary.

Parameters:
newPath -

isExecutable

public boolean isExecutable()
Does this BinaryWrapper refer to some external executable program in order to get it's content?

Returns:
True if this is an "executable"-style BinaryWrapper, false if it's not.

getInputStream

public java.io.InputStream getInputStream()
                                   throws java.io.IOException
Returns an InputStreamthat can be used to retrieve the contents of this BinaryWrapper.

Returns:
An InputStreamthat can be used to retrieve the contents of the file.
Throws:
java.io.IOException - if an error occurs.

getContentType

public java.lang.String getContentType()
Returns the content type passed by the browser or null if not defined.

Returns:
The content type passed by the browser or null if not defined.

isInMemory

public boolean isInMemory()
Provides a hint as to whether or not the file contents will be read from memory.

Returns:
true if the file contents will be read from memory; false otherwise.

getSize

public long getSize()
Returns the size of the content, if we know it.

Returns:
The size of the content, in bytes.

loadFromURL

public void loadFromURL(java.lang.String url)
                 throws java.io.IOException
Throws:
java.io.IOException

get

public byte[] get()
           throws java.io.IOException
Returns the data as an array of bytes. If the contents were not yet cached in memory, they will be loaded from disk storage first, or accessed from the URL if appropriate.

Returns:
The contents of the file as an array of bytes.
Throws:
java.io.IOException

getString

public java.lang.String getString(java.lang.String encoding)
                           throws java.io.UnsupportedEncodingException,
                                  java.io.IOException
Returns the contents of the file as a String, using the specified encoding. This method uses get()to retrieve the contents of the file.

Parameters:
encoding - The character encoding to use.
Returns:
The contents of the file, as a string.
Throws:
java.io.UnsupportedEncodingException - if the requested character encoding is not available.
java.io.IOException - If the get() method throws an IOException retrieving the content.

getString

public java.lang.String getString()
                           throws java.io.IOException
Returns the contents of the file as a String, using the default character encoding. This method uses get()to retrieve the contents of the file.

Returns:
The contents of the file, as a string.
Throws:
java.io.IOException - If the get() method throws an IOException retrieving the content.

close

public void close()
           throws java.io.IOException
Closes and flushes the underlying output stream.

Throws:
java.io.IOException - Thrown if any errors occur with the output streams

delete

public void delete()
Deletes the underlying storage for a file item, including deleting any associated temporary disk file. Although this storage will be deleted automatically when the FileItem instance is garbage collected, this method can be used to ensure that this is done at an earlier time, thus preserving system resources.


getOutputStream

public java.io.OutputStream getOutputStream()
                                     throws java.io.IOException
Returns an OutputStreamthat can be used for storing the contents of the file.

Returns:
An OutputStreamthat can be used for storing the contensts of the file.
Throws:
java.io.IOException - if an error occurs.

loadFromStream

public void loadFromStream(java.io.InputStream is)
                    throws java.io.IOException
Load the content of this BinaryWrapper from the specified input stream.

Parameters:
is - The input stream to load from
Throws:
java.io.IOException - If an IOException occurs during loading

finalize

protected void finalize()
                 throws java.lang.Throwable
Call release to clean up if we have not already

Throws:
java.lang.Throwable

release

public void release()
             throws java.lang.Throwable
Removes the file contents from the temporary storage.

Throws:
java.lang.Throwable

modeToString

private java.lang.String modeToString(int mode)
Convert the specified mode value into a string

Parameters:
mode - The mode
Returns:
A string representation of the mode

setURLPrefix

public void setURLPrefix(java.lang.String newUrlPrefix)
Parameters:
newUrlPrefix - The urlPrefix to set. See class Javadoc for a description.

toString

public java.lang.String toString()
Return this BinaryWrapper as a string description, useful for debugging

Returns:
String representation of this BinaryWrapper

writeToStream

public void writeToStream(java.io.OutputStream bout)
                   throws java.io.IOException
Write the current content to the specified output stream

Parameters:
bout - The output stream to write the contents to
Throws:
java.io.IOException - If an error occurs during writing

writeToFile

public void writeToFile(java.lang.String fileName)
                 throws java.io.IOException
Convenience method to write the contents to the specified filename

Parameters:
fileName - A full pathname of the output file to write
Throws:
java.io.IOException - If an error occurs during writing.

Keel 2.1RC2

Please see keelframework.org for information about new Keel releases.