public class JSimpleDB extends Object
JSimpleDB is a Java persistence solution built on three layers of abstraction:
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.Database
and Transaction classes.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.
JObject,
JTransaction,
JSimpleDBFactory,
org.jsimpledb.annotation| 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 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. |
| 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. |
public static final String GENERATED_CLASS_NAME_SUFFIX
public JSimpleDB(Iterable<? extends Class<?>> classes)
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.
classes - classes annotated with @JSimpleClass annotationsIllegalArgumentException - if classes is nullIllegalArgumentException - if classes contains a null class or a class with invalid annotation(s)InvalidSchemaException - if the schema implied by classes is invalidpublic JSimpleDB(Class<?>... classes)
SimpleKVDatabase.
Equivalent to JSimpleDB(Arrays.asList(classes)).
classes - classes annotated with @JSimpleClass annotationsJSimpleDB(Iterable)public JSimpleDB(Database database, int version, StorageIdGenerator storageIdGenerator, Iterable<? extends Class<?>> classes)
database - core database to useversion - 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 versionstorageIdGenerator - generator for auto-generated storage ID's, or null to disallow auto-generation of storage ID'sclasses - classes annotated with @JSimpleClass annotations; non-annotated classes are ignoredIllegalArgumentException - if database or classes is nullIllegalArgumentException - if version is less than -1IllegalArgumentException - if classes contains a null class or a class with invalid annotation(s)InvalidSchemaException - if the schema implied by classes is invalidpublic Database getDatabase()
Database underlying this instance.Databasepublic int getConfiguredVersion()
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.
Database.createTransaction()public int getActualVersion()
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.
public static Class<?> getModelClass(JObject jobj)
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.
jobj - database instancejobj's class that is not a JSimpleDB-generated subclassIllegalArgumentException - if jobj is nullpublic JTransaction createTransaction(boolean allowNewSchema, ValidationMode validationMode)
Convenience method; equivalent to:
createTransaction(allowNewSchema, validationMode, null)
allowNewSchema - whether creating a new schema version is allowedvalidationMode - the ValidationMode to use for the new transactionInvalidSchemaException - if schemaModel does not match what's recorded in the
database for the schema version provided to the constructorInvalidSchemaException - if the schema version provided to the constructor
is not recorded in the database and allowNewSchema is falseInvalidSchemaException - 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 databaseIllegalArgumentException - if validationMode is nullpublic JTransaction createTransaction(boolean allowNewSchema, ValidationMode validationMode, Map<String,?> kvoptions)
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.
allowNewSchema - whether creating a new schema version is allowedvalidationMode - the ValidationMode to use for the new transactionkvoptions - optional KVDatabase-specific transaction options; may be nullInvalidSchemaException - if schemaModel does not match what's recorded in the
database for the schema version provided to the constructorInvalidSchemaException - if the schema version provided to the constructor
is not recorded in the database and allowNewSchema is falseInvalidSchemaException - 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 databaseIllegalArgumentException - if validationMode is nullpublic JTransaction createTransaction(KVTransaction kvt, boolean allowNewSchema, ValidationMode validationMode)
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.
kvt - already opened key/value store transactionallowNewSchema - whether creating a new schema version is allowedvalidationMode - the ValidationMode to use for the new transactionInvalidSchemaException - if schemaModel does not match what's recorded in the
database for the schema version provided to the constructorInvalidSchemaException - if the schema version provided to the constructor
is not recorded in the database and allowNewSchema is falseInvalidSchemaException - 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 databaseIllegalArgumentException - if kvt or validationMode is nullpublic SnapshotJTransaction createSnapshotTransaction(ValidationMode validationMode)
SnapshotJTransaction backed by a NavigableMapKVStore.
The returned SnapshotJTransaction does not support commit() or
rollback(), and can be used indefinitely.
validationMode - the ValidationMode to use for the snapshot transactionpublic SnapshotJTransaction createSnapshotTransaction(KVStore kvstore, boolean allowNewSchema, ValidationMode validationMode)
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.
kvstore - key/value store, empty or having content compatible with this transaction's JSimpleDBallowNewSchema - whether creating a new schema version in kvstore is allowedvalidationMode - the ValidationMode to use for the snapshot transactionkvstoreSchemaMismatchException - if kvstore contains incompatible or missing schema informationInconsistentDatabaseException - if inconsistent or invalid meta-data is detected in the databaseIllegalArgumentException - if kvstore is nullpublic SchemaModel getSchemaModel()
SchemaModel associated with this instance, derived from the annotations on the scanned classes.public NameIndex getNameIndex()
NameIndex based on this instance's schema model.public SortedMap<Integer,JClass<?>> getJClasses()
JClass's associated with this instance, indexed by storage ID.JClasspublic Map<Class<?>,JClass<?>> getJClassesByType()
JClass's associated with this instance, indexed by Java model type.JClasspublic <T> JClass<T> getJClass(Class<T> type)
JClass modeled by the given type.T - Java model typetype - an annotated Java object model typeJClassIllegalArgumentException - if type is not equal to a known Java object model typepublic <T> JClass<? super T> findJClass(Class<T> type)
JClass for which the give type is a sub-type of the corresponding Java model type.T - Java model type or subtype thereoftype - (sub)type of some Java object model typeJClass whose Java object model type is a supertype of type, or null if none foundpublic JClass<?> getJClass(ObjId id)
JClass associated with the object ID.id - object IDJClass instanceTypeNotInSchemaVersionException - if id has a type that does not exist in this instance's schema versionIllegalArgumentException - if id is nullpublic JClass<?> getJClass(int storageId)
JClass associated with the given storage ID.storageId - object type storage IDJClass instanceUnknownTypeException - if storageId does not represent an object typepublic <T> List<JClass<? extends T>> getJClasses(Class<T> type)
JClasses which sub-type the given type.T - Java model typetype - type restriction, or null for no restrctionJClasses whose type is type or a sub-type, ordered by storage IDpublic ReferencePath parseReferencePath(Class<?> startType, String path)
ReferencePath in String form.startType - starting Java type for the pathpath - dot-separated path of zero or more reference fields, followed by a target fieldIllegalArgumentException - if path is invalidIllegalArgumentException - if startType or path is nullReferencePathpublic void setValidatorFactory(ValidatorFactory validatorFactory)
ValidatorFactory used to create Validators
for validation within transactions.validatorFactory - factory for validatorsIllegalArgumentException - if validatorFactory is nullpublic Iterable<JObject> getReferencedObjects(JObject jobj)
Note: the returned Iterable may contain duplicates; these can be eliminated using an
ObjIdSet if necessary.
jobj - starting objectjobjIllegalArgumentException - if jobj is nullCopyright © 2017. All rights reserved.