| java.lang.Object
 org.garret.perst.continuous.CDatabase
| CDatabase | | public class CDatabase (Code) | |
This class emulates relational database on top of Perst storage
It maintains class extends and associated indices. Is supports JSQL and full text search queries.
This class provides version control system, optimistic access control and full text search (using Lucene).
All transactions are isolated from each other and do not see changes made by other transactions
(even committed transactions if commit happens after start of this transaction).
The database keeps all versions of the object hich are grouped in version history.
Version history is linear which means that no branches in version tree are possible.
When transaction tries to update some object then working copy of the current version is created.
Only this copy is changed, leaving all other versions unchanged. This modification will be visible only
for the current transaction. Created or modified objects are linked in indices when transaction is committed.
It means that application will not be able to find in the index just inserted or updated object. It has
first to commit the current transaction. All working copies created during transaction execution
are linked in he list stored in transaction context which is in turn associated with the current thread.
It means two things:
- one thread can participate in only one transaction and one transaction can be controlled only by one thread
- size of transaction is limited by the amount of memory available for the application
When transaction is committed, then all its working copies are inspected. If the last version in version history is
not equal to one from which working copy was created then conflict is detected and ConflictException is thrown.
And if insertion of working copy in index will cause unique constraint violation then NotUniqueException is thrown.
If no conflicts are detected, then transaction is committed and each working copy becomes new version in correspondent
version history.
Isolation of transaction provided by CDatabase class is based on multiversioning and modification of working copies
instead of original objects. Working copy is produced from the current version using clone (shallow copy) method.
Clone will work correctly if components of the objects have primitive type (int, double,...) or are immutable (String).
Using java.util.Date type is possible only if you do not try to update its components.
Instead of normal Java references, you should use references to correspondent CVersionHistory (it allows to preserve
reference consistency if new version of reference object is created).
CDatabase class also supports links (components with Link type) and arrays.
Fields with value type (class implementing IValue interface) can be used only if them are
immutable or cloneable (implement org.garret.perst.ICloneable interface).
Using any other data type including Perst collection classes is not supported and can cause unpredictable behavior.
|
| Inner Class :public enum VersionSortOrder | |
| Method Summary | |
| public void | beginTransaction()
Start new transaction. | | public synchronized void | beginTransaction(long transId)
Start transaction with the given identifier. | | public void | close()
Close the database. | | public long | commitTransaction()
Commit transaction. | | public void | delete(CVersion record)
Mark current version as been deleted.
Parameters:
record - working copy of the current version or current version itself. | | void | excludeFromFullTextIndex(TableDescriptor desc, CVersion v)
| | public IterableIterator<T> | find(Class table, String field, Key key)
Select current version from specified table by key
Parameters:
table - class corresponding to the table
Parameters:
field - indexed field
Parameters:
key - key value iterator through selected records. | | public IterableIterator<T> | find(Class table, String field, Key key, VersionSelector selector)
Select records from the specified table by key using version selector
Parameters:
table - class corresponding to the table
Parameters:
field - indexed field
Parameters:
key - key value
Parameters:
selector - version selector iterator through selected records. | | public IterableIterator<T> | find(Class table, String field, Key min, Key max, VersionSelector selector, int order)
Select records from the specified table by key range using version selector
Parameters:
table - class corresponding to the table
Parameters:
field - indexed field
Parameters:
min - minimal key value
Parameters:
max - maximal key value
Parameters:
selector - version selector
Parameters:
order - key sort order: GenericIndex.ASCENT_ORDER or GenericIndex.DESCENT_ORDER iterator through selected records. | | public FullTextSearchResult[] | fullTextSearch(String query, int limit)
Perform full text search through the current version of all objects in the database
Parameters:
query - full text search search query. | | public FullTextSearchResult[] | fullTextSearch(String query, int limit, VersionSelector selector, VersionSortOrder order)
Perform full text search using version selector
Parameters:
query - full text search search query. | | synchronized IndexReader | getIndexReader()
| | synchronized IndexWriter | getIndexWriter()
| | public IterableIterator<T> | getRecords(Class table)
Get iterator through current version of all table records
Parameters:
table - class corresponding to the table iterator through all table records. | | public IterableIterator<T> | getRecords(Class table, VersionSelector selector)
Get iterator through all records of the table using specified version selector
Parameters:
table - class corresponding to the table
Parameters:
selector - version selector iterator through all table records. | | public IResource | getResource()
| | public T | getSingleton(Iterator<T> iterator)
Extract single result from the returned result set. | | public Storage | getStorage()
| | synchronized TableDescriptor | getTable(Class type)
| | static TransactionContext | getTransactionContext()
| | public IPersistent | getUserData()
Get user data. | | static TransactionContext | getWriteTransactionContext()
| | void | includeInFullTextIndex(Document doc)
| | public void | insert(T record)
| | synchronized TableDescriptor | lookupTable(Class type)
| | public void | open(Storage storage, String fullTextIndexPath)
Open the database. | | void | openFullTextIndex(RootObject root, String path)
| | public synchronized void | optimizeFullTextIndex()
Optimize full text index. | | public Query<T> | prepare(Class table, String predicate)
Prepare JSQL query. | | public Query<T> | prepare(Class table, String predicate, VersionSelector selector)
Prepare JSQL query. | | public synchronized void | restoreFullTextIndex()
Restore full text search index.
If the full text search index is located in file system directory it may be get out of sync with the Perst database or even be
corrupted in case of failure. | | public void | rollbackTransaction()
| | public IterableIterator<T> | select(Class table, String predicate)
Select current version of records from specified table matching specified criteria
Parameters:
table - class corresponding to the table
Parameters:
predicate - search predicate iterator through selected records. | | public IterableIterator<T> | select(Class table, String predicate, VersionSelector selector)
Select records from the specified table using version selector
Parameters:
table - class corresponding to the table
Parameters:
predicate - search predicate
Parameters:
selector - version selector iterator through selected records. | | public void | setUserData(IPersistent obj)
Set user data. | | public T[] | toArray(T[] arr, Iterator<T> iterator, VersionSortOrder order)
Converted returned result set to array.
It should be applied as pipeline to CDatabase.select/CDatabase.find/CDatabase.getRecords/Query.execute methods:
MyClass[] arr = db.toArray(new MyClass[0], db.select(MyClass.class, "price between 100 and 1000 and amount > 100",
VersionSortOrder.ASCENT));
Result set iterator usually selects records in Perst in lazy mode, so execution of query is very
fast but fetching each element requires some additional calculations. | | public List<T> | toList(Iterator<T> iterator)
Convert returned result set to the List collection. | | public List<T> | toList(Iterator<T> iterator, int limit)
Converted returned result set to List collection with limit for number of fetched records. | | public T | update(T record)
Update the record. |
| analyzer | | StandardAnalyzer analyzer(Code) | | |
| indexReader | | IndexReader indexReader(Code) | | |
| indexWriter | | IndexWriter indexWriter(Code) | | |
| instance | | public static CDatabase instance(Code) | | Static instance of the database which can be used by application working with the single database
|
| lastActiveTransId | | long lastActiveTransId(Code) | | |
| maxTransSeqNo | | long maxTransSeqNo(Code) | | |
| minTransSeqNo | | long minTransSeqNo(Code) | | |
| beginTransaction | | public void beginTransaction()(Code) | | Start new transaction. All changes can be made only within transaction context.
Transaction context is associated with thread. It means that one thread can run only one transaction and
one transaction can be handled only by one thread.
Transaction is observing database state at the moment of the transaction start. Any changes done by
other transactions (committed and uncommitted) after this moment are not visible for the current transaction.
CDatabase uses optimistic access control. It means that transaction may be aborted if conflict
is detected during transaction commit.
|
| beginTransaction | | public synchronized void beginTransaction(long transId)(Code) | | Start transaction with the given identifier.
Identifier of the transaction can be obtained using CVersion.getTransactionId() method.
Starting transaction with ID of previously committed transaction allows to obtain snapshot
of the database at the moment of this transaction execution. All search methods
using default version selector (referencing current version) and CVersionHistory.getCurrent()
method will select versions which were current at the moment of this transaction execution.
Parameters:
transId - identifier of previously committed transaction
exception:
TransactionAlreadyStartedException - when thread attempts to start new transaction without committing or aborting previous one. Transaction should be explicitly finished using CDatabase.commit or CDatabase.rollback method.Each thread should start its own transaction, it is not possible to share the same transaction by more than one threads.It is possible to call beginTransaction several times without commit or rollback only if previous transaction was read-only - didn't change any object |
| close | | public void close()(Code) | | Close the database. All uncommitted transaction will be aborted.
Close full text index and storage.
|
| commitTransaction | | public long commitTransaction() throws ConflictException, NotUniqueException(Code) | | Commit transaction.
exception:
ConflictExpetion - is thrown if object modified by this transaction was also changed by some other previously committed transaction
exception:
NotUniqueException - is thrown if indexable field with unique constraint of inserted or updated object contains the same value as current version of some other instance of this class (committed by another transact).Please notice that CDatabase is not able to detect unique constraint violations within one transaction - if itinserts two instances with same value of indexable field. identifier assigned to this transaction or 0 if there is no active transaction. This identifier can be used to obtain snapshot of the database at the moment of this transaction execution. |
| delete | | public void delete(CVersion record)(Code) | | Mark current version as been deleted.
Parameters:
record - working copy of the current version or current version itself. In the last case work copy is created
exception:
NotCurrentVersionException - is thrown if specified version is not current in the version history
exception:
TransactionNotStartedException - if transaction was not started by this thread using CDatabase.beginTransaction |
| find | | public IterableIterator<T> find(Class table, String field, Key key) throws NoSuchIndexException(Code) | | Select current version from specified table by key
Parameters:
table - class corresponding to the table
Parameters:
field - indexed field
Parameters:
key - key value iterator through selected records. This iterator doesn't support remove() method.If there are no instances of such class in the database, then empty iterator is returned
exception:
NoSuchIndexException - if there is no index for the specified field |
| find | | public IterableIterator<T> find(Class table, String field, Key key, VersionSelector selector) throws NoSuchIndexException(Code) | | Select records from the specified table by key using version selector
Parameters:
table - class corresponding to the table
Parameters:
field - indexed field
Parameters:
key - key value
Parameters:
selector - version selector iterator through selected records. This iterator doesn't support remove() method.If there are no instances of such class in the database, then empty iterator is returned
exception:
NoSuchIndexException - if there is no index for the specified field |
| find | | public IterableIterator<T> find(Class table, String field, Key min, Key max, VersionSelector selector, int order)(Code) | | Select records from the specified table by key range using version selector
Parameters:
table - class corresponding to the table
Parameters:
field - indexed field
Parameters:
min - minimal key value
Parameters:
max - maximal key value
Parameters:
selector - version selector
Parameters:
order - key sort order: GenericIndex.ASCENT_ORDER or GenericIndex.DESCENT_ORDER iterator through selected records. This iterator doesn't support remove() method.If there are no instances of such class in the database, then empty iterator is returned
exception:
NoSuchIndexException - if there is no index for the specified field |
| fullTextSearch | | public FullTextSearchResult[] fullTextSearch(String query, int limit)(Code) | | Perform full text search through the current version of all objects in the database
Parameters:
query - full text search search query. It should be compliant with Lucene query syntax and mayrefer to the particular fields or to any full text searchable field:- "name:John" - select document with field "name" containing word "John"
- "title:magic AND author:Clark" - select document with field "title" containing word "magic" and field "author"containing word "Clark"
- "atomic nuclear power" - select any document which full text searchable fields contain any of the specified words
- "Class:com.eshop.Player AND description:DivX" - select objects with class com.eshop.Player which description contains word "DivX"
Parameters:
limit - search result limit array with matched documents
exception:
FullTextSearchQuerySyntaxError - if query syntax is invalid |
| fullTextSearch | | public FullTextSearchResult[] fullTextSearch(String query, int limit, VersionSelector selector, VersionSortOrder order)(Code) | | Perform full text search using version selector
Parameters:
query - full text search search query. It should be compliant with Lucene query syntax and mayrefer to the particular fields or to any full text searchable field:- "name:John" - select document with field "name" containing word "John"
- "title:magic AND author:Clark" - select document with field "title" containing word "magic" and field "author"containing word "Clark"
- "atomic nuclear power" - select any document which full text searchable fields contain any of the specified words
- "Class:com.eshop.Player AND description:DivX" - select objects with class com.eshop.Player which description contains word "DivX"
Parameters:
limit - search result limit
Parameters:
selector - version selector
Parameters:
order - result set versions sort order (if VersionSortOrder.NONE then order of documents returned by Lucene is preserved - documents are sorted by score) array with matched documents
exception:
FullTextSearchQuerySyntaxError - if query syntax is invalid |
| getRecords | | public IterableIterator<T> getRecords(Class table)(Code) | | Get iterator through current version of all table records
Parameters:
table - class corresponding to the table iterator through all table records. If there are no instances of such class in the database, then emptyiterator is returned |
| getRecords | | public IterableIterator<T> getRecords(Class table, VersionSelector selector)(Code) | | Get iterator through all records of the table using specified version selector
Parameters:
table - class corresponding to the table
Parameters:
selector - version selector iterator through all table records. If there are no instances of such class in the database, then emptyiterator is returned |
| getResource | | public IResource getResource()(Code) | | Get resource used to synchronize access to the database
|
| getSingleton | | public T getSingleton(Iterator<T> iterator) throws SingletonException(Code) | | Extract single result from the returned result set.
It should be applied as pipeline to CDatabase.select/CDatabase.find/CDatabase.getRecords/Query.execute methods:
MyClass obj = db.getSingleton(db.find(MyClass.class, "key", value));
Parameters:
iterator - result set iterator returned by CDatabase.select/CDatabase.find/CDatabase.getRecords/Query.executemethods selected object if result set contains exactly one object or null if result set is empty
exception:
SingletonException - if result set contains more than one element |
| getStorage | | public Storage getStorage()(Code) | | Get storage associated with this database
underlying storage |
| getUserData | | public IPersistent getUserData()(Code) | | Get user data. Continuous uses Perst root objects for its own purposes.
But this methods allows application to specify its own root and store in the Perst
storage non-versioned objects.
reference to the persistent object previously stored by setUserData() |
| includeInFullTextIndex | | void includeInFullTextIndex(Document doc)(Code) | | |
| open | | public void open(Storage storage, String fullTextIndexPath)(Code) | | Open the database. This method initialize database if it not initialized yet.
Parameters:
storage - opened storage. Storage should be either empty (non-initialized, eitherpreviously initialized by the this method. It is not possible to open storage with root object other than RootObject created by this method.
Parameters:
fullTextIndexPath - path to the directory containing Lucene database. If null, then Lucene index will be stored inside the main Perst storage. |
| optimizeFullTextIndex | | public synchronized void optimizeFullTextIndex()(Code) | | Optimize full text index. This method can be periodically called by application (preferably in idle time)
to optimize full text search index
|
| prepare | | public Query<T> prepare(Class table, String predicate)(Code) | | Prepare JSQL query. Prepare is needed for queries with parameters. Also
preparing query can improve speed if query will be executed multiple times
(using prepare, it is compiled only once).
To execute prepared query, you should use Query.execute(db.getRecords(TABLE.class)) method
Parameters:
table - class corresponding to the table
Parameters:
predicate - search predicate prepared query
exception:
CompileError - exception is thrown if predicate is not valid JSQL exception |
| prepare | | public Query<T> prepare(Class table, String predicate, VersionSelector selector)(Code) | | Prepare JSQL query. Prepare is needed for queries with parameters. Also
preparing query can improve speed if query will be executed multiple times
(using prepare, it is compiled only once).
To execute prepared query, you should use Query.execute(db.getRecords(TABLE.class)) method
Parameters:
table - class corresponding to the table
Parameters:
predicate - search predicate
Parameters:
selector - version selector prepared query
exception:
CompileError - exception is thrown if predicate is not valid JSQL exception |
| restoreFullTextIndex | | public synchronized void restoreFullTextIndex()(Code) | | Restore full text search index.
If the full text search index is located in file system directory it may be get out of sync with the Perst database or even be
corrupted in case of failure. In this case index can be reconstructed using this method.
|
| rollbackTransaction | | public void rollbackTransaction()(Code) | | Rollback transaction
|
| select | | public IterableIterator<T> select(Class table, String predicate)(Code) | | Select current version of records from specified table matching specified criteria
Parameters:
table - class corresponding to the table
Parameters:
predicate - search predicate iterator through selected records. This iterator doesn't support remove() method.If there are no instances of such class in the database, then empty iterator is returned
exception:
CompileError - exception is thrown if predicate is not valid JSQL exception
exception:
JSQLRuntimeException - exception is thrown if there is runtime error during query execution |
| select | | public IterableIterator<T> select(Class table, String predicate, VersionSelector selector)(Code) | | Select records from the specified table using version selector
Parameters:
table - class corresponding to the table
Parameters:
predicate - search predicate
Parameters:
selector - version selector iterator through selected records. This iterator doesn't support remove() method.If there are no instances of such class in the database, then empty iterator is returned
exception:
CompileError - exception is thrown if predicate is not valid JSQL exception
exception:
JSQLRuntimeException - exception is thrown if there is runtime error during query execution |
| setUserData | | public void setUserData(IPersistent obj)(Code) | | Set user data. Continuous uses Perst root objects for its own purposes.
But this methods allows application to specify its own root and store in the Perst
storage non-versioned objects.
Parameters:
obj - reference to the persistent object which will be stored in Perst root object |
| toArray | | public T[] toArray(T[] arr, Iterator<T> iterator, VersionSortOrder order)(Code) | | Converted returned result set to array.
It should be applied as pipeline to CDatabase.select/CDatabase.find/CDatabase.getRecords/Query.execute methods:
MyClass[] arr = db.toArray(new MyClass[0], db.select(MyClass.class, "price between 100 and 1000 and amount > 100",
VersionSortOrder.ASCENT));
Result set iterator usually selects records in Perst in lazy mode, so execution of query is very
fast but fetching each element requires some additional calculations.
Using this method you can force loading of all result set elements. So you will know
precise number of selected results, can access them in any order and without extra overhead.
The payment for these advantages is increased time of query execution and amount of memory needed
to hold all selected objects.
Specifying sort order allows for example to select the first/last version satisfying search criteria.
Parameters:
arr - the array into which the elements of the list are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.
Parameters:
iterator - result set iterator returned by CDatabase.select/CDatabase.find/CDatabase.getRecords/Query.executemethods
Parameters:
order - version sort order: ASCENT, DESCENT or NONE. Array elements will be sorted by version identifiers. If sort order is not specified NONE (then records in the result array will be in the same order as returned by the iterator) an array containing selected objects in the given order |
| toList | | public List<T> toList(Iterator<T> iterator)(Code) | | Convert returned result set to the List collection.
It should be applied as pipeline to CDatabase.select/CDatabase.find/CDatabase.getRecords/Query.execute methods:
List list = db.toList(db.select(MyClass.class, "price between 100 and 1000 and amount > 100"));
Result set iterator usually selects records in Perst in lazy mode, so execution of query is very
fast but fetching each element requires some additional calculations.
Using this method you can force loading of all result set elements. So you will know
precise number of selected records, can access them in any order and without extra overhead.
The payment for these advantages is increased time of query execution and amount of memory needed
to hold all selected objects.
Parameters:
iterator - result set iterator returned by CDatabase.select/CDatabase.find/CDatabase.getRecords/Query.executemethods List containing all selected objects |
| toList | | public List<T> toList(Iterator<T> iterator, int limit)(Code) | | Converted returned result set to List collection with limit for number of fetched records.
It should be applied as pipeline to CDatabase.select/CDatabase.find/CDatabase.getRecords/Query.execute methods:
List list = db.toList(db.select(MyClass.class, "price between 100 and 1000 and amount > 100"));
Result set iterator usually selects records in Perst in lazy mode, so execution of query is very
fast but fetching each element requires some additional calculations.
Using this method you can force loading of all result set elements. So you will know
precise number of selected results, can access them in any order and without extra overhead.
The payment for these advantages is increased time of query execution and amount of memory needed
to hold all selected objects.
Parameters:
iterator - result set iterator returned by CDatabase.select/CDatabase.find/CDatabase.getRecords/Query.executemethods
Parameters:
limit - result list limit List containing selected objects, if number of selected objects is larger than specified limit, then only first limit of them will be placed in the list and other will be ignored. |
| update | | public T update(T record)(Code) | | Update the record.
Parameters:
record - updated record working copy of the specified version
exception:
AmbiguousVersionException - when some other version from the same version history was already updated by the current transaction
exception:
TransactionNotStartedException - if transaction was not started by this thread using CDatabase.beginTransaction |
|
|