av.tob.rdb
Class SQLQuerier

java.lang.Object
  av.tob.TheObjectBase.Querier
      av.tob.rdb.SQLQuerier

public abstract class SQLQuerier
extends TheObjectBase.Querier

The standard TheObjectBase.Querier interface by SwapEngines run atop traditional relational databases.

Author:

Compl

Field Summary

Fields inherited from class av.tob.TheObjectBase.Querier

tob

Constructor Summary

protected

SQLQuerier(TheObjectBase<? extends SQLQuerier> tob) Construct an instance.

Method Summary

abstract <T extends TheObject> long	count(Class<T> klass, String clause, Object... args) Count on class klass and all its direct and indirect subclasses for persistent objects matching criteria specified by clause.
abstract <T extends TheObject> void	exterminate(Class<T> klass) Kill all persistent objects of class klass and any of its direct or indirect subclasses.
abstract <T extends TheObject> List<T>	query(long start, long max, Class<T> klass, String clause, Object... args) Query on class klass and all its direct and indirect subclasses for persistent objects matching criteria specified by clause.
abstract SQLResultList	query(long start, long max, String customSQL) This method allows direct views at records in the underlying database schema by custom sql statements.
abstract <T extends TheObject> void	query(ObjectProcessor<? super T> processor, long max, Class<T> klass, String clause, Object... args) Query on class klass and all its direct and indirect subclasses for persistent objects matching criteria specified by clause.
abstract void	query(SQLResultProcessor processor, long max, String customSQL) This method allows direct views at records in the underlying database schema by custom sql statements.
abstract void	update(String customSQL) This method allows direct modifications to records in the underlying database schema by custom sql statements.

Methods inherited from class av.tob.TheObjectBase.Querier

exterminated

Methods inherited from class java.lang.Object

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

Constructor Detail

SQLQuerier

protected SQLQuerier(TheObjectBase<? extends SQLQuerier> tob)

Construct an instance.

Parameters:

tob -

Method Detail

query

public abstract <T extends TheObject> List<T> query(long start,
                                                    long max,
                                                    Class<T> klass,
                                                    String clause,
                                                    Object... args)

Query on class klass and all its direct and indirect subclasses for persistent objects matching criteria specified by clause. The result will be stored into a list and returned to the caller.

clause is typically constructed by concatenate QueryField with strings containing operators ( = > < and or ) and any valid expressions for sql statements ( order by asc desc group by, etc. ). When you are not sure how to specify a value in a string version of sql, use syntax defined for Connection.prepareStatement(java.lang.String) for the clause and specify same number of arguments args as the question marks appeared in clause. Then the jdbc driver will properly set them for you.

You do not create QueryField by yourself, instead, just use those generaged by TOB with EngineRDB during annotation processing. That should be an interface class residents in the same package of your persisent class and which take the name with a Q appended to your class'. For example, if you pass a klass parameter as com.data.Person.class here, then TOB should already generated a class com.data.PersonQ if build successed. There will be public static QueryField constants defined for each persistent field of class com.data.Person, may be FIRSTNAME AGE or some thing like. For persistent relations, there will also be such constants defined to reference persistent fields in tied persistent classes. If specified klass is a persistent relation, then one level of the tied persistent class is automatically joined if your clause contains references to them. More deeper level of joins and custom joins are not supported by SQLQuerier, as for TOB always maintain the connection network for online persistent objects, you want to traverse the structure and choose candidates instead of issuing those slow queries for performance consideration.

To reference database columns in construction of the clause parameter, ALWAYS and ONLY use QueryField constants from the generated interface for the class you passed here, or the query may fail or get incorrect result.

Note: As queries don't impose locks preventing concurrent modifications to the objects in result, later read data of the objects may has changed that no more matching the criteria specified by clause at the query time. If the read data makes sense, you should obtain it via methods annotated with @Reading / @Writing / @Retying and double check it fulfill your criteria.

Type Parameters:

T - target base persistent class of the query

Parameters:

start - list result objects from this index on, the first object has index 1

max - maximum number of objects to retrieve

klass - the query base class

clause - the query criteria

args - the query arguments

Returns:

a list of persistent objects match the query clause

query

public abstract <T extends TheObject> void query(ObjectProcessor<? super T> processor,
                                                 long max,
                                                 Class<T> klass,
                                                 String clause,
                                                 Object... args)
                    throws Exception

Query on class klass and all its direct and indirect subclasses for persistent objects matching criteria specified by clause. The result will be passed to the processor specified here.

clause is typically constructed by concatenate QueryField with strings containing operators ( = > < and or ) and any valid expressions for sql statements ( order by asc desc group by ). When you are not sure how to specify a value in a string version of sql, use syntax defined for Connection.prepareStatement(java.lang.String) for the clause and specify same number of arguments args as the question marks appeared in clause. Then the jdbc driver will properly set them for you.

You do not create QueryField by yourself, instead, just use those generaged by TOB with EngineRDB during annotation processing. That should be an interface class residents in the same package of your persisent class and which take the name with a Q appended to your class'. For example, if you pass a klass parameter as com.data.Person.class here, then TOB should already generated a class com.data.PersonQ if build successed. There will be public static QueryField constants defined for each persistent field of class com.data.Person, may be FIRSTNAME AGE or some thing like. For persistent relations, there will also be such constants defined to reference persistent fields in tied persistent classes. If specified klass is a persistent relation, then one level of the tied persistent class is automatically joined if your clause contains references to them. More deeper level of joins and custom joins are not supported by SQLQuerier, as for TOB always maintain the connection network for online persistent objects, you want to traverse the structure and choose candidates instead of issuing those slow queries for performance consideration.

To reference database columns in construction of the clause parameter, ALWAYS and ONLY use QueryField constants from the generated interface for the class you passed here, or the query may fail or get incorrect result.

Note: As queries don't impose locks preventing concurrent modifications to the objects in result, later read data of the objects may has changed that no more matching the criteria specified by clause at the query time. If the read data makes sense, you should obtain it via methods annotated with @Reading / @Writing / @Retying and double check it fulfill your criteria.

Type Parameters:

T - target base persistent class of the query

Parameters:

processor - which to receive the query results

max - maximum number of objects to retrieve

klass - the query base class

clause - the query criteria

args - the query arguments

Throws:

Exception - whatever the processor throws

count

public abstract <T extends TheObject> long count(Class<T> klass,
                                                 String clause,
                                                 Object... args)

Count on class klass and all its direct and indirect subclasses for persistent objects matching criteria specified by clause.

clause is typically constructed by concatenate QueryField with strings containing operators ( = > < and or ) and any valid expressions for sql statements. When you are not sure how to specify a value in a string version of sql, use syntax defined for Connection.prepareStatement(java.lang.String) for the clause and specify same number of arguments args as the question marks appeared in clause. Then the jdbc driver will properly set them for you.

You do not create QueryField by yourself, instead, just use those generaged by TOB with EngineRDB during annotation processing. That should be an interface class residents in the same package of your persisent class and which take the name with a Q appended to your class'. For example, if you pass a klass parameter as com.data.Person.class here, then TOB should already generated a class com.data.PersonQ if build successed. There will be public static QueryField constants defined for each persistent field of class com.data.Person, may be FIRSTNAME AGE or some thing like. For persistent relations, there will also be such constants defined to reference persistent fields in tied persistent classes. If specified klass is a persistent relation, then one level of the tied persistent class is automatically joined if your clause contains references to them. More deeper level of joins and custom joins are not supported by SQLQuerier, as for TOB always maintain the connection network for online persistent objects, you want to traverse the structure and choose candidates instead of issuing those slow queries for performance consideration.

To reference database columns in construction of the clause parameter, ALWAYS and ONLY use QueryField constants from the generated interface for the class you passed here, or the query may fail or get incorrect result.

Note: As queries don't impose locks preventing concurrent modifications to the objects queried, the count result may vary soon after this method has returned.

Type Parameters:

T - target base persistent class of the query

Parameters:

klass - the query base class

clause - the query criteria

args - the query arguments

Returns:

how many persistent objects match the query clause

exterminate

public abstract <T extends TheObject> void exterminate(Class<T> klass)

Kill all persistent objects of class klass and any of its direct or indirect subclasses.

Warning: Use this method at your own risk, for it will bypass the deletion validation normally implemented by persistent classes. And inter connections amount persistent objects will not be properly cleared by this method. Don't use it unless you know exactly what you are doing and you get pretty sure all objects that might connects to any exterminated object also get exterminated. You are setting future sufferings for yourself if you cut the grass but don't get rid of its root - A very old and traditional Chinese saying.

Type Parameters:

T - type of the base class to exterminate

Parameters:

klass - base persistent class to exterminate

query

public abstract SQLResultList query(long start,
                                    long max,
                                    String customSQL)
                             throws SQLException

This method allows direct views at records in the underlying database schema by custom sql statements.

This method is provided mainly for statistic functionality, as object based access is greatly accelarated by TOB, statistic based queries are not. Statistics is an important thing that relational database do the best.

it may provide some convenience that create extra, non-conflict tables in the same schema of TOB backen and manipulate them in TOB applications. This method is provided mainly for this purpose.

Parameters:

start - list result objects from this index on, the first object has index 1

max - maximum number of objects to retrieve

customSQL - custom SQL statement

Returns:

a list containing results queried out from the backend database

Throws:

SQLException

query

public abstract void query(SQLResultProcessor processor,
                           long max,
                           String customSQL)
                    throws SQLException

This method allows direct views at records in the underlying database schema by custom sql statements.

Warning: Normally you should not use data in the backend database directly, by other clients connected to it or by invoking this method. However, it may provide some convenience that create extra, non-conflict tables in the same schema of TOB backen and manipulate them in TOB applications. This method is provided mainly for this purpose.

Parameters:

processor - which to process the query results

max - maximum number of records to process

customSQL - custom SQL statement

Throws:

SQLException

update

public abstract void update(String customSQL)
                     throws SQLException

This method allows direct modifications to records in the underlying database schema by custom sql statements.

Warning: Normally you should not use data in the backend database directly, by other clients connected to it or by invoking this method. However, it may provide some convenience that create extra, non-conflict tables in the same schema of TOB backen and manipulate them in TOB applications. This method is provided mainly for this purpose.

Direct writings to tables used by TOB are forbidden unless explicitly permited.

Parameters:

customSQL - custom SQL statement

Throws:

SQLException