org.starhope.appius.util
Class BaseDatum

java.lang.Object
  org.starhope.appius.util.ManagedReferenceHolder
      org.starhope.appius.util.BaseDatum

All Implemented Interfaces:

com.sun.sgs.app.ManagedObject, Externalizable, Serializable, CastsToJSON

Direct Known Subclasses:

AvatarBase, Domain, Enrolment, Event, EventType, ItemTemplate, ItemType, Message, PaymentGateway, Provision, Server, ShippingOrder, Store, StoreCategory, UserAddress, WatchWord, Zone

public class BaseDatum
extends ManagedReferenceHolder
implements CastsToJSON, Externalizable, com.sun.sgs.app.ManagedObject

Another way to register a Managed Object to the Data Manager is with the setBinding call. This call does not return a Managed Reference, but instead binds the Managed Object to the string passed in with it to the call. Once a Managed Object has a name bound to it, the Managed Object may be retrieved by passing the same name to the getBinding call. Note that name bindings must be distinct. For each unique string used as a name binding by an application, there can be one and only one Managed Object bound.

Author:

brpocock

See Also:

Serialized Form

Field Summary

private static com.sun.sgs.app.ManagedReference<com.sun.sgs.app.util.ScalableHashMap<Class<? extends BaseDatum>,com.sun.sgs.app.ManagedReference<? extends BaseDatum>>>	classCache This is the cache of all objects of a given class, used by some stuff to make some other stuff happy.
protected String	database_id This is either the database ID value of this object in the database; or, if it's less than zero, it's a flag that means that the contents of the object have not been instantiated from the database and have not been flushed to the database.
private static long	serialVersionUID

Constructor Summary

BaseDatum()
Instantiate a "null object," with no data.

Method Summary

void	changed() This method should be called from all setters who wish to force an immediate (attempt at) flush of the contents to the database.
protected void	commitToDatabase() This method performs the actual flush of data to the database.
void	delete() Remove an object from the pool
boolean	equals(BaseDatum other) Compare two BaseDatum-derived objects
void	flush() Saves the object's state to the database, using either INSERT or UPDATE as appropriate.
protected static BaseDatum	get(Class<? extends BaseDatum> klass, org.json.JSONObject object) Instantiate a BaseDatum-derived object based upon JSON data
protected static BaseDatum	get(Class<? extends BaseDatum> klass, String id) Loads a database record into this object.
String	getID() Get the database ID value for this object.
protected String[]	getUniqueBoundName()
void	readExternal(ObjectInput in)
org.json.JSONObject	refJSON(com.sun.sgs.app.ManagedReference<? extends BaseDatum> reference)
void	set(org.json.JSONObject o) This method will attempt to set the data contents of this object to the values derived from the JSON object being passed-in.
protected void	setID(String id)
static String	sqlDateTime(Date dateTime)
org.json.JSONObject	toJSON() This returns a copy of the object's data cast into a JSON form.
void	writeExternal(ObjectOutput out)

Methods inherited from class org.starhope.appius.util.ManagedReferenceHolder

deref, setRef

Methods inherited from class java.lang.Object

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

Field Detail

classCache

private static com.sun.sgs.app.ManagedReference<com.sun.sgs.app.util.ScalableHashMap<Class<? extends BaseDatum>,com.sun.sgs.app.ManagedReference<? extends BaseDatum>>> classCache

This is the cache of all objects of a given class, used by some stuff to make some other stuff happy.

serialVersionUID

private static final long serialVersionUID

See Also:

Constant Field Values

database_id

protected String database_id

This is either the database ID value of this object in the database; or, if it's less than zero, it's a flag that means that the contents of the object have not been instantiated from the database and have not been flushed to the database.

Constructor Detail

BaseDatum

public BaseDatum()

Instantiate a "null object," with no data. This object is not backed by the database until it has been (successfully) saved, which presumably means that all of its fields are set first to valid values.

Method Detail

sqlDateTime

public static String sqlDateTime(Date dateTime)

Parameters:

dateTime - The java.util.Date to be formatted

Returns:

An SQL string describing the date & time *in UTC*

get

protected static BaseDatum get(Class<? extends BaseDatum> klass,
                               org.json.JSONObject object)
                        throws RuntimeException,
                               NotFoundException,
                               org.json.JSONException

Instantiate a BaseDatum-derived object based upon JSON data

Parameters:

klass - the subclass to which the resultant object is believed to belong

object - the JSON object describing the desired object

Returns:

the object being instantiated

Throws:

NotFoundException - if the object has an ID value, and is not found in the database with that ID

RuntimeException - if there's a severe problem, such as bad JSON data or numbers out of range

org.json.JSONException - if the JSON data is badly-formed

get

protected static BaseDatum get(Class<? extends BaseDatum> klass,
                               String id)
                        throws RuntimeException,
                               NotFoundException

Loads a database record into this object.

Instantiate a certain item by looking it up in the database based upon the ID column in the database table.

This method attempts to either find a copy of the given object ID in core, or (if one is not found), create a new one and load its contents from the database.

Parameters:

klass - The subclass of BaseDatum to which the resultant object belongs

id - The ID number. Note that, while we use a Java "long" type to hold this, the actual valid range is that of an INT UNSIGNED, that is, from 0 to 2**32 - 1. Since Java doesn't have unsigned types, we have to use a long to contain all possible values.

Returns:

the object instantiated

Throws:

RuntimeException - if something really nasty were to happen

NotFoundException - if the given value doesn't return a result set (i.e. if the ID supplied is not found in the database)

changed

public void changed()

This method should be called from all setters who wish to force an immediate (attempt at) flush of the contents to the database. Rapidly-changing values that might not need to be saved can simply set this.changed () instead.

delete

public void delete()

Remove an object from the pool

equals

public boolean equals(BaseDatum other)

Compare two BaseDatum-derived objects

Parameters:

other - The other object

Returns:

true if they represent the same object

flush

public void flush()

Saves the object's state to the database, using either INSERT or UPDATE as appropriate. The database will not be changed if the object's this.changed flag is "false."

This method does not propagate exceptions due to bad data. If you want to catch them, yourself, call the underlying commitToDatabase method, instead.

To simply confirm whether the database was updated, without concerning yourself with the details, you can also just check the changed flag, which will be cleared upon success.

getID

public String getID()

Get the database ID value for this object. Note that calling this method could cause an implicit flush() to the database; this is so that newly-instantiated objects can get their AUTO_INCREMENT database ID value assigned by being INSERT:ed for the first time. If that fails, this will throw up a DataException, on the assumption that there's some problem with internal data consistency causing this problem.

Returns:

the INT UNSIGNED database ID (if any), expressed as a Java long integer (since INT UNSIGNED is a 32-bit value and Java integers are 31-bit signed values)

readExternal

public void readExternal(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException

Specified by:

readExternal in interface Externalizable

Throws:

IOException

ClassNotFoundException

See Also:

Externalizable.readExternal(java.io.ObjectInput)

refJSON

public org.json.JSONObject refJSON(com.sun.sgs.app.ManagedReference<? extends BaseDatum> reference)

Parameters:

reference - a ManagedReference to a BaseDatum-derived class

Returns:

a JSON-compatible URL-type pointer

set

public void set(org.json.JSONObject o)

Description copied from interface: CastsToJSON

This method will attempt to set the data contents of this object to the values derived from the JSON object being passed-in. All exceptions are ignored, but any errors in the JSON data could cause the command to fail, completely or partially.

Specified by:

set in interface CastsToJSON

Parameters:

o - The JSON object containing a the new data for this object.

See Also:

CastsToJSON.set(org.json.JSONObject)

toJSON

public org.json.JSONObject toJSON()

Description copied from interface: CastsToJSON

This returns a copy of the object's data cast into a JSON form.

Specified by:

toJSON in interface CastsToJSON

Returns:

The string representing this object in JSON format

See Also:

CastsToJSON.toJSON()

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException

Specified by:

writeExternal in interface Externalizable

Throws:

IOException

See Also:

Externalizable.writeExternal(java.io.ObjectOutput)

commitToDatabase

protected void commitToDatabase()

This method performs the actual flush of data to the database. It ignores the state of the changed flag, and propagates exceptions to the caller.

Generally, users will call "flush," but this method is available to child classes for their use.

Note that what we actually do here, in our post-SQL Darkstar existence, is bind the data object to the names returned by getUniqueBoundName().

getUniqueBoundName

protected String[] getUniqueBoundName()

Returns:

A string array of names which uniquely identify this data object. There may be only one name, if that is appropriate for this class (as it usually is)

setID

protected void setID(String id)

Parameters:

id - the database ID for this object