com.jcorporate.expresso.services.dbobj
Class MediaDBObject

java.lang.Object
  com.jcorporate.expresso.core.dataobjects.BaseDataObject
      com.jcorporate.expresso.core.dataobjects.jdbc.JDBCDataObject
          com.jcorporate.expresso.core.dbobj.DBObject
              com.jcorporate.expresso.core.dbobj.SecuredDBObject
                  com.jcorporate.expresso.services.dbobj.MediaDBObject

All Implemented Interfaces:

Cacheable, ContextNested, DataObject, LookupInterface, Securable, Serializable

public class MediaDBObject

extends SecuredDBObject

A MediaDBObject is a DBObject intended to be used for storage of media objects directly in the database. It facilitates generic storage by automatically creating filename and MimeType fields that map to the MimeTypes table for easy downloading. This allows for the ability to store more than one media type in the same table while still allowing the Application to appropriately deal with each MimeType.

This data object conveniently stores and retrieves Binary Large OBjects (BLOBS) or Character Large OBjects (CLOBS).

Performance note: Each blob field access requires one more round trip to the database since BLOBs cannot be effectively stored in memory. Thus the lazy loading.

Typical Usage:

 myMediaDBObject = new myMediaDBObject();
 File f = new File("/temp/output.tmp");
 FileOutputStream fos = new FileOutputStream(f);
 myMediaDBObject.setField("id", 2)
 InputStream is = myMediaDBObject.retrieveBlob("picture");
 // Copy the input stream to the file output stream
 myMediaDBObject.release();
 

Since:

Expresso 5.1

Version:

$Revision: 1.9 $ on $Date: 2004/11/17 20:48:18 $

Author:

Michael Rimov, Peter Pilgrim

See Also:

Serialized Form

Nested Class Summary

Nested classes inherited from class com.jcorporate.expresso.core.dbobj.DBObject

DBObject.FieldError, DBObject.FieldUpdate

Field Summary

static String	FLD_FILE_SUFFIX Suffix for the filename field.
static String	FLD_MIME_SUFFIX Suffix for the mime number field.
static String	FLD_SIZE_SUFFIX Suffix for the file size field.

Fields inherited from class com.jcorporate.expresso.core.dbobj.SecuredDBObject

ADD, ALL_FUNCTIONS, CACHE_NAME, CACHE_TTY, DELETE, SEARCH, SYSTEM_ACCOUNT, SYSTEM_ACCOUNT_NAME, UPDATE

Fields inherited from class com.jcorporate.expresso.core.dbobj.DBObject

ATTRIBUTE_ERROR, ATTRIBUTE_ERROR_MESSAGE, ATTRIBUTE_PAGE_LIMIT, BIG_DECIMAL_ZERO, EMAIL_MASK, EVENT_ADD, EVENT_DELETE, EVENT_UPDATE, FLOAT_MASK, INT_MASK, IS_CHECK_RELATIONAL_INTEGRITY, UPDATE_CHANGED_ONLY, WHERE_KEYWORD

Fields inherited from class com.jcorporate.expresso.core.dataobjects.jdbc.JDBCDataObject

anyFieldsDistinct, anyFieldsToRetrieve, appendCustomWhere, caseSensitiveQuery, customWhereClause, dbKey, distinctFields, localConnection, LONGBINARY_READ_DEFAULT_SIZE, maxRecords, myClassName, myUpdates, offsetRecord, recordSet, retrieveFields, sMetadataMap, sortKeys

Fields inherited from class com.jcorporate.expresso.core.dataobjects.BaseDataObject

currentStatus, globalMask

Fields inherited from interface com.jcorporate.expresso.core.dataobjects.DataObject

STATUS_CURRENT, STATUS_DELETED, STATUS_NEW, STATUS_UPDATED

Constructor Summary

MediaDBObject()
Default Constructor.

MediaDBObject(DBConnection newConnection)
Constructor that sets the connection on create

MediaDBObject(DBConnection newConnection, String setupTablesContext)

Constructor that sets a connection as the object is created - typically this is used when a particular DBConnection is required for the purposes of maintaining a database transaction.

MediaDBObject(int newUid)
Constructor: Specify a DB connection AND user

MediaDBObject(RequestContext request)
For using DBObjects within Controllers.

Method Summary

protected void	addBlobField(String fieldName, String fieldDescription) Adds a BLOB field definition to this DBObject.
String	getBlobFilename(String fieldName) Convenience method to get the LOB attachment filename
String	getBlobFileSize(String fieldName) Convenience method to get the LOB attachment content length
int	getBlobFileSizeInt(String fieldName) Convenience method to get the LOB attachment content length as an integer
String	getBlobMimeType(String fieldName) Convenience method to get the LOB attachment mime content type
void	release() Release the associated data with the blob fields.
InputStream	retrieveBlob(String fieldName) Retrieves a BLOB from the database.
void	saveBlob(String fieldName) This method is for saving a BLOB field that has been processed by the DefaultAutoElement object.
void	saveBlob(String fieldName, InputStream value, int fileSize) Saves a file to the blob field,
void	saveBlob(String fieldName, InputStream value, String fileName, int fileSize) Saves a BLOB field to the database

Methods inherited from class com.jcorporate.expresso.core.dbobj.SecuredDBObject

add, canRequesterAdd, canRequesterDelete, canRequesterRead, canRequesterUpdate, checkAllowed, copyAttributes, count, createSecurityCache, delete, deleteAll, find, getRequestingUid, getString, getString, getString, getString, getString, getString, getSystemUid, instantiate, isAllowed, retrieve, search, searchAndRetrieveList, searchAndRetrieveList, setRequestingUid, update

Methods inherited from class com.jcorporate.expresso.core.dbobj.DBObject

addDetail, addField, addField, addFieldError, addFoundKeys, addIfNeeded, addIndex, addKey, addOrUpdate, addSortKey, addTransition, addVirtualField, addVirtualField, addVirtualField, addVirtualField, average, basicAdd, cacheIsChangedComparison, checkAllReferredToBy, checkAllRefs, checkAllRefsPublic, checkDeleteDetailPerm, checkField, checkRef, checkRef, clear, clearDistinctFields, clearError, clearFieldsToRetrieve, clearSortKeys, containsWildCards, delete, deleteAll, deleteDetails, denotesRange, equals, forKey, formatDateTime, get, getAllAttributes, getAttribute, getAttributesIterator, getBooleanFieldValue, getCacheSize, getCacheStatsMap, getCacheUtil, getCheckZeroUpdate, getCustomWhereClause, getDataContext, getDataField, getDataTransferObject, getDBName, getDetails, getDistinctFieldCount, getDistinctFields, getField, getFieldBigDecimal, getFieldBoolean, getFieldByte, getFieldByteArray, getFieldData, getFieldDate, getFieldDecimalFormatted, getFieldDouble, getFieldErrorMessage, getFieldFloat, getFieldInt, getFieldLong, getFieldMetaData, getFieldShort, getFieldsToRetrieveCount, getFilterClass, getFoundCount, getFoundKeysArray, getIndexArray, getISOValuesDefault, getISOValuesDefault, getISOValuesDefault, getKey, getKeyFieldListIterator, getLength, getLengthInt, getLocalConnection, getLocale, getLogger, getLookupObject, getMax, getMax, getMaxRecords, getMyKeys, getMyUpdatesArray, getOffsetRecord, getPatternMatcher, getPrecision, getSerializedForm, getStringFilter, getThisDBbj, getThisDBObj, getValidValueDescrip, getValidValues, getValidValuesList, getValues, getValuesDefault, getValuesDefault, getValuesDefault, hasError, hasErrors, haveAllKeys, initialize, isCached, isChanged, isDistinct, isEmpty, isFieldDistinct, isFieldNull, isFieldsToRetrieve, isFieldToRetrieve, isMultiValued, isReadOnly, isSecret, isVirtual, loadFromConnection, logChange, max, min, newInstance, noNewLine, noQuotes, notifyListeners, populateDefaultValues, referredToBy, removeAttribute, removeFromCache, retrieveFromCache, saveBinaryField, search, set, setAttribute, setCacheSize, setCharset, setCheckZeroUpdate, setConnection, setConnection, setCustomWhereClause, setCustomWhereClause, setDataContext, setDataField, setDataTransferObject, setDefaultValue, setDescription, setField, setField, setField, setField, setField, setField, setField, setField, setField, setField, setFieldData, setFieldData, setFieldDistinct, setFieldsToRetrieve, setFilterClass, setFilterClass, setKeys, setLocale, setLookupField, setLookupObject, setMask, setMaxRecords, setMultiValued, setName, setOffsetRecord, setReadOnly, setSchema, setSecret, setSortKey, setStringFilter, setStringFiltersOnAll, setTargetDbSchema, setTargetTable, setupFields, sqlAggrFunction, sum, toDebugString, update, updateAll, updateAll, verify

Methods inherited from class com.jcorporate.expresso.core.dataobjects.jdbc.JDBCDataObject

addInParam, addOutParam, buildWhereClause, buildWhereClauseBuffer, checkZeroUpdate, constructNewMetaData, createAndExecuteSearch, createAndRunStoreProcedure, getConnectionPool, getCustomStringFieldValue, getDef, getDistinctFieldArrayList, getExecutor, getFieldsToRetrieveIterator, getJDBCMetaData, getJDBCUtil, getMappedDataContext, getMetaData, getQueryInterface, getSerialForm, loadFromConnection, makeLimitationStub, quoteIfNeeded, runStoredProcedure, runStoredProcedureAndRetrieveList, selectFieldString, setCaseSensitiveQuery, setDBConnectionPool, setDBName, setMappedDataContext, setOriginalDBName, setTargetStoreProcedure

Methods inherited from class com.jcorporate.expresso.core.dataobjects.BaseDataObject

getGlobalMask, getStatus, isGlobalMasked, setFieldsWithDefaults, setGlobalMask, setStatus

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FLD_FILE_SUFFIX

public static final String FLD_FILE_SUFFIX

Suffix for the filename field.

Each blob field has several additional supporting fields. The supporting fields have the name of the original BLOB field plus a suffix that is appended to the BLOB field name to get the supporting field

See Also:

Constant Field Values

FLD_MIME_SUFFIX

public static final String FLD_MIME_SUFFIX

Suffix for the mime number field. This field contains a pointer into the MimeTypes table.

Each blob field has several additional supporting fields. The supporting fields have the name of the original BLOB field plus a suffix that is appended to the BLOB field name to get the supporting field

See Also:

Constant Field Values

FLD_SIZE_SUFFIX

public static final String FLD_SIZE_SUFFIX

Suffix for the file size field. This field contains the size of the blob that was saved to the database.

Each blob field has several additional supporting fields. The supporting fields have the name of the original BLOB field plus a suffix that is appended to the BLOB field name to get the supporting field

See Also:

Constant Field Values

Constructor Detail

MediaDBObject

public MediaDBObject()
              throws DBException

Default Constructor.

Throws:

DBException - upon initialization error

MediaDBObject

public MediaDBObject(DBConnection newConnection)
              throws DBException

Constructor that sets the connection on create

Parameters:

newConnection - The dbConnection object to associate with this object

MediaDBObject

public MediaDBObject(DBConnection newConnection,
                     String setupTablesContext)
              throws DBException

Constructor that sets a connection as the object is created - typically this is used when a particular DBConnection is required for the purposes of maintaining a database transaction. If a specific connection is not used, there is no way to use commit() and rollback() in the event of failure, as a different DBConnection might be used for each phase of the transaction. Critial sections should therefore explicity request a DBConnection from the connection pool and pass it to each of the DB objects in that section.

This constructor is neceesary to work with otherDBMap and transaction capabilities

Parameters:

newConnection - The DBConnection to utilize

setupTablesContext - The data context that contains the setup (and security) tables for this object

MediaDBObject

public MediaDBObject(int newUid)
              throws DBException

Constructor: Specify a DB connection AND user

Parameters:

newUid - User ID attempting to use this object. If this is SecuredDBObject.SYSTEM_ACCOUNT, then full permissions are granted. Note that you cannot log in as SecuredDBObject.SYSTEM_ACCOUNT, t can only be used from within a method.

Throws:

DBException - If the object cannot be created

MediaDBObject

public MediaDBObject(RequestContext request)
              throws DBException

For using DBObjects within Controllers. Initializes based upon the current user and the requested db. [Of course this can be modified later]

Parameters:

request - - The controller request handed to you by the framework.

Throws:

DBException - upon construction error

Method Detail

getBlobFilename

public String getBlobFilename(String fieldName)
                       throws DBException

Convenience method to get the LOB attachment filename

Throws:

DBException - if a database error occurs

getBlobMimeType

public String getBlobMimeType(String fieldName)
                       throws DBException

Convenience method to get the LOB attachment mime content type

Throws:

DBException - if a database error occurs

getBlobFileSize

public String getBlobFileSize(String fieldName)
                       throws DBException

Convenience method to get the LOB attachment content length

Throws:

DBException - if a database error occurs

getBlobFileSizeInt

public int getBlobFileSizeInt(String fieldName)
                       throws DBException

Convenience method to get the LOB attachment content length as an integer

Throws:

DBException - if a database error occurs

addBlobField

protected void addBlobField(String fieldName,
                            String fieldDescription)
                     throws DBException

Adds a BLOB field definition to this DBObject.

Using this method creates several supporting fields.

• BlobFieldName + '_mimeType': An integer value that points to the mime type in the MimeTypes table. When the BLOB is retrieved, the content stream mime type can be set allowing for the web browser to properly interpret the incoming stream.
• BlobFieldName + '_fileName': A file name for the BLOB field. While this is optional, it allows the WebBrowser to assign a default file name when it saves the BLOB locally
• BlobFieldName + '_fileSize': This field gets set when a file is uploaded into the database table. It allows for the browser to determine what percentage of the BLOB is transferred to the browser

Parameters:

fieldName - The name of the field to create.

fieldDescription - The 'friendly name' of the field to create

Throws:

DBException - upon creation error.

saveBlob

public void saveBlob(String fieldName)
              throws DBException

This method is for saving a BLOB field that has been processed by the DefaultAutoElement object. We have all the information we need because the file to save, mime types, etc, have all been saved as attributes of the fieldName specified. Do not call this method if you have not either set the appropriate attributes yourself or have called DefaultAutoElement.parseSingleInput().

This method also deletes the uploaded temp file upon completion. Create the File object and call one of the other saveBlob objects yourself if you do not want this behavior.

Parameters:

fieldName - The field Name to save

Throws:

DBException - If unable to save the file to the database

IllegalStateException - if unable to retrieve the appropriate attributes.

IllegalArgumentException - if fieldName doesn't exist or is null.

See Also:

DefaultAutoElement.parseSingleInput(com.jcorporate.expresso.core.controller.ControllerRequest, com.jcorporate.expresso.core.dataobjects.DataObject, java.lang.String, java.lang.String, com.jcorporate.expresso.core.controller.ErrorCollection)

saveBlob

public void saveBlob(String fieldName,
                     InputStream value,
                     String fileName,
                     int fileSize)
              throws DBException

Saves a BLOB field to the database

Parameters:

fieldName - the field Name to save

value - A binary stream to become the value of the new strea,

fileName - The name of the 'file' to store

fileSize - The size of the file to save.

Throws:

DBException

saveBlob

public void saveBlob(String fieldName,
                     InputStream value,
                     int fileSize)
              throws DBException

Saves a file to the blob field,

Parameters:

fieldName - the field name to save to the database

value - A java.io.InputStream to save into the database

fileSize - the size of the stream that is getting saved to the database

Throws:

DBException - upon communication error

retrieveBlob

public InputStream retrieveBlob(String fieldName)
                         throws DBException

Retrieves a BLOB from the database. This functiona allocates a DBConnection object and all the corresponding input streams. You must process the BLOB before doing anything else to this particular DBObject, and then call the release() function to release the DBConnection and close the appropriate InputStreams.

Parameters:

fieldName - The name of the field to retrieve

Returns:

java.io.InputStream the contents of the BLOB field. [May be null]

Throws:

DBException - upon retrieval error

release

public void release()

Release the associated data with the blob fields. Very important that this is called once you've retrieved/set the BLOB fields.