org.gjt.tw.dbobjects
Class StorableObject

java.lang.Object
  |
  +--org.gjt.tw.dbobjects.StorableObject
Direct Known Subclasses:
Address, Address, Customer, Customer, CustomerAddress, CustomerAddress

public abstract class StorableObject
extends java.lang.Object

Every class that you want to store in the database using the mechanism provided by this package has to extend this abstract class.

Unfortunately, it is possible to extend the class and forget to implement important methods. This means that although everything compiles it might not work.

This is a list of what you have to do when extending this class:

First, the constructor of your class needs to call the super constructor. Upon creation of the object, the data is not stored in the database. You have to do this by calling the store()-method explicitly. Before store() is called all objects used by your class have to be instanciated. Otherwise you will get a NullPointerException while storing. If you add a call to store() to the constructor, store() is called each time an object is retrieved from the database. In most cases this is undisirable.

Second, you have to provide a get and a set method for each field in the class that you want to store. Example:

   private String name;

   public String getName() {
     return name;
   }

   public void setName (String name) {
     this.name = name;
   }
 

Third, you have to implement the method getMapping (). This method always looke the same:

   protected ObjectMapping getMapping() {
     if (mapping == null)
       mapping = new ObjectMapping ();
     return mapping;
   }
 
This method uses an object called mapping. This has to be declared by your class:
   private static ObjectMapping mapping;
 

Fourth, you have to provide an init () method that initializes the object mapping. This method will look like this:

   public static void init () throws ObjectException, IncompleteDefinitionException {
     mapping = new ObjectMapping ();
     mapping.setTableName ("customer");
     mapping.setObjectClass (Customer.class);
     mapping.addField ("id", Long.TYPE, "id");
     mapping.addField ("name", String.class, "customer_name");
     mapping.setKeyField ("id");
     mapping.setAutoIncrement (ObjectMapping.AUTOINCREMENT_SEQUENCER);
     mapping.prepareSQLStatements ();
   }
 

Fifth, you might want to implement static methods that allow to retrieve stored objects. Such a method looks like this:

   public static Customer getByName (String name) throws DatabaseException, ObjectException {
     StorableObject[] objects = DBManager.getByField (mapping, "name", name);
       if (objects == null)
         return null;
       else
         return (Customer) objects[0];
   }
 

For more in depth information please have a look at the examples provided inside the test package. There you will find working examples how to use this package. The best way to create your own new classes is to copy the existing code, get rid of all fields you don't need and extend it by your own code.


Field Summary
 boolean isStoredInDatabase
          Description of the Field
 
Constructor Summary
StorableObject()
          Default Constructor.
 
Method Summary
 void delete()
          This method deletes the databse entry of the object.
 void getDomTree()
          Returns an XML element that forms a DOM tree representing the data of this object.
protected abstract  ObjectMapping getMapping()
          This method returns the object mapping of the current object.
static void init()
          This method initializes the class.
 void print()
          Prints the values of all mapped fields of the current object to the console.
 void store()
          This method stores the object into the database.
 java.lang.String toXML()
          Returns a string containing the XML representation of the values of the fields stored in the current object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

isStoredInDatabase

public boolean isStoredInDatabase
Description of the Field
Constructor Detail

StorableObject

public StorableObject()
Default Constructor. Sets all values to defaults.
Method Detail

getDomTree

public void getDomTree()
Returns an XML element that forms a DOM tree representing the data of this object. Only those fields are inserted into the DOM tree that were initialized in the init method.

delete

public void delete()
            throws DatabaseException,
                   ObjectException
This method deletes the databse entry of the object. No values of the java object are changed, but the database entry does not exist any more. It is possible to store the object again.
Throws:
DatabaseException - Description of Exception
ObjectException - Description of Exception

print

public void print()
Prints the values of all mapped fields of the current object to the console.

store

public void store()
           throws DatabaseException,
                  ObjectException
This method stores the object into the database. From the view of the application there is no difference whether the object has to be inserted or updated.
Throws:
DatabaseException - Description of Exception
ObjectException - Description of Exception

toXML

public java.lang.String toXML()
Returns a string containing the XML representation of the values of the fields stored in the current object.
Returns:
java.lang.String

getMapping

protected abstract ObjectMapping getMapping()
This method returns the object mapping of the current object. This method is only used internally. But because of implementation issues each class extending StorableObject has to implement this method. The code for this method always looks like this:
   protected ObjectMapping getMapping() {
     if (mapping == null)
       mapping = new ObjectMapping ();
     return mapping;
   }
 
Returns:
databasemanagement.ObjectMapping

init

public static void init()
                 throws ObjectException,
                        IncompleteDefinitionException
This method initializes the class. Each class that extends StorableObject has to implement this class! Upon initialization of your application, the init() method of each of your classes has to be called once.
Throws:
ObjectException - Description of Exception
IncompleteDefinitionException - Description of Exception