com.vordel.es
Interface EntityStore

All Superinterfaces:

TypeStore

public interface EntityStore
extends TypeStore

The EntityStore interface defines a common contract for access to all providers of the EntityStore service.

Field Summary

static ESPK	ES_NULL_PK A key representing a null reference
static int	EXPORT_CLOSURE Used with exportContents(), this flag indicates that any entities which are referred to by exported entities are also exported.
static int	EXPORT_ENTITIES Used with exportContents(), this flag indicates that the entities should be exported.
static int	EXPORT_PORTABLE_ESPKS Used with exportContents(), this flag indicates that the ESPK values for the entities are normalized, allowing import into other ES stores.
static int	EXPORT_REALIZED_TYPES Used with exportContents(), this flag indicates that only types which are instantiated are to be exported.
static int	EXPORT_SOFT_REF_CLOSURE Used with exportContents(), this flag indicates that soft references are followed for closure when the reference can be resolved to another entity.
static int	EXPORT_TRUNKS Used with exportContents(), this flag will ensure all entities leading from the export roots back to the main store root get exported too.
static int	EXPORT_TYPES Used with exportContents(), this flag indicates that the types should be exported.
static int	IMPORT_DIRECTIVE_OVERRIDE_ALL Used with exportContents(), this flag indicates that all exported entities should be flagged with the override directive for subsequent import.

Fields inherited from interface com.vordel.es.TypeStore

BASE_TYPE_NAME

Method Summary

ESPK	addEntity(ESPK parentPK, Entity entity) Add an Entity to the Store.
void	commit() Indicate that you wish to have all operations on the Store since the last startTransaction committed to the Store, and published to the Store's listeners.
void	connect(java.lang.String url, java.util.Properties credentials) Connect to an entity store.
ESPK	decodePK(java.lang.String stringifiedPK) Decode a stringified PK as per the implementation.
void	deleteEntity(ESPK pk) Delete an entity from the data store.
void	deregisterChangeListener(ESPK entityPK, ESChangeListener listener) Deregister from listening to changes to the Entities in the Store.
void	disconnect() Disconnect from the EntityStore.
void	exportContents(java.io.OutputStream out, java.util.Collection<ESPK> startNodes, int flags) Export the contents of the entity store to the specified output stream.
java.util.Collection<ESPK>	findChildren(ESPK pk, Field[] fvals, EntityType ofType) Find all children of a particular Entity.
java.util.Collection<ESPK>	findReferringEntities(ESPK targetEntityPK) Get a Set of ESPKs which identify all Entities in the store which contain a field or fields which hold a reference to the Entity specified
Entity	getEntity(ESPK pk) Get a particular Entity from the Store, depending on its key.
Entity	getEntity(ESPK pk, java.lang.String[] requiredFieldNames) Retrieve the subordinate Entities of the identified parent.
ESPK	getRootPK() Get the identifier for the root Entity in the Store.
java.util.Collection<ESPK>	importData(java.io.InputStream stream) Import a serialized definition of the Store.
void	initialize() Connect to the EntityStore and bootstrap the store with the default components required to implement a store.
java.util.Collection<ESPK>	listChildren(ESPK pk, EntityType type) List all children of a particular Entity.
void	registerChangeListener(ESPK entityPK, ESChangeListener listener) Register to listen to changes to the Entities in the Store.
void	rollback() Indicate that you wish to discard all changes to the Store since the last startTransaction.
void	startTransaction() Indicate to the Store that you want to start a transaction.
void	updateEntity(Entity entity) Replace an entity

Methods inherited from interface com.vordel.es.TypeStore

addType, getBaseType, getSubtypes, getTypeForName, reset, updateType

Field Detail

EXPORT_TYPES

static final int EXPORT_TYPES

Used with exportContents(), this flag indicates that the types should be exported.

See Also:

Constant Field Values

EXPORT_ENTITIES

static final int EXPORT_ENTITIES

Used with exportContents(), this flag indicates that the entities should be exported. You'll normally want this set.

See Also:

Constant Field Values

EXPORT_CLOSURE

static final int EXPORT_CLOSURE

Used with exportContents(), this flag indicates that any entities which are referred to by exported entities are also exported.

See Also:

Constant Field Values

EXPORT_PORTABLE_ESPKS

static final int EXPORT_PORTABLE_ESPKS

Used with exportContents(), this flag indicates that the ESPK values for the entities are normalized, allowing import into other ES stores. In the majority of cases you'll want to set this.

See Also:

Constant Field Values

EXPORT_REALIZED_TYPES

static final int EXPORT_REALIZED_TYPES

Used with exportContents(), this flag indicates that only types which are instantiated are to be exported. Required the EXPORT_TYPES flag to be set before it is considered.

See Also:

Constant Field Values

IMPORT_DIRECTIVE_OVERRIDE_ALL

static final int IMPORT_DIRECTIVE_OVERRIDE_ALL

Used with exportContents(), this flag indicates that all exported entities should be flagged with the override directive for subsequent import. No other directives should be indicated for specific keys in conjunction with this flag, or an error will be forced.

See Also:

Constant Field Values

EXPORT_SOFT_REF_CLOSURE

static final int EXPORT_SOFT_REF_CLOSURE

Used with exportContents(), this flag indicates that soft references are followed for closure when the reference can be resolved to another entity. Failures to resolve the soft reference are silently ignored. Requires EXPORT_CLOSURE flag to be set before it is considered.

See Also:

Constant Field Values

EXPORT_TRUNKS

static final int EXPORT_TRUNKS

Used with exportContents(), this flag will ensure all entities leading from the export roots back to the main store root get exported too. Note that this behaviour is enabled by default if the EXPORT_CLOSURE flag is set.

See Also:

Constant Field Values

ES_NULL_PK

static final ESPK ES_NULL_PK

A key representing a null reference

Method Detail

getRootPK

ESPK getRootPK()

Get the identifier for the root Entity in the Store. Always returns a valid PK, or throws an IllegalStateException if the underlying provider exists but is not yet initialized.

Returns:

The root Entity identifier

getEntity

Entity getEntity(ESPK pk)
                 throws EntityStoreException

Get a particular Entity from the Store, depending on its key.

Parameters:

pk - The unique identifier for the Entity

Returns:

An Entity

Throws:

EntityStoreException - If the specified Entity doesn't exist

getEntity

Entity getEntity(ESPK pk,
                 java.lang.String[] requiredFieldNames)
                 throws EntityStoreException

Retrieve the subordinate Entities of the identified parent.

Parameters:

pk - The identifier of the Entities you wish to retrieve.

requiredFieldNames - By specifying this, you can limit the amount of data actually retreived by the server.

Throws:

EntityStoreException

addEntity

ESPK addEntity(ESPK parentPK,
               Entity entity)
               throws EntityStoreException

Add an Entity to the Store.

Parameters:

parentPK - The identifier of the candidate parent Entity to this new Entity

entity - The entity you wish to store.

Returns:

The identity of the new entity in the EntityStore. The Entity itself will also be updated with this identifier, so successive calls to Entity.getPK() will return the new identifier

Throws:

DuplicateKeysException - If an entity with the same keys already exists in the store.

EntityStoreException

updateEntity

void updateEntity(Entity entity)
                  throws EntityStoreException

Replace an entity

Parameters:

entity - The candidate entity for replacement. The entity must already have been initialized via a call to getEntity, and its PK will be already set.

Throws:

EntityStoreException

deleteEntity

void deleteEntity(ESPK pk)
                  throws EntityStoreException

Delete an entity from the data store.

Parameters:

pk - Identity of the Entity to be deleted

Throws:

EntityStoreException

listChildren

java.util.Collection<ESPK> listChildren(ESPK pk,
                                        EntityType type)
                                        throws EntityStoreException

List all children of a particular Entity.

Parameters:

pk - The entity id of the parent whose children you wish to list

type - Indicate the type of children you are interested in. "null" indicates that you wish to retrieve children of all types.

Returns:

A Collection of zero or more child ESPKs

Throws:

EntityStoreException

findChildren

java.util.Collection<ESPK> findChildren(ESPK pk,
                                        Field[] fvals,
                                        EntityType ofType)
                                        throws EntityStoreException

Find all children of a particular Entity.

Parameters:

pk - The entity id of the parent whose children you wish to get

fvals - The Fields (including their values) you wish to do the search on. The fields can have their data and/or references set.

ofType - Search only for Entities of the specified type.

Returns:

A Collection of zero or more child ESPKs

Throws:

EntityStoreException - If the pk is invalid.

findReferringEntities

java.util.Collection<ESPK> findReferringEntities(ESPK targetEntityPK)
                                                 throws EntityStoreException

Get a Set of ESPKs which identify all Entities in the store which contain a field or fields which hold a reference to the Entity specified

Parameters:

targetEntityPK - The ESPK of the Entity to which other Entities may refer.

Returns:

A Set of ESPKs of any Entities which hold a reference to the target Entity.

Throws:

EntityStoreException

connect

void connect(java.lang.String url,
             java.util.Properties credentials)
             throws EntityStoreException

Connect to an entity store.

Parameters:

url - The Url of the EntityStore's backend provider.

credentials - A property list of credentials required to connect. Will usually contain a minimum of a username and password, but may contain other implementation specific properties, such as key locations for SSL etc. See the specific implementations of EntityStore for details as to the contents of these properties.

Throws:

EntityStoreException

disconnect

void disconnect()
                throws EntityStoreException

Disconnect from the EntityStore. Releases any resources which may have been associated with the connection.

Throws:

EntityStoreException

initialize

void initialize()
                throws EntityStoreException

Connect to the EntityStore and bootstrap the store with the default components required to implement a store. Any previous data in the store will be wiped.

Throws:

EntityStoreException - if the underlying implementation cannot perform its own initialization and relies on external administrative steps to instantiate the schema components.

importData

java.util.Collection<ESPK> importData(java.io.InputStream stream)
                                      throws EntityStoreException

Import a serialized definition of the Store.

Parameters:

stream - An input stream from which to get the entity/type definitions

Returns:

Collection a list of the newly imported objects.

Throws:

EntityStoreException

exportContents

void exportContents(java.io.OutputStream out,
                    java.util.Collection<ESPK> startNodes,
                    int flags)
                    throws EntityStoreException

Export the contents of the entity store to the specified output stream.

Parameters:

out - The output stream to output to.

startNodes - An array of the ESPKs which indicate the starting points of the branches to export. Null entries and duplicates will be ignored. A null, zero-length array or array with no usable ESPKs will result in no Entity data being exported, but types may still be exported if specified in the flags.

flags - A set of flags to indicate what and how to export.

Throws:

EntityStoreException - if the OutputStream is null.

startTransaction

void startTransaction()
                      throws EntityStoreException

Indicate to the Store that you want to start a transaction.

Throws:

EntityStoreException - if the underlying implementation was unable to start a transaction

commit

void commit()
            throws EntityStoreException

Indicate that you wish to have all operations on the Store since the last startTransaction committed to the Store, and published to the Store's listeners.

Throws:

EntityStoreException - If a transaction hasn't been started, or the underlying implementation was unable to commit.

rollback

void rollback()
              throws EntityStoreException

Indicate that you wish to discard all changes to the Store since the last startTransaction.

Throws:

EntityStoreException - If the underlying implementation was unable to roll back your changes, or a transaction hasn't been started

registerChangeListener

void registerChangeListener(ESPK entityPK,
                            ESChangeListener listener)
                            throws EntityStoreException

Register to listen to changes to the Entities in the Store.

Parameters:

entityPK - The Entity PK on which to listen for events

listener - The listener for EntityStore change events

Throws:

EntityStoreException

deregisterChangeListener

void deregisterChangeListener(ESPK entityPK,
                              ESChangeListener listener)
                              throws EntityStoreException

Deregister from listening to changes to the Entities in the Store.

Parameters:

entityPK - The Entity PK from which we no longer listen to events

listener - The listener for EntityStore change events, as initially registered.

Throws:

EntityStoreException

decodePK

ESPK decodePK(java.lang.String stringifiedPK)
              throws EntityStoreException

Decode a stringified PK as per the implementation. To encode, just use ESPK.toString()

Parameters:

stringifiedPK - The string version of the PK

Returns:

an ESPK as per the particular implementation

Throws:

EntityStoreException