org.jsimpledb

Class JSimpleDB

java.lang.Object

org.jsimpledb.JSimpleDB

public class JSimpleDB
extends Object

JSimpleDB Java persistence layer.

JSimpleDB is a Java persistence solution built on three layers of abstraction:

• At the bottom layer is a simple byte[] key/value database represented by the KVDatabase class. Transactions are supported at this layer and are accessed through the KVTransaction interface. There are several available KVDatabase implementations, including "wrappers" for several third party key/value stores.
• On top of that sits the core API layer, which provides a rigourous database abstraction on top of the key/value store. It supports simple fields of any atomic Java type, as well as list, set, and map complex fields, tightly controlled schema versioning, simple and composite indexes, and lifecycle and change notifications. It is not Java-specific or explicitly object-oriented. The core API is accessed through the Database and Transaction classes.
• The top layer is a Java-centric, type safe, object-oriented persistence layer for Java applications. It sits on top of the core API layer and provides a fully type-safe Java view of a core API Transaction, where all access is through user-supplied Java model classes. Database types and fields, and Java listener methods are all declared using Java annotations. Incremental JSR 303 validation is supported. The JSimpleDB class represents an instance of this top layer database, and JTransaction represents the corresonding transactions.

User-provided Java model classes define database fields by declaring abstract Java bean property methods. JSimpleDB generates concrete subclasses of the user-provided abstract model classes at runtime. These runtime classes implement the abstract bean property methods, as well as the JObject interface. Java model class instances are always associated with a specific JTransaction, and all of their database state derives from that the underlying key/value KVTransaction.

All Java model class instances have a unique ObjId which represents database identity. JSimpleDB guarantees that at most one Java model class instance instance will exist for any given JTransaction and ObjId. Instance creation, index queries, and certain other database-related tasks are initiated using a JTransaction.

Normal database transactions are created via createTransaction(). "Snapshot" transactions are purely in-memory transactions that are detached from the database and may persist indefinitely. Their purpose is to hold a snapshot of some (user-defined) portion of the database content for use outside of a regular transaction. Otherwise, they function like normal transactions, with support for index queries, listener callbacks, etc. See JTransaction.createSnapshotTransaction(), JTransaction.getSnapshotTransaction(), JObject.copyOut(), and JObject.copyIn().

Instances of this class are usually created using a JSimpleDBFactory.

See Also:

JObject, JTransaction, JSimpleDBFactory, org.jsimpledb.annotation

Field Summary

Fields

Modifier and Type	Field and Description
static String	GENERATED_CLASS_NAME_SUFFIX The suffix that is appended to Java model class names to get the corresponding JSimpleDB generated class name.

Constructor Summary

Constructors

Constructor and Description
JSimpleDB(Class<?>... classes) Create an instance using an initially empty, in-memory SimpleKVDatabase.
JSimpleDB(Database database, int version, StorageIdGenerator storageIdGenerator, Iterable<? extends Class<?>> classes) Primary constructor.
JSimpleDB(Iterable<? extends Class<?>> classes) Create an instance using an initially empty, in-memory SimpleKVDatabase.

Method Summary

Modifier and Type	Method and Description
SnapshotJTransaction	createSnapshotTransaction(KVStore kvstore, boolean allowNewSchema, ValidationMode validationMode) Create a new SnapshotJTransaction based on the provided key/value store.
SnapshotJTransaction	createSnapshotTransaction(ValidationMode validationMode) Create a new, empty SnapshotJTransaction backed by a NavigableMapKVStore.
JTransaction	createTransaction(boolean allowNewSchema, ValidationMode validationMode) Create a new transaction.
JTransaction	createTransaction(boolean allowNewSchema, ValidationMode validationMode, Map<String,?> kvoptions) Create a new transaction with key/value transaction options.
JTransaction	createTransaction(KVTransaction kvt, boolean allowNewSchema, ValidationMode validationMode) Create a new transaction using an already-opened KVTransaction.
<T> JClass<? super T>	findJClass(Class<T> type) Find the most specific JClass for which the give type is a sub-type of the corresponding Java model type.
int	getActualVersion() Get the schema version that this instance used for the most recently created transaction.
int	getConfiguredVersion() Get the schema version that this instance was configured to use.
Database	getDatabase() Get the core API Database underlying this instance.
<T> JClass<T>	getJClass(Class<T> type) Get the JClass modeled by the given type.
JClass<?>	getJClass(int storageId) Get the JClass associated with the given storage ID.
JClass<?>	getJClass(ObjId id) Get the JClass associated with the object ID.
SortedMap<Integer,JClass<?>>	getJClasses() Get all JClass's associated with this instance, indexed by storage ID.
<T> List<JClass<? extends T>>	getJClasses(Class<T> type) Get all JClasses which sub-type the given type.
Map<Class<?>,JClass<?>>	getJClassesByType() Get all JClass's associated with this instance, indexed by Java model type.
static Class<?>	getModelClass(JObject jobj) Get the Java model class of the given JObject.
NameIndex	getNameIndex() Get a NameIndex based on this instance's schema model.
Iterable<JObject>	getReferencedObjects(JObject jobj) Utility method to get all of the objects directly referenced by a given object via any field.
SchemaModel	getSchemaModel() Get the SchemaModel associated with this instance, derived from the annotations on the scanned classes.
ReferencePath	parseReferencePath(Class<?> startType, String path) Parse a ReferencePath in String form.
void	setValidatorFactory(ValidatorFactory validatorFactory) Configure a custom ValidatorFactory used to create Validators for validation within transactions.

Methods inherited from class java.lang.Object

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

Field Detail

GENERATED_CLASS_NAME_SUFFIX

public static final String GENERATED_CLASS_NAME_SUFFIX

The suffix that is appended to Java model class names to get the corresponding JSimpleDB generated class name.

See Also:

Constant Field Values

Constructor Detail

JSimpleDB

public JSimpleDB(Iterable<? extends Class<?>> classes)

Create an instance using an initially empty, in-memory SimpleKVDatabase. Generates a database schema by introspecting the classes; schema version number 1 is assumed and a DefaultStorageIdGenerator is used to auto-generate storage ID's where necessary.

This constructor can also be used just to validate the annotations on the given classes.

Parameters:

classes - classes annotated with @JSimpleClass annotations

Throws:

IllegalArgumentException - if classes is null

IllegalArgumentException - if classes contains a null class or a class with invalid annotation(s)

InvalidSchemaException - if the schema implied by classes is invalid

JSimpleDB

public JSimpleDB(Class<?>... classes)

Create an instance using an initially empty, in-memory SimpleKVDatabase.

Equivalent to JSimpleDB(Arrays.asList(classes)).

Parameters:

classes - classes annotated with @JSimpleClass annotations

See Also:

JSimpleDB(Iterable)

JSimpleDB

public JSimpleDB(Database database,
                 int version,
                 StorageIdGenerator storageIdGenerator,
                 Iterable<? extends Class<?>> classes)

Primary constructor.

Parameters:

database - core database to use

version - schema version number of the schema derived from classes, zero to use the highest version already recorded in the database, or -1 to use an auto-generated schema version

storageIdGenerator - generator for auto-generated storage ID's, or null to disallow auto-generation of storage ID's

classes - classes annotated with @JSimpleClass annotations; non-annotated classes are ignored

Throws:

IllegalArgumentException - if database or classes is null

IllegalArgumentException - if version is less than -1

IllegalArgumentException - if classes contains a null class or a class with invalid annotation(s)

InvalidSchemaException - if the schema implied by classes is invalid

Method Detail

getDatabase

public Database getDatabase()

Get the core API Database underlying this instance.

Returns:

underlying Database

getConfiguredVersion

public int getConfiguredVersion()

Get the schema version that this instance was configured to use.

This will either be a specific non-zero schema version number, or zero, indicating that the highest schema version found in the database should be used.

If -1 was configured, this will return the actual auto-generated schema version.

Returns:

the schema version that this instance will use when opening transactions via Database.createTransaction()

getActualVersion

public int getActualVersion()

Get the schema version that this instance used for the most recently created transaction.

If no transactions have been created yet, this returns zero. Otherwise, it returns the schema version used by the most recently created transaction.

If the version passed to the constructor was zero, this method can be used to read the highest schema version seen in the database by the most recently created transaction.

If the version passed to the constructor was non-zero, and at least one transaction has been created, this method will return the same value.

Returns:

the schema version that this instance used in the most recently created transaction

getModelClass

public static Class<?> getModelClass(JObject jobj)

Get the Java model class of the given JObject.

If jobj is an instance of a JSimpleDB-generated subclass of a user-supplied Java model class, this returns the original Java model class. Otherwise, it returns obj's type.

Parameters:

jobj - database instance

Returns:

lowest ancestor class of jobj's class that is not a JSimpleDB-generated subclass

Throws:

IllegalArgumentException - if jobj is null

createTransaction

public JTransaction createTransaction(boolean allowNewSchema,
                                      ValidationMode validationMode)

Create a new transaction.

Convenience method; equivalent to:

  createTransaction(allowNewSchema, validationMode, null)
  

Parameters:

allowNewSchema - whether creating a new schema version is allowed

validationMode - the ValidationMode to use for the new transaction

Returns:

the newly created transaction

Throws:

InvalidSchemaException - if schemaModel does not match what's recorded in the database for the schema version provided to the constructor

InvalidSchemaException - if the schema version provided to the constructor is not recorded in the database and allowNewSchema is false

InvalidSchemaException - if the schema version provided to the constructor is not recorded in the database and allowNewSchema is true, but schemaModel is incompatible with one or more previous schemas alread recorded in the database (i.e., the same storage ID is used incompatibly between schema versions)

InconsistentDatabaseException - if inconsistent or invalid meta-data is detected in the database

IllegalArgumentException - if validationMode is null

createTransaction

public JTransaction createTransaction(boolean allowNewSchema,
                                      ValidationMode validationMode,
                                      Map<String,?> kvoptions)

Create a new transaction with key/value transaction options.

This does not invoke JTransaction.setCurrent(): the caller is responsible for doing that if necessary. However, this method does arrange for JTransaction.setCurrent(null) to be invoked as soon as the returned transaction is committed (or rolled back), assuming JTransaction.getCurrent() returns the JTransaction returned here at that time.

Parameters:

allowNewSchema - whether creating a new schema version is allowed

validationMode - the ValidationMode to use for the new transaction

kvoptions - optional KVDatabase-specific transaction options; may be null

Returns:

the newly created transaction

Throws:

InvalidSchemaException - if schemaModel does not match what's recorded in the database for the schema version provided to the constructor

InvalidSchemaException - if the schema version provided to the constructor is not recorded in the database and allowNewSchema is false

InvalidSchemaException - if the schema version provided to the constructor is not recorded in the database and allowNewSchema is true, but schemaModel is incompatible with one or more previous schemas alread recorded in the database (i.e., the same storage ID is used incompatibly between schema versions)

InconsistentDatabaseException - if inconsistent or invalid meta-data is detected in the database

IllegalArgumentException - if validationMode is null

createTransaction

public JTransaction createTransaction(KVTransaction kvt,
                                      boolean allowNewSchema,
                                      ValidationMode validationMode)

Create a new transaction using an already-opened KVTransaction.

This does not invoke JTransaction.setCurrent(): the caller is responsible for doing that if necessary. However, this method does arrange for JTransaction.setCurrent(null) to be invoked as soon as the returned transaction is committed (or rolled back), assuming JTransaction.getCurrent() returns the JTransaction returned here at that time.

Parameters:

kvt - already opened key/value store transaction

allowNewSchema - whether creating a new schema version is allowed

validationMode - the ValidationMode to use for the new transaction

Returns:

the newly created transaction

Throws:

InvalidSchemaException - if schemaModel does not match what's recorded in the database for the schema version provided to the constructor

InvalidSchemaException - if the schema version provided to the constructor is not recorded in the database and allowNewSchema is false

InvalidSchemaException - if the schema version provided to the constructor is not recorded in the database and allowNewSchema is true, but schemaModel is incompatible with one or more previous schemas alread recorded in the database (i.e., the same storage ID is used incompatibly between schema versions)

InconsistentDatabaseException - if inconsistent or invalid meta-data is detected in the database

IllegalArgumentException - if kvt or validationMode is null

createSnapshotTransaction

public SnapshotJTransaction createSnapshotTransaction(ValidationMode validationMode)

Create a new, empty SnapshotJTransaction backed by a NavigableMapKVStore.

The returned SnapshotJTransaction does not support commit() or rollback(), and can be used indefinitely.

Parameters:

validationMode - the ValidationMode to use for the snapshot transaction

Returns:

initially empty snapshot transaction

createSnapshotTransaction

public SnapshotJTransaction createSnapshotTransaction(KVStore kvstore,
                                                      boolean allowNewSchema,
                                                      ValidationMode validationMode)

Create a new SnapshotJTransaction based on the provided key/value store.

The key/value store will be initialized if necessary (i.e., kvstore may be empty), otherwise it will be validated against the schema information associated with this instance.

The returned SnapshotJTransaction does not support commit() or rollback(), and can be used indefinitely.

Parameters:

kvstore - key/value store, empty or having content compatible with this transaction's JSimpleDB

allowNewSchema - whether creating a new schema version in kvstore is allowed

validationMode - the ValidationMode to use for the snapshot transaction

Returns:

snapshot transaction based on kvstore

Throws:

SchemaMismatchException - if kvstore contains incompatible or missing schema information

InconsistentDatabaseException - if inconsistent or invalid meta-data is detected in the database

IllegalArgumentException - if kvstore is null

getSchemaModel

public SchemaModel getSchemaModel()

Get the SchemaModel associated with this instance, derived from the annotations on the scanned classes.

Returns:

the associated schema model

getNameIndex

public NameIndex getNameIndex()

Get a NameIndex based on this instance's schema model.

Returns:

a name index on this instance's schema model

getJClasses

public SortedMap<Integer,JClass<?>> getJClasses()

Get all JClass's associated with this instance, indexed by storage ID.

Returns:

read-only mapping from storage ID to JClass

getJClassesByType

public Map<Class<?>,JClass<?>> getJClassesByType()

Get all JClass's associated with this instance, indexed by Java model type.

Returns:

read-only mapping from Java model type to JClass

getJClass

public <T> JClass<T> getJClass(Class<T> type)

Get the JClass modeled by the given type.

Type Parameters:

T - Java model type

Parameters:

type - an annotated Java object model type

Returns:

associated JClass

Throws:

IllegalArgumentException - if type is not equal to a known Java object model type

findJClass

public <T> JClass<? super T> findJClass(Class<T> type)

Find the most specific JClass for which the give type is a sub-type of the corresponding Java model type.

Type Parameters:

T - Java model type or subtype thereof

Parameters:

type - (sub)type of some Java object model type

Returns:

narrowest JClass whose Java object model type is a supertype of type, or null if none found

getJClass

public JClass<?> getJClass(ObjId id)

Get the JClass associated with the object ID.

Parameters:

id - object ID

Returns:

JClass instance

Throws:

TypeNotInSchemaVersionException - if id has a type that does not exist in this instance's schema version

IllegalArgumentException - if id is null

getJClass

public JClass<?> getJClass(int storageId)

Get the JClass associated with the given storage ID.

Parameters:

storageId - object type storage ID

Returns:

JClass instance

Throws:

UnknownTypeException - if storageId does not represent an object type

getJClasses

public <T> List<JClass<? extends T>> getJClasses(Class<T> type)

Get all JClasses which sub-type the given type.

Type Parameters:

T - Java model type

Parameters:

type - type restriction, or null for no restrction

Returns:

list of JClasses whose type is type or a sub-type, ordered by storage ID

parseReferencePath

public ReferencePath parseReferencePath(Class<?> startType,
                                        String path)

Parse a ReferencePath in String form.

Parameters:

startType - starting Java type for the path

path - dot-separated path of zero or more reference fields, followed by a target field

Returns:

parsed reference path

Throws:

IllegalArgumentException - if path is invalid

IllegalArgumentException - if startType or path is null

See Also:

ReferencePath

setValidatorFactory

public void setValidatorFactory(ValidatorFactory validatorFactory)

Configure a custom ValidatorFactory used to create Validators for validation within transactions.

Parameters:

validatorFactory - factory for validators

Throws:

IllegalArgumentException - if validatorFactory is null

getReferencedObjects

public Iterable<JObject> getReferencedObjects(JObject jobj)

Utility method to get all of the objects directly referenced by a given object via any field.

Note: the returned Iterable may contain duplicates; these can be eliminated using an ObjIdSet if necessary.

Parameters:

jobj - starting object

Returns:

all objects directly referenced by jobj

Throws:

IllegalArgumentException - if jobj is null