com.ibm.able.platform
Class RmiPlatformPersistenceServiceProxy

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

All Implemented Interfaces:

AblePlatformService, AblePlatformServiceEventGenerator, PlatformPersistenceService, java.io.Serializable, javax.agent.service.Service

public class RmiPlatformPersistenceServiceProxy

extends java.lang.Object

implements PlatformPersistenceService, java.io.Serializable

An RMI Platform Persistence Service proxy contains a reference to an RMI version of a Platform Persistence Service. The proxy contains methods identical to the methods in the actual service. When a method is called on the proxy, the proxy forwards the call on to the actual service. However, the proxy (1) traps all RemoteExceptions that might be thrown by the service, (2) turns the RemoteExceptions into PlatformPersistenceExceptions, and then (3) rethrows the new exception. In this way, code making use of the proxy does not have to be sensitive to RMI RemoteExceptions and can code to a common Platform Persistence Service interface.

See Also:

Serialized Form

Field Summary

Fields inherited from interface com.ibm.able.platform.PlatformPersistenceService

BLOB_TYPE, DELETE_TYPE, INSERT_TYPE, PERSISTENCE_DB_FLUSH_TIME, PERSISTENCE_DB_RESET_ALL, PERSISTENCE_DRIVER, PERSISTENCE_PASSWORD, PERSISTENCE_PROTOCOL, PERSISTENCE_SUBPROTOCOL, PERSISTENCE_USERID, SERVICE_TYPE, UPDATE_TYPE

Constructor Summary

RmiPlatformPersistenceServiceProxy(RmiPlatformPersistenceService theDelegate, java.rmi.registry.Registry theRegistry, java.lang.String theAddress)
Create a proxy over the specified RMI reference to a Platform Persistence Service.

Method Summary

void	addAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener) Adds a service event listener to this service.
void	close(java.lang.String databaseName, java.lang.String tableName, AbleSecureKey key) Closes all connections, both the AbleDBImport and AbleDBExport beans for this database table.
void	createTableConnection(java.lang.String databaseName, java.lang.String tableName, java.lang.String schema, java.lang.String[] columnNames, java.lang.String[] columnTypes, AbleSecureKey key, boolean writeOnly) This creates an AbleDBExport and optionally an AbleDBImport bean and the table these beans will be dealing with if the table does not already exist.
void	delete(java.lang.String databaseName, java.lang.String tableName, java.util.Map whereMap, AbleSecureKey key) Deletes rows from a table.
void	delete(java.lang.String databaseName, java.lang.String tableName, java.lang.String whereString, AbleSecureKey key) Deletes rows from a table.
java.util.Vector	getAblePlatformServiceEventListeners() Gets a collection of all service event listeners registered with this service event generator.
javax.agent.service.ServiceProperties	getServiceProperties() Retrieve the service properties of the underlying service.
int	getState() Returns the state of this service.
void	insert(java.lang.String databaseName, java.lang.String tableName, java.io.Serializable[] insertData, AbleSecureKey key) Insert a record into a table.
void	removeAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener) Removes a service event listener from this service.
java.lang.Object[]	select(java.lang.String databaseName, java.lang.String tableName, java.lang.String columnString, java.lang.String whereString, AbleSecureKey key) Selects data from a table.
void	setServiceProperties(javax.agent.service.ServiceProperties theServiceProperties) Set the service properties of the underlying service.
void	terminateService(AbleSecureKey theSecureKey) Terminates this service in a controlled way; the service is removed from the service root and, if necessary, unbound from the RMI registry and unexported as a remote RMI object.
java.lang.String	toString() Retrieve a string describing (the contents of) the object.
void	update(java.lang.String databaseName, java.lang.String tableName, java.util.Map updateMap, java.util.Map whereMap, AbleSecureKey key) Updates a row in a table.

Methods inherited from class java.lang.Object

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

Constructor Detail

RmiPlatformPersistenceServiceProxy

public RmiPlatformPersistenceServiceProxy(RmiPlatformPersistenceService theDelegate,
                                          java.rmi.registry.Registry theRegistry,
                                          java.lang.String theAddress)

Create a proxy over the specified RMI reference to a Platform Persistence Service.

Parameters:

theDelegate - A reference to an RMI version of a Platform Persistence Service.

theRegistry - The RMI registry at which the above Platform Persistence Service is registered.

theAddress - The RMI address at which the above Platform Persistence Service is registered.

Method Detail

getServiceProperties

public javax.agent.service.ServiceProperties getServiceProperties()

Retrieve the service properties of the underlying service.

Note: In this implementation, the method call is not forwarded on to the service; null is always returned.

Specified by:

getServiceProperties in interface javax.agent.service.Service

Returns:

null at all times.

setServiceProperties

public void setServiceProperties(javax.agent.service.ServiceProperties theServiceProperties)

Set the service properties of the underlying service.

Note: In this implementation, the method call is not forwarded on to the service; the call is simply ignored.

Specified by:

setServiceProperties in interface javax.agent.service.Service

Parameters:

theServiceProperties - The service properties to be used by the service.

addAblePlatformServiceEventListener

public void addAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener)
                                         throws AbleException

Description copied from interface: AblePlatformServiceEventGenerator

Adds a service event listener to this service.

Specified by:

addAblePlatformServiceEventListener in interface AblePlatformServiceEventGenerator

Parameters:

theListener - Any object interested in listening for service events generated by this service.

Throws:

AbleException - If the listener to be added is null, or on any error.

removeAblePlatformServiceEventListener

public void removeAblePlatformServiceEventListener(AblePlatformServiceEventListener theListener)
                                            throws AbleException

Description copied from interface: AblePlatformServiceEventGenerator

Removes a service event listener from this service.

Specified by:

removeAblePlatformServiceEventListener in interface AblePlatformServiceEventGenerator

Parameters:

theListener - A previously registered object that is no longer interested in listening for service events generated by this service.

Throws:

AbleException - If the listener to be removed is null, or on any error.

getAblePlatformServiceEventListeners

public java.util.Vector getAblePlatformServiceEventListeners()
                                                      throws AbleException

Description copied from interface: AblePlatformServiceEventGenerator

Gets a collection of all service event listeners registered with this service event generator.

Specified by:

getAblePlatformServiceEventListeners in interface AblePlatformServiceEventGenerator

Returns:

All registered AblePlatformServiceEventListener objects.

Throws:

AbleException - On any error.

terminateService

public void terminateService(AbleSecureKey theSecureKey)
                      throws AbleException,
                             javax.agent.service.naming.NamingException

Description copied from interface: AblePlatformService

Terminates this service in a controlled way; the service is removed from the service root and, if necessary, unbound from the RMI registry and unexported as a remote RMI object.

Specified by:

terminateService in interface AblePlatformService

Parameters:

theSecureKey - When security if off, this may be null as the parameter is ignored; when security is on the security key must be from an object with equal or greater authority in order for the operation to proceed.

Throws:

javax.agent.service.naming.NamingException - On any naming error.

AbleException - On any remote error or Able error.

getState

public int getState()
             throws AbleException

Description copied from interface: AblePlatformService

Returns the state of this service.

Specified by:

getState in interface AblePlatformService

Returns:

The state of this service.

Throws:

AbleException - On any remote error or Able error.

createTableConnection

public void createTableConnection(java.lang.String databaseName,
                                  java.lang.String tableName,
                                  java.lang.String schema,
                                  java.lang.String[] columnNames,
                                  java.lang.String[] columnTypes,
                                  AbleSecureKey key,
                                  boolean writeOnly)
                           throws PlatformPersistenceException

Description copied from interface: PlatformPersistenceService

This creates an AbleDBExport and optionally an AbleDBImport bean and the table these beans will be dealing with if the table does not already exist. The Export bean will be used in the future to alter the table in any way, and the Import bean will be used to read info from the table.

Specified by:

createTableConnection in interface PlatformPersistenceService

Parameters:

databaseName - The name of the Database that the table will exist in.

tableName - The name of the table.

schema - The schema of the table.

columnNames - String[] containing the name of each column for this table.

columnTypes - String[] containing the type of each column for this table.

key - AbleSecureKey used to secure communication.

writeOnly - When true, the service is output only.

Throws:

PlatformPersistenceException -

If unable to verify the key when the platform is secure.

If databaseName is null.

If tableName is null.

If columnNames is null.

If columnTypes is null.

If columnTypes and columnNames are of different lengths.

On errors creating the table.

insert

public void insert(java.lang.String databaseName,
                   java.lang.String tableName,
                   java.io.Serializable[] insertData,
                   AbleSecureKey key)
            throws PlatformPersistenceException

Description copied from interface: PlatformPersistenceService

Insert a record into a table.

Specified by:

insert in interface PlatformPersistenceService

Parameters:

databaseName - The name of the Database that the table will exist in.

tableName - The name of the table to insert into.

insertData - Serializable[] containing the data that is to be inserted into the table.

key - AbleSecureKey used to secure communication.

Throws:

PlatformPersistenceException -

If the insertData is null.

If unable to verify the key when the platform is secure.

If secure and the caller is not the one who originally set up the connection to this table.

If the table connection does not exist.

update

public void update(java.lang.String databaseName,
                   java.lang.String tableName,
                   java.util.Map updateMap,
                   java.util.Map whereMap,
                   AbleSecureKey key)
            throws PlatformPersistenceException

Description copied from interface: PlatformPersistenceService

Updates a row in a table.

Specified by:

update in interface PlatformPersistenceService

Parameters:

databaseName - The name of the DB that the table will exist in.

tableName - The name of the table.

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.

key - AbleSecureKey used to secure communication.

Throws:

PlatformPersistenceException -

If the updateMap is null.

If unable to verify the key when the platform is secure.

If secure and the caller is not the one who originally set up the connection to this table.

If the table connection does not exist.

delete

public void delete(java.lang.String databaseName,
                   java.lang.String tableName,
                   java.lang.String whereString,
                   AbleSecureKey key)
            throws PlatformPersistenceException

Description copied from interface: PlatformPersistenceService

Deletes rows from a table.

Specified by:

delete in interface PlatformPersistenceService

Parameters:

databaseName - The name of the DB that the table will exist in.

tableName - The name of the table.

whereString - This is the simple String that states the where clause of the delete. If left null or blank, everything will be deleted.

key - AbleSecureKey used to secure communication.

Throws:

PlatformPersistenceException -

If unable to verify the key when the platform is secure.

If secure and the caller is not the one who originally set up the connection to this table.

If the table connection does not exist.

delete

public void delete(java.lang.String databaseName,
                   java.lang.String tableName,
                   java.util.Map whereMap,
                   AbleSecureKey key)
            throws PlatformPersistenceException

Description copied from interface: PlatformPersistenceService

Deletes rows from a table.

Specified by:

delete in interface PlatformPersistenceService

Parameters:

databaseName - The name of the DB that the table will exist in

tableName - The name of the table

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.

key - AbleSecureKey used to secure communication.

Throws:

PlatformPersistenceException -

If unable to verify the key when the platform is secure.

If secure and the caller is not the one who originally set up the connection to this table.

If the table connection does not exist.

close

public void close(java.lang.String databaseName,
                  java.lang.String tableName,
                  AbleSecureKey key)
           throws PlatformPersistenceException

Description copied from interface: PlatformPersistenceService

Closes all connections, both the AbleDBImport and AbleDBExport beans for this database table.

Specified by:

close in interface PlatformPersistenceService

Parameters:

databaseName - The name of the DB that the table will exist in.

tableName - The name of the table.

key - AbleSecureKey used to secure communication.

Throws:

PlatformPersistenceException -

If unable to verify the key when the platform is secure.

If secure and the caller is not the one who originally set up the connection to this table.

If the table connection does not exist.

select

public java.lang.Object[] select(java.lang.String databaseName,
                                 java.lang.String tableName,
                                 java.lang.String columnString,
                                 java.lang.String whereString,
                                 AbleSecureKey key)
                          throws PlatformPersistenceException

Description copied from interface: PlatformPersistenceService

Selects data from a table.

Specified by:

select in interface PlatformPersistenceService

Parameters:

databaseName - The name of the DB that the table will exist in.

tableName - The name of the table.

columnString - The columns that are to be returned in a select statement. If left blank or null, all columns will be returned.

whereString - The where string of the select statement. If left blank or null, everything will be returned.

key - AbleSecureKey used to secure communication.

Returns:

An Object[] of Object[]s, each containing a returned row from the select statement.

Throws:

PlatformPersistenceException -

If unable to verify the key when the platform is secure.

If secure and the caller is not the one who originally set up the connection to this table.

If the table connection does not exist.

On errors deserializing a Blob.

If the persisted data selected is not of a valid type.

toString

public java.lang.String toString()

Retrieve a string describing (the contents of) the object.

Returns:

A String containing the current contents of the object.