JSimpleDB (JSimpleDB Main Classes 2.1.2 API)

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

Methods
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 `JClass`es 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 `Validator`s 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, or zero to use the highest version already recorded in the database
    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 not greater than zero
    
    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 else zero, indicating that the highest schema version found in the database should be used.
    
    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

Class JSimpleDB

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

GENERATED_CLASS_NAME_SUFFIX

Constructor Detail

JSimpleDB

JSimpleDB

JSimpleDB

Method Detail

getDatabase

getConfiguredVersion

getActualVersion

getModelClass

createTransaction

createTransaction

createTransaction

createSnapshotTransaction

createSnapshotTransaction

getSchemaModel

getNameIndex

getJClasses

getJClassesByType

getJClass

findJClass

getJClass

getJClass

getJClasses

parseReferencePath

setValidatorFactory

getReferencedObjects