av.tob
Class TheObjectBase<Q extends TheObjectBase.Querier>

java.lang.Object
  av.tob.TheObjectBase<Q>

Type Parameters:

Q - Type of the supported querier. Note TOB itself doesn't supply query abilities, instead the swap engine are required to declare its own querier interface for programmers. Application programmers normally specify the intended querier (i.e. SQLQuerier by RDBMS family engines) when constructing and using a TOB instance.

public final class TheObjectBase<Q extends TheObjectBase.Querier>
extends Object

The Object Base is a RAM targeted, state-of-the-art Object Oriented Database system in java.

TOB builds upon most advanced semantics from the version 5 of Java Programming Language, reflects cutting-edge methodologies of Object Oriented Design & Development, greatly reduced the complexity for OO persistent programming and code maintenance. At the same time, TOB terrifyingly boosts the performance that traversing persistent object network interconnected through persistent relations. TOB offers revolutionary performance at no cost of lossing accuracy or serializability, in contrast to those cache accelarated O-R Mapping solutions.

Visit http://tob.ableverse.org for more information.

Author:

Compl

See Also:

SQLQuerier

Nested Class Summary

static class

TheObjectBase.Querier This is the base class for all querier interfaces defined by various SwapEngines.

Field Summary

static long	NULL_ID NULL id reserved by TOB, value is: 0L
Q	q The querier of this TOB.
Q	querier The querier of this TOB.
static String	VERSION

Method Summary

<T extends TheObject> T	birth(T obj) Give birth to a fetus object and return a born object from it.
void	commitAllTransactions() Commit all transactions of current thread.
void	commitCurrentTransaction() Commit current transaction.
static <Q extends TheObjectBase.Querier> TheObjectBase<Q>	create(Class<Q> querierClass) Create a TOB with the first available engine listed inside the querierClass' meta at supporting-engines/engine.
static <Q extends TheObjectBase.Querier> TheObjectBase<Q>	create(MetaBundle meta) The meta passed here must have valid TOB configuration, including nested swap engine configuration defined.
TheObject	get(long id) Get the persistent object identified by id.
<T extends TheObject> T	get(long id, Class<T> expectedClass) Get the persistent object identified by id.
av.tob.Transaction	getCurrentTransaction() Get the current Transaction bound to current Thread.
<T extends TheObject> PersistentClass<T>	getPersistentClass(Class<T> javaClass) Get the persistent class definition corrsponding to an application defined java persistent class.
String	getVersion()
void	process(long id, ObjectProcessor<?> processor) Process a persistent object via the ObjectProcessor interface.
void	rollbackAllTransactions() Rollback all transactions of current thread.
void	rollbackCurrentTransaction() Rollback current transaction;
void	shutdown() Shutdown this TOB.
av.tob.Transaction	startNewTransaction() Start a new nested transaction, make it the current transaction and return it.

Methods inherited from class java.lang.Object

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

Field Detail

VERSION

public static final String VERSION

See Also:

Constant Field Values

NULL_ID

public static final long NULL_ID

NULL id reserved by TOB, value is: 0L

See Also:

Constant Field Values

querier

public final Q extends TheObjectBase.Querier querier

The querier of this TOB.

q

public final Q extends TheObjectBase.Querier q

The querier of this TOB.

Method Detail

getVersion

public String getVersion()

create

public static <Q extends TheObjectBase.Querier> TheObjectBase<Q> create(MetaBundle meta)
                                                             throws ObjectBaseCreationException

The meta passed here must have valid TOB configuration, including nested swap engine configuration defined.

Type Parameters:

Q - querier type

Parameters:

meta - a meta bundle with sufficient information to create a TOB

Returns:

a new TOB initialized by the configuration info from meta

Throws:

ObjectBaseCreationException - if error occurs

create

public static <Q extends TheObjectBase.Querier> TheObjectBase<Q> create(Class<Q> querierClass)
                                                             throws ObjectBaseCreationException

Create a TOB with the first available engine listed inside the querierClass' meta at supporting-engines/engine.

Type Parameters:

Q - type of the querier class

Parameters:

querierClass - the querier class

Returns:

the created new TOB

Throws:

ObjectBaseCreationException - if error occurs

shutdown

public void shutdown()

Shutdown this TOB.

getPersistentClass

public <T extends TheObject> PersistentClass<T> getPersistentClass(Class<T> javaClass)

Get the persistent class definition corrsponding to an application defined java persistent class.

Type Parameters:

T - type of the persistent class

Parameters:

javaClass - the application defined persistent class instance

Returns:

the persistent class corrsponding to the application define java persistent class

getCurrentTransaction

public av.tob.Transaction getCurrentTransaction()

Get the current Transaction bound to current Thread.

Returns:

current tx

startNewTransaction

public av.tob.Transaction startNewTransaction()

Start a new nested transaction, make it the current transaction and return it.

commitCurrentTransaction

public void commitCurrentTransaction()
                              throws ConsistenceException,
                                     CommitFailedException

Commit current transaction.

If failed, current transaction will rolled back before throwing an exceptiion.

All locks will be released whether successed or not.

Throws:

ConsistenceException - if consistency violated

CommitFailedException - if system errors occured

rollbackCurrentTransaction

public void rollbackCurrentTransaction()

Rollback current transaction;

commitAllTransactions

public void commitAllTransactions()
                           throws ConsistenceException,
                                  CommitFailedException

Commit all transactions of current thread.

If any failed, all uncommited transactions will rolled back before throwing an exceptiion.

All locks will be released whether successed or not.

Throws:

ConsistenceException - if consistency violated

CommitFailedException - if system errors occured

rollbackAllTransactions

public void rollbackAllTransactions()

Rollback all transactions of current thread.

birth

public <T extends TheObject> T birth(T obj)
                          throws av.tob.FetalDeathException

Give birth to a fetus object and return a born object from it.

Type Parameters:

T - type of the object to birth

Parameters:

obj - the fetus object to birth

Returns:

the born object

Throws:

av.tob.FetalDeathException - if error occurs

get

public <T extends TheObject> T get(long id,
                                   Class<T> expectedClass)
                        throws InterruptedException

Get the persistent object identified by id. null will be returned if id identifies no object, or the object identified by id is not assignable to expectedClass.

If expectedClass is null, null null will be returned immediately, regardless of id.

TOB guarantees to set the persistent object to Online state before returning it to the the caller.

TOB also guarantees that another java object instance with different identityHashCode will never be returned for a particular id value, as long as any previous caller still holds a previously returned instance for the same id.

That is, given an application thread t1 had got one persistent object with id, namely o1, given o1 was not deleted and t1 kept its reference to o1, subsequent calls to this method with the same id, by t1 or any other thread, namely t2, would got the object o2, that TOB guarantees the comparation o1 == o2 will always be true.

Parameters:

id - the object identifier

expectedClass - the expected class

Returns:

the persistent object identified by id, assignable to expectedClass, or null otherwise

Throws:

InterruptedException - if the calling thread is interrupted

get

public TheObject get(long id)
              throws InterruptedException

Get the persistent object identified by id. null will be returned if id identifies no object.

TOB guarantees to set the persistent object to Online state before returning it to the the caller.

TOB also guarantees that another java object instance with different identityHashCode will never be returned for a particular id value, as long as any previous caller still holds a previously returned instance for the same id.

That is, given an application thread t1 had got one persistent object with id, namely o1, given o1 was not deleted and t1 kept its reference to o1, subsequent calls to this method with the same id, by t1 or any other thread, namely t2, would got the object o2, that TOB guarantees the comparation o1 == o2 will always be true.

Note that applications are not encouraged to use this method followed by an explicit type cast, such like Employee e = (Employee) tob.get(123);. Since ClassCastException tends to occur and it'll be easy for attackers to issue fake id polling that intends for such exceptions. get(long, Class) is recommended for such scenarios. For example: Employee e = tob.get(123, Employee.class); is recommended.

Parameters:

id - the object identifier

Returns:

the persistent object identified by id

Throws:

InterruptedException - if the calling thread is interrupted

process

public void process(long id,
                    ObjectProcessor<?> processor)
             throws Exception

Process a persistent object via the ObjectProcessor interface. When the processor is invoked, the ordinal parameter to ObjectProcessor.processTheObject(long, TheObject) will be 0.

If the object with the specified id exists and has been loaded, the processor will be called immediately.

In case of the object exists but not yet loaded, the processor is possibly to be called in another thread right after it loaded the object.

In case of object with the specified id does not exist, or not assignable to the declared type of the processor, the processor will be invoked with null, in the calling thread or another thread which found out this.

Note if the object has not yet been loaded, the processor won't be called until a load requirement is fired in the future, as this method doesn't fire such a requirement, invoke get(long) subsequently to ensure a soon invocation on the processor if needed.

Parameters:

id - id of the persistent object

processor - which to process the persistent object

Throws:

NullPointerException - if processor is null

Exception