com.ibm.etill.framework.admin
Class AdminObject

java.lang.Object
  |
  +--com.ibm.etill.framework.admin.AdminObject
All Implemented Interfaces:
com.ibm.etill.framework.archive.Archivable, PSServerAdminConstants
Direct Known Subclasses:
AccountAdmin, CassetteAdmin, MerchantAdmin, PaySystemAdmin

public abstract class AdminObject
extends Object
implements com.ibm.etill.framework.archive.Archivable, PSServerAdminConstants

AdminObject is the base class for all classes that represent primary administrative objects within the Payment Engine.

Cassette writers extend this class to define their own primary administrative objects. Such classes should be developed in conjunction with a corresponding subclass of com.ibm.etill.framework.xdm.PSServerAdminObject to support query API commands. This is explained in more detail in Relationship to Query Classes below. For now, however it is important to understand that instances of classes that extend AdminObject exist in the Payment Engine and represent the effective configuration for the Commerce Payments instance as long as they exist.

Overview of Commerce Payments Administrative Objects
There are two types of administrative objects that cassettes need to manipulate:

  1. Primary administrative objects (or simply primary objects) are those that define a separate configurable entity within the Payment Engine. The Framework defines several primary objects, such as PayServer, CassetteAdmin, PaySystemAdmin, AccountAdmin and so on.

    Cassettes may define their own primary objects when the payment protocol depends upon some type of configurable entity that does not exist in the Commerce Payments Framework. There are two forms of cassette-specific primary objects:

  2. Cassette-specific extensions are data items that augment a Framework primary administration object. For example, an AccountAdmin object contains the Framework's information about a given account, so a cassette extension to such an object would contain the cassette's own information regarding that account.

    While cassette extensions are typically contained within a single cassette-defined object, there is no predefined way that cassettes must build such objects. In other words, "extension" does not imply that the cassette must extend any particular base class in the Java sense of the word. Instead, administration API commands are simply forwarded to the Cassette object's service method for processing. From there, the cassette decides how to handle the request, including which of its internal objects to update.

Properties maintained by AdminObject
All primary administrative objects share certain properties which are implemented through this base class. These properties describe the current state of the object as the Payment Engine sees it. Specifically, these are:

enabled
a configurable property that indicates whether or not the system should attempt to activate the object. On startup, the Payment Server will try to initialize all objects that have their enabled property set to true. When the value of enabled is modified through the API, Commerce Payments will attempt to start or stop the object for true and false values, respectively. The methods that manipulate the enabled property (setEnabled and getEnabled) are defined within this class.
active
an information (non-configurable) property that indicates whether the object is currently active. Note that setting the enabled property to false will stop an object and set the active property to false. Setting enabled to true will result in an attempt to start the object; if the startup is successful, then the active property will be set to true. If an object "fails" for whatever reason, the active property of that object should be set to false. The methods that manipulate the active property (setActive and getActive) are defined within this class.
valid
an information (non-configurable) property that indicates whether or not the object has problems which may prevent it from starting. The class that extends AdminObject is responsible for setting this property value to true once the object has started successfully. If the start operation fails, the subclass should throw an ETillAbortOperation exception, causing the value to be set to false.
changesPending
an information (non-configurable) property that indicates whether or not the current configuration of the object that is stored in the database (as it would be viewed through a query API command) precisely matches the configuration of this in-memory object. This value is used in conjunction with properties whose values can only be changed when the object is not active. If a user attempts to change such a property while the object is active, the value will be changed in the database and changesPending will be set to true. The next time the object is started, the new value will take effect and changesPending will be reset to false. The methods that manipulate the active property (setActive and getActive) are defined within this class.

Responsibilities of AdminObject subclasses
Since AdminObject is an abstract class, classes that extend AdminObject must implement the abstract methods described below. Furthermore, all properties and characteristics required by the objects represented by the subclass (other than those described above) must be defined and implemented within the subclass.

Database Tables
Each type of primary administrative object is expected to have a dedicated table in the Commerce Payments database. Every instance of that object would occupy one row in the table. While the layout and contents of that table are up to the cassette writer, AdminObject does impose a small number of requirements. Specifically, AdminObject contains code that creates, updates and reads from specific columns in the database table identified by the subclass. This code assumes that the column names are as follows and that they appear consecutively, in the specified order, within the table definition:

Relationship to Query Classes
As previously mentioned, each administrative object exists and is maintained within the Payment Engine. The external view of these objects through the Commerce Payments Query commands typically represents a subset of the information that is actually maintained in the database. In addition, since Query commands provide a purely read-only access to the data in the Commerce Payments database, the processing of these commands occurs under a different JVM than the Payment Engine. Specifically, Query commands are processed within the Payment Servlet. Because of this separation of processing responsibilities across the two different JVMs, and because of the fundamentally different requirements of the two command subsets (administrative commands, which alter the Commerce Payments configuration, and query commands which simply report the current state of the database), two different class hierarchies are defined to implement the functions:

As cassettes are developed, each of these types of classes should be developed to represent each of the cassette's primary objects.

See Also:
CassetteConfigObject, CassetteExtensionObject, com.ibm.etill.framework.cassette.query.CassetteProperty, PSServerAdminObject

Field Summary
protected  boolean active
          Contains this object's active status
protected static String ADMINCREATEQUESTIONMARKS
          Used in SQL commands to create this AdminObject.
protected static String ADMINCREATESTRING
          Used in SQL commands to manage this object's basic properties.
protected static String ADMINUPDATESTRING
          Used in SQL commands to update this AdminObject.
protected  boolean enabled
          Contains this object's enabled status
protected  String invalidListKey
          Used internally.
protected  boolean valid
          Contains this object's active status.
 
Fields inherited from interface com.ibm.etill.framework.xdm.PSServerAdminConstants
COL_ACTIVE, COL_ENABLED, COL_MESSAGESKEY, COL_PENDING, COL_VALID
 
Constructor Summary
protected AdminObject()
          Constructs an AdminObject and sets the active property to false.
protected AdminObject(Boolean enabled)
          Constructs an AdminObject, setting the enabled property as specified and the active property to false Since AdminObject is an abstract class, this constructor must be called from a subclass's constructor.
 
Method Summary
 void addCassetteMessage(String message)
          Cassettes call this method to add message text which will be returned through query API commands and displayed by the Commerce Payments user interface.
 void addFrameworkMessage(String message)
          Cassettes should not call this method.
protected  void deleteObject()
          Subclasses can override this method so that it deletes this AdminObject.
 boolean getActive()
          Returns the current setting of this object's active property.
 boolean getEnabled()
          Returns the current setting of this object's enabled property.
 Hashtable getInvalidList()
          Cassette should not call this method.
 boolean getPending()
          Returns the current setting of this object's changesPending property.
protected  void initializeCommon(PSServerAdminObject queryObject)
          Initializes this AdminObject using the enabled property from the input PSServerAdminObject, which is assumed to have been used to read the object contents from the database.
protected  void initializeCommon(ResultSet rs)
          Initializes this AdminObject using the enabled property directly from the input ResultSet, which is assumed to contain the object contents read directly from the database.
 void processConfigurationChanges()
          Called by the Framework to perform any actions required by a configuration change.
static void processExtension(AdminRequest request)
          Called by the Framework to process the cassette extension to the input AdminRequest object.
 void setActive(boolean value)
          Updates this object's active property to the input value.
protected  int setCommonDatabaseFields(Connection conn, PreparedStatement pstmt, int index)
          Modifies the input PreparedStatement in order to update this object's database representation with the most current enabled, active, valid and changesPending property values.
 void setEnabled(boolean value)
          Updates this object's enabled property to the input value.
 void setEnabled(Boolean value)
          Updates this object's enabled property to the input value.
 void setPending(boolean value)
          Updates this object's changesPending property to the input value.
abstract  void startObject()
          Implemented by subclasses to start this AdminObject.
abstract  void stopObject()
          Implemented by subclasses to stop this AdminObject.
abstract  String toString()
          Implemented by subclasses to format this AdminObject for tracing purposes.
static void validateExtension(AdminRequest request)
          Called by the Framework to validate the parameters for the cassette-specific extension to the input AdminRequest object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.ibm.etill.framework.archive.Archivable
createRecord, deleteRecord, updateRecord
 

Field Detail

ADMINCREATESTRING

protected static final String ADMINCREATESTRING
Used in SQL commands to manage this object's basic properties.

ADMINCREATEQUESTIONMARKS

protected static final String ADMINCREATEQUESTIONMARKS
Used in SQL commands to create this AdminObject.

ADMINUPDATESTRING

protected static final String ADMINUPDATESTRING
Used in SQL commands to update this AdminObject.

enabled

protected boolean enabled
Contains this object's enabled status

active

protected boolean active
Contains this object's active status

valid

protected boolean valid
Contains this object's active status. The subclass must set this value to true once the object has been successfully started so that its is correctly reflected in the database.

invalidListKey

protected String invalidListKey
Used internally.
Constructor Detail

AdminObject

protected AdminObject()
Constructs an AdminObject and sets the active property to false. Since AdminObject is an abstract class, this constructor must be called from a subclass's constructor.

AdminObject

protected AdminObject(Boolean enabled)
Constructs an AdminObject, setting the enabled property as specified and the active property to false Since AdminObject is an abstract class, this constructor must be called from a subclass's constructor.
Parameters:
enabled - a Boolean object that contains the initial enabled property value. If a null is passed, the property is set to false.
Method Detail

initializeCommon

protected void initializeCommon(PSServerAdminObject queryObject)
Initializes this AdminObject using the enabled property from the input PSServerAdminObject, which is assumed to have been used to read the object contents from the database.
Parameters:
queryObject - the PSServerAdminObject used to extract the contents of the object from the database.

initializeCommon

protected void initializeCommon(ResultSet rs)
Initializes this AdminObject using the enabled property directly from the input ResultSet, which is assumed to contain the object contents read directly from the database.
Parameters:
rs - a ResultSet containing the contents of the object as it is currently stored in the database.

deleteObject

protected void deleteObject()
Subclasses can override this method so that it deletes this AdminObject. The implementation of this method in AdminObject does nothing.

setCommonDatabaseFields

protected int setCommonDatabaseFields(Connection conn,
                                      PreparedStatement pstmt,
                                      int index)
                               throws SQLException,
                                      com.ibm.etill.framework.payapi.ETillAbortOperation
Modifies the input PreparedStatement in order to update this object's database representation with the most current enabled, active, valid and changesPending property values.
Parameters:
conn - a java.sql.Connection object representing the database connection.
pstmt - a java.sql.PreparedStatement that's been initialized to update this object's record in the appropriate database table.
index - an int that contains the index into the pstmt's parameter set at which to set the property values.
Returns:
int - the pstmt index at which the next parameter (if any) should be placed.
Throws:
SQLException - thrown if there are SQL or JDBC errors
com.ibm.etill.framework.payapi.ETillAbortOperation - if there is a catastrophic error from ETillArchive

processConfigurationChanges

public final void processConfigurationChanges()
                                       throws com.ibm.etill.framework.payapi.ETillAbortOperation
Called by the Framework to perform any actions required by a configuration change. Specifically, if this object is enabled, but not active, then this method attempts to start it. If this object is disabled and active, then this method attempts to stop it. In either of these cases, the object state is committed to the database after the operation completes. For any other case, no action is taken.

This method cannot be overridden by subclasses.

Throws:
com.ibm.etill.framework.payapi.ETillAbortOperation - thrown if the start, stop or commit operation fails.

processExtension

public static void processExtension(AdminRequest request)
                             throws com.ibm.etill.framework.payapi.ETillAbortOperation
Called by the Framework to process the cassette extension to the input AdminRequest object. This method is called after the generic object has been processed and the cassette has validated the request parameters for its extension.
Parameters:
request - an AdminRequest object that has been processed for the generic object and validated by the cassette.
Throws:
com.ibm.etill.framework.payapi.ETillAbortOperation - thrown by the cassette if an error occurs while processing the extension.

validateExtension

public static void validateExtension(AdminRequest request)
                              throws com.ibm.etill.framework.payapi.ETillAbortOperation
Called by the Framework to validate the parameters for the cassette-specific extension to the input AdminRequest object.
Parameters:
request - an AdminRequest object to validate.
Throws:
com.ibm.etill.framework.payapi.ETillAbortOperation - thrown if a validation error occurs.

startObject

public abstract void startObject()
                          throws com.ibm.etill.framework.payapi.ETillAbortOperation
Implemented by subclasses to start this AdminObject. The Framework calls this method as required.
Throws:
com.ibm.etill.framework.payapi.ETillAbortOperation - thrown if the object cannot be started.

stopObject

public abstract void stopObject()
                         throws com.ibm.etill.framework.payapi.ETillAbortOperation
Implemented by subclasses to stop this AdminObject. The Framework calls this method as required.
Throws:
com.ibm.etill.framework.payapi.ETillAbortOperation - thrown if the object cannot be stopped.

toString

public abstract String toString()
Implemented by subclasses to format this AdminObject for tracing purposes.
Overrides:
toString in class Object
Returns:
String - a string representation of the key elements of this AdminObject.

getActive

public boolean getActive()
Returns the current setting of this object's active property.
Returns:
boolean - true if the object is currently active, false if not.

setActive

public void setActive(boolean value)
Updates this object's active property to the input value.
Parameters:
value - - a boolean containing the new setting.

getEnabled

public boolean getEnabled()
Returns the current setting of this object's enabled property.
Returns:
boolean - true if the object is currently enabled, false if not.

setEnabled

public void setEnabled(boolean value)
Updates this object's enabled property to the input value.
Parameters:
value - - a boolean containing the new setting.

setEnabled

public void setEnabled(Boolean value)
Updates this object's enabled property to the input value. If the input value is null, the enabled property is not changed
Parameters:
value - - a Boolean containing the new setting, which may be null.

getPending

public boolean getPending()
Returns the current setting of this object's changesPending property.
Returns:
boolean - true if the object currently has pending changes, false if not.

setPending

public void setPending(boolean value)
Updates this object's changesPending property to the input value.
Parameters:
value - - a boolean containing the new setting.

addCassetteMessage

public void addCassetteMessage(String message)
Cassettes call this method to add message text which will be returned through query API commands and displayed by the Commerce Payments user interface. Cassette messages allow cassettes to display dynamically-generated text at the user interface without having to manually build HTML pages.
Parameters:
message - a String containing the message text.
See Also:
XDMMessages

addFrameworkMessage

public void addFrameworkMessage(String message)
Cassettes should not call this method. The Framework calls this method to add message text which will be returned through query API commands and displayed by the Commerce Payments user interface.
Parameters:
message - a String containing the message text.

getInvalidList

public Hashtable getInvalidList()
Cassette should not call this method.