apollo.Storable
Class Storable

java.lang.Object
  |
  +--apollo.Storable.Storable
All Implemented Interfaces:
java.io.Serializable
Direct Known Subclasses:
JobRecord, TestUser

public abstract class Storable
extends java.lang.Object
implements java.io.Serializable

The superclass for Storable objects. Copyright Joe Kislo, All Rights Reserved.

See Also:
Serialized Form

Field Summary
static int AVERAGE
           
static int COUNT
           
static int CUSTOM
           
static java.lang.Boolean False
           
static java.lang.Object[][] fieldIndex
           
 java.lang.String[] fieldNames
           
 java.lang.String[] fieldPrimaryKey
           
 java.lang.Object[][] fieldType
           
static int MAX
           
static int MIN
           
static java.lang.Integer NON_UNIQUE
           
static int SUM
           
static java.lang.Boolean True
           
static java.lang.Integer UNIQUE
           
 
Constructor Summary
Storable(java.lang.Object[][] fieldType, java.lang.String[] fieldPrimaryKey)
          You must pass up to the constructor four fields.
 
Method Summary
static void addValueAtomic(ManagerTracker MT, java.lang.Class CLOperateTable, java.lang.String strOperateAttribute, int value, WhereStatement whereStatement)
           
static void begin(TransactionTracker TT, java.lang.Class theClass)
           
static void commit(TransactionTracker TT, java.lang.Class theClass)
           
 boolean equals(java.lang.Object o)
           
 java.lang.String[] getFieldNames()
          This will return the fieldNames array.
 java.lang.String[] getFieldPrimaryKey()
          This will return the primary key of the storable object.
abstract  java.lang.Object[] getFieldValues()
          This must return the data the object is having stored.
 int getIndexForField(java.lang.String theFieldName)
          Will return the index of theFieldName in fieldNames.
 java.lang.Object[] getPrimaryKeyValues()
          This method will retrieve the PrimaryKeyValues and return them in an array
 java.util.Vector getPrimaryKeyValuesVector()
          This method will retrieve the PrimaryKeyValues and return them in a vector (which can be stored and keyed off in a Hashtable, unlike an array)
 void insert(ManagerTracker MT)
          This will insert this record into the SQL table.
static java.lang.Object[] loadArrayInstance(ManagerTracker MT, java.lang.Class theClass, WhereStatement whereStatement)
           
static java.lang.Object[] loadArrayInstance(ManagerTracker MT, java.lang.Class theClass, WhereStatement whereStatement, java.lang.String[] includeFields)
          This loads an array of instances of the storable subclass matching the SQLWhereClause.
static java.lang.Object loadFunction(ManagerTracker MT, StorableFunction function, java.lang.Class[] CLGroupBy, java.lang.String[] attributeGroupBy, WhereStatement whereStatement)
           
static java.lang.Object loadFunction(ManagerTracker MT, StorableFunction function, WhereStatement whereStatement)
           
static java.lang.Object loadInstance(ManagerTracker MT, java.lang.Class theClass, java.lang.Object[] theLoadKey)
          This loads a single instance of the storable subclass using theLoadKey as the primary key.
static java.util.Vector loadVectorInstance(ManagerTracker MT, java.lang.Class theClass, WhereStatement whereStatement)
           
static java.util.Vector loadVectorInstance(ManagerTracker MT, java.lang.Class theClass, WhereStatement whereStatement, java.lang.String[] includeFields)
          This loads a vector (or a set) of objects out of the database as described by the WhereStatement.
 void remove(ManagerTracker MT)
          This will remove this record from the SQL table.
static void rollback(TransactionTracker TT, java.lang.Class theClass)
           
protected  void setAutoIncrement(long i)
           
 void setUpdatedField(java.lang.String theFieldName)
          When you update a field in a storable, you should tell the Storable superclass that you updated that field.
static java.lang.String SQLSanitize(ManagerTracker MT, java.lang.Class theClass, java.lang.String strToSanitize, boolean includeQuotes)
           
 void synchronize(ManagerTracker MT)
          Synchronize will confirm that this instance of the Storable object is the newest one by checking the internal version number.
static boolean tableCreated(ManagerTracker MT, java.lang.Class theClass)
           
 void testStorableConfiguration(java.lang.Object storableSubclass)
           
 java.lang.String toString()
          This will return a string representation of the Storable object
 void update(ManagerTracker MT)
          This will update the record in the SQL table.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

SUM

public static final int SUM

AVERAGE

public static final int AVERAGE

COUNT

public static final int COUNT

MAX

public static final int MAX

MIN

public static final int MIN

CUSTOM

public static final int CUSTOM

UNIQUE

public static final java.lang.Integer UNIQUE

NON_UNIQUE

public static final java.lang.Integer NON_UNIQUE

fieldIndex

public static final java.lang.Object[][] fieldIndex

True

public static final java.lang.Boolean True

False

public static final java.lang.Boolean False

fieldType

public final java.lang.Object[][] fieldType

fieldNames

public final java.lang.String[] fieldNames

fieldPrimaryKey

public final java.lang.String[] fieldPrimaryKey
Constructor Detail

Storable

public Storable(java.lang.Object[][] fieldType,
                java.lang.String[] fieldPrimaryKey)
You must pass up to the constructor four fields. fieldNames, fieldTypes, fieldCanBeNull and fieldPrimaryKey. These fields must be final and static in your Storable subclass. Read the detailed documentation under the respective method below for how these arrays must be declared.
Parameters:
fieldNames - Holds the SQL table column names.
fieldTypes - Holds the SQL table column types.
fieldClasses - Holds the Class objects corrisponding to each attribute
fieldCanBeNull - Holds boolean values weather the respective column can be null.
fieldPrimaryKey - Holds the SQL column names of the fields comprimsing the primary (and unique) key.
Method Detail

testStorableConfiguration

public void testStorableConfiguration(java.lang.Object storableSubclass)
                               throws MalformedStorable

getFieldNames

public java.lang.String[] getFieldNames()
This will return the fieldNames array. The fieldNames array MUST be declared static in the Storable subtype. EG:
static public String[] fieldNames = { "userID","password","age","sessionTimeout" }
The fieldNames array holds the SQL table column names. NOTE: All fieldNames, fieldTypes, fieldCanBeNull and fieldPrimaryKey, MUST be in the same order. Which means the KEY must be the first things in fieldNames.

getFieldPrimaryKey

public java.lang.String[] getFieldPrimaryKey()
This will return the primary key of the storable object. The fieldPrimaryKey array MUST be declared static in the Storable subtype. EG:
static public String[] fieldPrimaryKey = { "UserID" }
The fieldPrimaryKey holds the SQL column names of the fields comprimsing the primary (and unique) key. Since order is enforced, your primary key will always be the first field(s) in your fieldNames. NOTE: All fieldNames, fieldTypes, fieldCanBeNull and fieldPrimaryKey, MUST be in the same order. Which means the KEY must be the first things in fieldNames.

setUpdatedField

public void setUpdatedField(java.lang.String theFieldName)
                     throws MalformedStorable
When you update a field in a storable, you should tell the Storable superclass that you updated that field. It will store what fields you have modified in a bit vector. When it comes time for you to update() the storable into the database, it will only update the modified fields. You do not need to keep the superclass informed if you update fields if you do not want. If update() is called, and the bit vector says NOTHING has been updated in the storable, it will update ALL fields. So if you never tell the Storable superclass of your modifications, it will still work. However, there is a significant speed advantage if you DO tell the Storable superclass what fields you modify; since it will result in smaller SQL queries. If you only inform the storable superclass when *some* (and not *all*) fields get modified, you will have unreliable results. If the field you put in here does not exist, it will throw a MalformedStorable exception. Reminder: MalformedStorable exceptions extend RuntimeException. You must explicitly catch them. Otherwise your program will just halt.
Parameters:
theFieldName - The field you just modified

getIndexForField

public int getIndexForField(java.lang.String theFieldName)
                     throws MalformedStorable
Will return the index of theFieldName in fieldNames. If it does not exist a MalformedStorable exception will be thrown. Be careful!

getFieldValues

public abstract java.lang.Object[] getFieldValues()
This must return the data the object is having stored. This is returned in the form of an Objects array. You must turn your primitives into objects. They will be converted back. NOTE: This must return in the order of fieldNames, fieldTypes, fieldCanBeNull and fieldPrimaryKey.

getPrimaryKeyValues

public java.lang.Object[] getPrimaryKeyValues()
This method will retrieve the PrimaryKeyValues and return them in an array

getPrimaryKeyValuesVector

public java.util.Vector getPrimaryKeyValuesVector()
This method will retrieve the PrimaryKeyValues and return them in a vector (which can be stored and keyed off in a Hashtable, unlike an array)

loadInstance

public static java.lang.Object loadInstance(ManagerTracker MT,
                                            java.lang.Class theClass,
                                            java.lang.Object[] theLoadKey)
                                     throws MalformedStorable
This loads a single instance of the storable subclass using theLoadKey as the primary key. If you call Storable.loadInstance, you will need to pass in the Class object (IE User.class will get you the Class object for User), and loadInstance will return your Storable subclass in Object form. So lets say you are looking up a User record: User thisUser = (User) Storable.loadInstance(User.class, new Object[] = {"joe"}); However, the prefered way of doing this is using User's static loadInstance method, since it will pass in the class name, and cast for you. However you need to have put/updated your static loadInstance method in your storable subclass. If you did this properly, this will work: User thisUser = User.loadInstance(new Object[] = {"joe"});
Parameters:
theClassName - The Storable subtype Class object
theLoadKey - The Key to use for load (primary key only)

loadArrayInstance

public static java.lang.Object[] loadArrayInstance(ManagerTracker MT,
                                                   java.lang.Class theClass,
                                                   WhereStatement whereStatement,
                                                   java.lang.String[] includeFields)
This loads an array of instances of the storable subclass matching the SQLWhereClause. Primarily the same as loadVectorInstance, except in array is returned. User[] teenagers = (User[]) Storable.loadArrayInstance(User.class, wq); However, the prefered way of doing this is using User's static loadArrayInstance method, since it will pass in the class name, and cast for you. However you need to have put/updated your static loadArrayInstance method in your storable subclass. If you did this properly, this will work: User[] teenagers = User.loadArrayInstance(wq);
Parameters:
theClassName - The Storable subtype Class object
whereStatement - The WhereQuery describing the rows to return
includeFields - If this variable is supplied only the fields in this array will be retrieved and sent to the object constructor

loadArrayInstance

public static java.lang.Object[] loadArrayInstance(ManagerTracker MT,
                                                   java.lang.Class theClass,
                                                   WhereStatement whereStatement)

begin

public static void begin(TransactionTracker TT,
                         java.lang.Class theClass)

commit

public static void commit(TransactionTracker TT,
                          java.lang.Class theClass)

rollback

public static void rollback(TransactionTracker TT,
                            java.lang.Class theClass)

setAutoIncrement

protected void setAutoIncrement(long i)

SQLSanitize

public static java.lang.String SQLSanitize(ManagerTracker MT,
                                           java.lang.Class theClass,
                                           java.lang.String strToSanitize,
                                           boolean includeQuotes)

loadFunction

public static java.lang.Object loadFunction(ManagerTracker MT,
                                            StorableFunction function,
                                            WhereStatement whereStatement)

loadFunction

public static java.lang.Object loadFunction(ManagerTracker MT,
                                            StorableFunction function,
                                            java.lang.Class[] CLGroupBy,
                                            java.lang.String[] attributeGroupBy,
                                            WhereStatement whereStatement)

addValueAtomic

public static void addValueAtomic(ManagerTracker MT,
                                  java.lang.Class CLOperateTable,
                                  java.lang.String strOperateAttribute,
                                  int value,
                                  WhereStatement whereStatement)

loadVectorInstance

public static java.util.Vector loadVectorInstance(ManagerTracker MT,
                                                  java.lang.Class theClass,
                                                  WhereStatement whereStatement)

loadVectorInstance

public static java.util.Vector loadVectorInstance(ManagerTracker MT,
                                                  java.lang.Class theClass,
                                                  WhereStatement whereStatement,
                                                  java.lang.String[] includeFields)
This loads a vector (or a set) of objects out of the database as described by the WhereStatement.
Parameters:
MT - The ManagerTracker
theClass - The storable class to load
whereStatement - The wherequery describing the objects to load
includeFields - If this variable is supplied only the fields in this array will be retrieved and sent to the object constructor

tableCreated

public static boolean tableCreated(ManagerTracker MT,
                                   java.lang.Class theClass)

toString

public java.lang.String toString()
This will return a string representation of the Storable object
Overrides:
toString in class java.lang.Object

insert

public void insert(ManagerTracker MT)
This will insert this record into the SQL table. If the SQL table does not already exist, it will be created from the specifications given in the Storable subclass. If the record already exists, it will throw a DuplicateKeyException with a report. If it is unable to make heads or tails of your storable subclass, it will throw a MalformedStorable. In which case you should probably run testStorableConfiguration() and see what's wrong.

remove

public void remove(ManagerTracker MT)
This will remove this record from the SQL table.

update

public void update(ManagerTracker MT)
This will update the record in the SQL table. If the record does not exist already, it will throw an SQLException. Update will only update the fields you have modified, assuming you register your updates with the setUpdatedField() method. If you have not, and it detects no updates, it will update every field in the record.

equals

public boolean equals(java.lang.Object o)
Overrides:
equals in class java.lang.Object

synchronize

public void synchronize(ManagerTracker MT)
Synchronize will confirm that this instance of the Storable object is the newest one by checking the internal version number. If it is not, it will reprogram (using the setFieldValues) the new values into this existing instance. To call this method, your Storable class must implement Synchronizable