com.ibm.able.platform
Class AblePersistenceSupport

java.lang.Object
  com.ibm.able.platform.AblePersistenceSupport

All Implemented Interfaces:

AbleEventQueueProcessor

public final class AblePersistenceSupport

extends java.lang.Object

implements AbleEventQueueProcessor

AblePersistenceSupport is a support Object that others can use to persist information.

Services and Agents and any other part of the platform may wish to persist information, and to do so, they can instantiate one of these Objects. In AblePersistenceSupport's ctor, the database and table to write to, the format of this table, and some addtional processing information will be passed in.

The use of this support object is dependant on the AblePlatformPersistenceService being up and running in the platform. If this object attempts to persist some information while the AblePlatformPersistenceService is not ready to be used, this support object will queue up these missed persist actions and attempt them when the service becomes available.

The class that creates one of these support objects should also implement the AblePersistenceSupportProcessor interface. This is necessary so this support object can call back to the AblePersistenceSupportProcessor that created it and pass back all previously persisted information.

Field Summary

static int	PERSIST_ACTION_ADD Different types of persist actions that can occur
static int	PERSIST_ACTION_REMOVE_MAP
static int	PERSIST_ACTION_REMOVE_STRING
static int	PERSIST_ACTION_UPDATE_MAP

Constructor Summary

AblePersistenceSupport(java.lang.String thePersistenceDatabaseName, java.lang.String thePersistenceTableName, java.lang.String thePersistenceSchema, java.lang.String[] thePersistenceTableColumnNames, java.lang.String[] thePersistenceTableColumnTypes, long thePPSIntervalCheckTime, AblePersistenceSupportProcessor theProcessor, AbleSecuritySupport theSecuritySupport)
Creates a new AblePersistenceSupport with the supplied properties.

AblePersistenceSupport(java.lang.String thePersistenceDatabaseName, java.lang.String thePersistenceTableName, java.lang.String thePersistenceSchema, java.lang.String[] thePersistenceTableColumnNames, java.lang.String[] thePersistenceTableColumnTypes, long thePPSIntervalCheckTime, AblePersistenceSupportProcessor theProcessor, AbleSecuritySupport theSecuritySupport, boolean theWriteOnlyFlag)
Creates a new AblePersistenceSupport with the supplied properties.

Method Summary

boolean	delete(java.util.Map whereMap) Handles deleting a record from the table this support Object is dealing with.
boolean	delete(java.lang.String whereString) Handles deleting a record from the table this support Object is dealing with.
static java.io.Serializable	Deserialize(byte[] objInBytes) Deserializes the given byte array into a Serializable object with the state of the object restored to when it was serialized.
java.lang.String	getDatabaseName() Gets the name of the database used by this persistence support object.
AbleLogger	getLogger() Returns a message logger object from the event queue's container.
int	getState() Returns the state of the event queue's container.
java.lang.String[]	getTableColumnNames() Gets a collection of the names of the columns in the table used by this persistence support object.
java.lang.String[]	getTableColumnTypes() Gets a collection of the data types of the columns in the table used by this persistence support object.
java.lang.String	getTableName() Gets the name of the database table used by this persistence support object.
boolean	insert(java.io.Serializable[] row) Handles inserting a record into the table this support Object is dealing with.
static boolean	isBaseSQLObject(java.lang.Object obj) Determines if the passed in Object is one of the SQL base Object types.
java.io.Serializable	nextId(java.lang.String columnName) Return the row id number for the next record to write to the log.
void	processAbleEvent(AbleEvent theAbleEvent) Processes an Able event synchronously; that is, on the same thread as the caller.
void	processNoEventProcessingEnabledSituation() Processes the situation where neither timer nor Able event processing is enabled in the event queue, but the event queue's asynchronous thread of control has been started.
void	processTimerEvent() This will be called if we are waiting for the PlatformPersistenceService to get back up.
void	quitAll() This method will nicely shut down this AblePersistenceSupport Object.
static byte[]	Serialize(java.io.Serializable obj) Serializes the given Object into a byte array.
void	setState(int theState) Sets the state of the event queue's container.
boolean	update(java.util.Map updateMap, java.util.Map whereMap) Handles updating a record in the table this support Object is dealing with.

Methods inherited from class java.lang.Object

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

Field Detail

PERSIST_ACTION_ADD

public static final int PERSIST_ACTION_ADD

Different types of persist actions that can occur

See Also:

Constant Field Values

PERSIST_ACTION_UPDATE_MAP

public static final int PERSIST_ACTION_UPDATE_MAP

See Also:

Constant Field Values

PERSIST_ACTION_REMOVE_STRING

public static final int PERSIST_ACTION_REMOVE_STRING

See Also:

Constant Field Values

PERSIST_ACTION_REMOVE_MAP

public static final int PERSIST_ACTION_REMOVE_MAP

See Also:

Constant Field Values

Constructor Detail

AblePersistenceSupport

public AblePersistenceSupport(java.lang.String thePersistenceDatabaseName,
                              java.lang.String thePersistenceTableName,
                              java.lang.String thePersistenceSchema,
                              java.lang.String[] thePersistenceTableColumnNames,
                              java.lang.String[] thePersistenceTableColumnTypes,
                              long thePPSIntervalCheckTime,
                              AblePersistenceSupportProcessor theProcessor,
                              AbleSecuritySupport theSecuritySupport)

Creates a new AblePersistenceSupport with the supplied properties.

An AblePersistenceSupport is a support Object that others will use to persist information.

Parameters:

thePersistenceDatabaseName - The database that this persistence support will be using.

thePersistenceTableName - The table that this persistence support will be using.

thePersistenceSchema - The schema of the table that this persistence support will be using.

thePersistenceTableColumnNames - The column names of the table that is being persisted to.

thePersistenceTableColumnTypes - The column types of the table that is being persisted to.

thePPSIntervalCheckTime - The interval between checks to the PlatformPersistenceService to see if the PlatformPersistenceService is up and ready.

theProcessor - The AblePersistenceSupportProcessor that will be called back to with the persisted information this AblePersistenceSupport grabs from persistence.

theSecuritySupport - The AbleSecuritySupport Object that will assist in security issues.

AblePersistenceSupport

public AblePersistenceSupport(java.lang.String thePersistenceDatabaseName,
                              java.lang.String thePersistenceTableName,
                              java.lang.String thePersistenceSchema,
                              java.lang.String[] thePersistenceTableColumnNames,
                              java.lang.String[] thePersistenceTableColumnTypes,
                              long thePPSIntervalCheckTime,
                              AblePersistenceSupportProcessor theProcessor,
                              AbleSecuritySupport theSecuritySupport,
                              boolean theWriteOnlyFlag)

Creates a new AblePersistenceSupport with the supplied properties.

An AblePersistenceSupport is a support Object that others will use to persist information.

Parameters:

thePersistenceDatabaseName - The database that this persistence support will be using.

thePersistenceTableName - The table that this persistence support will be using.

thePersistenceSchema - The schema of the table that this persistence support will be using.

thePersistenceTableColumnNames - The column names of the table that is being persisted to.

thePersistenceTableColumnTypes - The column types of the table that is being persisted to.

thePPSIntervalCheckTime - The interval between checks to the PlatformPersistenceService to see if the PlatformPersistenceService is up and ready.

theProcessor - The AblePersistenceSupportProcessor that will be called back to with the persisted information this AblePersistenceSupport grabs from persistence.

theSecuritySupport - The AbleSecuritySupport Object that will assist in security issues.

theWriteOnlyFlag - If true, only the export object is created. The table will be used for output only.

Method Detail

processAbleEvent

public void processAbleEvent(AbleEvent theAbleEvent)
                      throws AbleException

Description copied from interface: AbleEventQueueProcessor

Processes an Able event synchronously; that is, on the same thread as the caller.

This method is called by the AbleEventQueue when an event is removed from the queue for asynchronous processing. Note that this method also can be called directly from the handleAbleEvent() method described in the AbleEventListener interface when that method is given a synchronous event to handle.

Specified by:

processAbleEvent in interface AbleEventQueueProcessor

Parameters:

theAbleEvent - The event to process.

Throws:

AbleException - If an error occurs.

processTimerEvent

public void processTimerEvent()
                       throws AbleException

This will be called if we are waiting for the PlatformPersistenceService to get back up. This method will check if the PlatformPersistenceService is up and ready. If so, all missed persist actions will be pushed to the PlatformPersistenceService. If not, nothing will be done, processing missed persist actions will be attempted again at the next interval.

Specified by:

processTimerEvent in interface AbleEventQueueProcessor

Throws:

AbleException

processNoEventProcessingEnabledSituation

public void processNoEventProcessingEnabledSituation()
                                              throws AbleException

Description copied from interface: AbleEventQueueProcessor

Processes the situation where neither timer nor Able event processing is enabled in the event queue, but the event queue's asynchronous thread of control has been started.

This method is called by an AbleEventQueue when the queue is neither enabled for timer processing nor Able event processing. When neither type of processing is enabled, the queue is in a tight processing loop, consuming CPU cycles. This method is called so that the event queue's container can do something about the situation or perform some other type of asynchronous processing.

Specified by:

processNoEventProcessingEnabledSituation in interface AbleEventQueueProcessor

Throws:

AbleException - If an error occurs.

setState

public void setState(int theState)
              throws AbleException

Description copied from interface: AbleEventQueueProcessor

Sets the state of the event queue's container.

This method is called by an AbleEventQueue when the queue's run time loop changes state; for example, from Waiting to Active.

Specified by:

setState in interface AbleEventQueueProcessor

Parameters:

theState - An AbleState value.

Throws:

AbleException - If an error occurs.

getState

public int getState()
             throws AbleException

Description copied from interface: AbleEventQueueProcessor

Returns the state of the event queue's container.

This method is called by an AbleEventQueue when the queue needs to interrogate the state of its container.

Specified by:

getState in interface AbleEventQueueProcessor

Returns:

An AbleState value.

Throws:

AbleException - If an error occurs.

getLogger

public AbleLogger getLogger()
                     throws AbleException

Description copied from interface: AbleEventQueueProcessor

Returns a message logger object from the event queue's container.

Specified by:

getLogger in interface AbleEventQueueProcessor

Returns:

a Logger object.

Throws:

AbleException - If an error occurs.

getDatabaseName

public final java.lang.String getDatabaseName()

Gets the name of the database used by this persistence support object.

Returns:

the name of the database.

getTableName

public final java.lang.String getTableName()

Gets the name of the database table used by this persistence support object.

Returns:

the name of the database table.

getTableColumnNames

public final java.lang.String[] getTableColumnNames()

Gets a collection of the names of the columns in the table used by this persistence support object.

Returns:

a collection of column names.

getTableColumnTypes

public final java.lang.String[] getTableColumnTypes()

Gets a collection of the data types of the columns in the table used by this persistence support object.

Returns:

a collection of data types; for example, if the DB table has a single column of type Object, ["java.lang.Object"] is returned.

insert

public boolean insert(java.io.Serializable[] row)

Handles inserting a record into the table this support Object is dealing with.

Parameters:

row - An Serializable[] representing the row that is to be inserted.

Returns:

boolean indicating success when the persist was sent to the PlatformPersistenceService, or failure if the persist action had to be cached.

update

public boolean update(java.util.Map updateMap,
                      java.util.Map whereMap)

Handles updating a record in the table this support Object is dealing with.

Parameters:

updateMap - This is the new data for the record that is to be updated. This is a Map where the keys are the column names and the values are the column values. When using a Map the columns that are not changing do not have to be presents.

whereMap - This is a Map that will be used to build the where clause. The keys will be the column names, and the values will be the Object to match to for their respective column. If left null, or empty, everything will be deleted.

Returns:

boolean indicating success when the persist was sent to the PlatformPersistenceService, or failure if the persist action had to be cached.

delete

public boolean delete(java.lang.String whereString)

Handles deleting a record from the table this support Object is dealing with.

Parameters:

whereString - The where string for the update statement that will specify which records are to be updated.

Returns:

boolean indicating success when the persist was sent to the PlatformPersistenceService, or failure if the persist action had to be cached.

delete

public boolean delete(java.util.Map whereMap)

Handles deleting a record from the table this support Object is dealing with.

Parameters:

whereMap - This is a Map that will be used to build the where clause. The keys will be the column names, and the values will be the Object to match to for their respective column. If left null, or empty, everything will be deleted.

Returns:

boolean indicating success when the persist was sent to the PlatformPersistenceService, or failure if the persist action had to be cached.

quitAll

public void quitAll()

This method will nicely shut down this AblePersistenceSupport Object. It will attempt to end the event event queue, flush out all missed persist actions one last time, and tell the PlatformPersistenceService to clean up the connection that this AblePersistenceSupport Object was using.

isBaseSQLObject

public static boolean isBaseSQLObject(java.lang.Object obj)

Determines if the passed in Object is one of the SQL base Object types. If it is, then it should not have to be serialized into a byte[] before persisting to the database. If it is not one of these types, it will be stored as a byte[] into the database.

A byte[] cannot be considered a base type because we will assume that all byte[]s returned from persistence will need to be deserialized back into a Serializable, not a byte[].

The following are considered base SQL Object tyeps:

• Array
• BigDecimal
• Blob
• Boolean
• Byte
• Clob
• Date
• Double
• Float
• Long
• Integer
• Ref
• Short
• String
• Time
• TimeStamp
• URL

Parameters:

obj - Object to be check if it is one of the base SQL Object types.

Returns:

boolean true if obj is a base SQL Object type, otherwise false.

Serialize

public static byte[] Serialize(java.io.Serializable obj)
                        throws AbleException

Serializes the given Object into a byte array. The input Object must implement the Serializable interface.

Parameters:

obj - Serializable object to be serialized.

Returns:

byte [] that is the serialized version of the specified object.

Throws:

AbleException - If the serialization was not successful.

Deserialize

public static java.io.Serializable Deserialize(byte[] objInBytes)
                                        throws AbleException

Deserializes the given byte array into a Serializable object with the state of the object restored to when it was serialized.

Parameters:

objInBytes - byte [] that is the byte array of a Serialized object to be restored.

Returns:

Object that is the object restored from the Serialized byte array.

Throws:

AbleException - If the deserialization was not successful.

nextId

public java.io.Serializable nextId(java.lang.String columnName)

Return the row id number for the next record to write to the log. Increments the number for the next call.

Parameters:

columnName - The name of the column in the ABLEPLATFORMLOG table used as a row identifier.

Returns:

One plus the maximum value of the ID column in the table.