li.strolch.agent.api

Interface ElementMap<T extends StrolchRootElement>

Type Parameters:

T - the object instance being managed

All Known Subinterfaces:

ActivityMap, OrderMap, ResourceMap

All Known Implementing Classes:

AuditingActivityMap, AuditingElementMapFacade, AuditingOrderMap, AuditingResourceMap, CachedActivityMap, CachedElementMap, CachedOrderMap, CachedResourceMap, TransactionalActivityMap, TransactionalElementMap, TransactionalOrderMap, TransactionalResourceMap

public interface ElementMap<T extends StrolchRootElement>

The ElementMap is the entry point to the Strolch model. Any access to Strolch objects is done using the ElementMap. A concrete ElementMap instance uses the given StrolchTransaction to access the a StrolchDao and perform the relevant operation.

Note:

Author:

Robert von Burg

Method Summary

Modifier and Type	Method and Description
void	add(StrolchTransaction tx, T element) Adds the given element to the underlying persistence layer.
void	addAll(StrolchTransaction tx, List<T> elements) Adds the given elements to the underlying persistence layer.
List<T>	getAllElements(StrolchTransaction tx) Returns all elements in the underlying persistence layer regardless of type
Set<String>	getAllKeys(StrolchTransaction tx) Returns all keys/IDs of all elements in the underlying persistence layer, regardless of type
List<T>	getBy(StrolchTransaction tx, StringListParameter refP, boolean assertExists) Returns all elements which are referenced by the given StringListParameter.
T	getBy(StrolchTransaction tx, StringParameter refP, boolean assertExists) Returns the element which is referenced by the given StringParameter.
T	getBy(StrolchTransaction tx, String type, String id) Retrieves the element with the given type and id, or null if it does not exist
T	getBy(StrolchTransaction tx, String type, String id, boolean assertExists) Retrieves the element with the given type and id, or null if it does not exist
T	getBy(StrolchTransaction tx, String type, String id, int version) Retrieves the specific version of the element with the given type and id, or null if it does not exist
T	getBy(StrolchTransaction tx, String type, String id, int version, boolean assertExists) Retrieves the specific version of the element with the given type and id, or null if it does not exist
List<T>	getElementsBy(StrolchTransaction tx, String type) Returns all elements in the underlying persistence layer of the given type
Set<String>	getKeysBy(StrolchTransaction tx, String type) Returns all keys/IDs of all elements in the underlying persistence layer, of the given type
T	getTemplate(StrolchTransaction tx, String type) Returns a copy of the element with the type "Template" and the id = type
T	getTemplate(StrolchTransaction tx, String type, boolean assertExists) Returns a copy of the element with the type "Template" and the id = type
Set<String>	getTypes(StrolchTransaction tx) Returns all the types known in the underlying persistence layer
List<T>	getVersionsFor(StrolchTransaction tx, String type, String id) Queries and returns all the versions of the element with the given type and ID
boolean	hasElement(StrolchTransaction tx, String type, String id) Returns true if the underlying persistence layer has an element with the given type and ID
boolean	hasType(StrolchTransaction tx, String type) Returns true if the underlying persistence layer has elements with the given type
long	querySize(StrolchTransaction tx) Returns the number of elements regardless of type in the underlying persistence layer
long	querySize(StrolchTransaction tx, String type) Returns the number of elements of the given type in the underlying persistence layer
void	remove(StrolchTransaction tx, T element) Removes the given element
long	removeAll(StrolchTransaction tx) Removes all elements regardless of the type
void	removeAll(StrolchTransaction tx, List<T> elements) Removes the given elements
long	removeAllBy(StrolchTransaction tx, String type) Removes all elements of the given type
T	revertToVersion(StrolchTransaction tx, String type, String id, int version) Reverts to the given version of the specified element.
T	revertToVersion(StrolchTransaction tx, T element) Reverts to the given version of the specified element.
void	undoVersion(StrolchTransaction tx, T element) Undoes the given version by reverting to the previous version of the element given.
void	update(StrolchTransaction tx, T element) Updates the existing element
void	updateAll(StrolchTransaction tx, List<T> elements) Updates all the existing elements

Method Detail

hasType

boolean hasType(StrolchTransaction tx,
                String type)

Returns true if the underlying persistence layer has elements with the given type

Parameters:

tx - the open StrolchTransaction

type - the type of element to check for

Returns:

true if the underlying persistence layer has elements with the given type

hasElement

boolean hasElement(StrolchTransaction tx,
                   String type,
                   String id)

Returns true if the underlying persistence layer has an element with the given type and ID

Parameters:

tx - the open StrolchTransaction

type - the type of element to check for

id - the ID of the element to check for

Returns:

true if the underlying persistence layer has an element with the given type and ID

querySize

long querySize(StrolchTransaction tx)

Returns the number of elements regardless of type in the underlying persistence layer

Parameters:

tx - the open StrolchTransaction

Returns:

the number of elements regardless of type in the underlying persistence layer

querySize

long querySize(StrolchTransaction tx,
               String type)

Returns the number of elements of the given type in the underlying persistence layer

Parameters:

tx - the open StrolchTransaction

type - the type of element for which the number of elements is to be queried

Returns:

the number of elements of the given type in the underlying persistence layer

getTemplate

T getTemplate(StrolchTransaction tx,
              String type)

Returns a copy of the element with the type "Template" and the id = type

Parameters:

tx - the open StrolchTransaction

type - The template id to return

Returns:

the template, or null if it does not exist

getTemplate

T getTemplate(StrolchTransaction tx,
              String type,
              boolean assertExists)
       throws StrolchException

Returns a copy of the element with the type "Template" and the id = type

Parameters:

tx - the open StrolchTransaction

type - The template id to return

assertExists - if true, and element does not exist, then a StrolchException is thrown

Returns:

the template, or null if it does not exist

Throws:

StrolchException - if the template does not exist

getBy

T getBy(StrolchTransaction tx,
        String type,
        String id)

Retrieves the element with the given type and id, or null if it does not exist

Parameters:

tx - the open transaction

type - the type of the element to retrieve

id - the id of the element to retrieve

Returns:

the element with the type and id, or null if it does not exist

getBy

T getBy(StrolchTransaction tx,
        String type,
        String id,
        boolean assertExists)
 throws StrolchException

Retrieves the element with the given type and id, or null if it does not exist

Parameters:

tx - the open transaction

type - the type of the element to retrieve

id - the id of the element to retrieve

assertExists - if true, and element does not exist, then a StrolchException is thrown

Returns:

the element with the type and id, or null if it does not exist

Throws:

StrolchException - if the element does not exist

getBy

T getBy(StrolchTransaction tx,
        String type,
        String id,
        int version)

Retrieves the specific version of the element with the given type and id, or null if it does not exist

Parameters:

tx - the open transaction

type - the type of the element to retrieve

id - the id of the element to retrieve

version - the version to get

Returns:

the element with the type and id, or null if it does not exist

getBy

T getBy(StrolchTransaction tx,
        String type,
        String id,
        int version,
        boolean assertExists)
 throws StrolchException

Retrieves the specific version of the element with the given type and id, or null if it does not exist

Parameters:

tx - the open transaction

type - the type of the element to retrieve

id - the id of the element to retrieve

version - the version to get

assertExists - if true, and element does not exist, then a StrolchException is thrown

Returns:

the element with the type and id, or null if it does not exist

Throws:

StrolchException - if the element does not exist

getBy

T getBy(StrolchTransaction tx,
        StringParameter refP,
        boolean assertExists)
 throws StrolchException

Returns the element which is referenced by the given StringParameter. A reference Parameter must have its interpretation set to the element type being referenced e.g. s StrolchConstants.INTERPRETATION_ORDER_REF and the UOM must be set to the element's type and the value is the id of the element

Parameters:

tx - the StrolchTransaction instance

refP - the StringParameter which references an element

assertExists - if true, and element does not exist, then a StrolchException is thrown

Returns:

the element found, or null if it does not exist

Throws:

StrolchException - if the StringParameter is not a properly configured as a reference parameter

getBy

List<T> getBy(StrolchTransaction tx,
              StringListParameter refP,
              boolean assertExists)
       throws StrolchException

Returns all elements which are referenced by the given StringListParameter. A reference Parameter must have its interpretation set to the element type being referenced e.g. s StrolchConstants.INTERPRETATION_ORDER_REF and the UOM must be set to the element's type and the value is the id of the element

Parameters:

tx - the StrolchTransaction instance

refP - the StringListParameter which references an element

assertExists - if true, and element does not exist, then a StrolchException is thrown

Returns:

the list of elements found, or the empty list if they do not exist. Note: Any missing elements are not returned!

Throws:

StrolchException - if the StringParameter is not a properly configured as a reference parameter

getVersionsFor

List<T> getVersionsFor(StrolchTransaction tx,
                       String type,
                       String id)

Queries and returns all the versions of the element with the given type and ID

Parameters:

tx - the StrolchTransaction instance

type - the type of the element to be queried

id - the id of the element to be queried

Returns:

all the versions of the element with the given type and ID

getAllElements

List<T> getAllElements(StrolchTransaction tx)

Returns all elements in the underlying persistence layer regardless of type

Parameters:

tx - the StrolchTransaction instance

Returns:

all elements in the underlying persistence layer regardless of type

getElementsBy

List<T> getElementsBy(StrolchTransaction tx,
                      String type)

Returns all elements in the underlying persistence layer of the given type

Parameters:

tx - the StrolchTransaction instance

type - the type of the elements to retrieve

Returns:

all elements in the underlying persistence layer of the given type

getTypes

Set<String> getTypes(StrolchTransaction tx)

Returns all the types known in the underlying persistence layer

Parameters:

tx - the StrolchTransaction instance

Returns:

all the types known in the underlying persistence layer

getAllKeys

Set<String> getAllKeys(StrolchTransaction tx)

Returns all keys/IDs of all elements in the underlying persistence layer, regardless of type

Parameters:

tx - the StrolchTransaction instance

Returns:

all keys/IDs of all elements in the underlying persistence layer, regardless of type

getKeysBy

Set<String> getKeysBy(StrolchTransaction tx,
                      String type)

Returns all keys/IDs of all elements in the underlying persistence layer, of the given type

Parameters:

tx - the StrolchTransaction instance

type - the type of the element to retrieve the keys for

Returns:

all keys/IDs of all elements in the underlying persistence layer, of the given type

add

void add(StrolchTransaction tx,
         T element)
  throws StrolchPersistenceException

Adds the given element to the underlying persistence layer. The element may not already exist

Parameters:

tx - the StrolchTransaction instance

element - the element to add

Throws:

StrolchPersistenceException - if an element already exists with the same ID

addAll

void addAll(StrolchTransaction tx,
            List<T> elements)
     throws StrolchPersistenceException

Adds the given elements to the underlying persistence layer. None of the elements may already exist

Parameters:

tx - the StrolchTransaction instance

elements - the elements to add

Throws:

StrolchPersistenceException - if an element already exists with the same ID

update

void update(StrolchTransaction tx,
            T element)
     throws StrolchPersistenceException

Updates the existing element

Parameters:

tx - the StrolchTransaction instance

element - the element to update

Throws:

StrolchPersistenceException - if the element does not exist

updateAll

void updateAll(StrolchTransaction tx,
               List<T> elements)
        throws StrolchPersistenceException

Updates all the existing elements

Parameters:

tx - the StrolchTransaction instance

elements - the elements to update

Throws:

StrolchPersistenceException - if any of the elements don't yet exist

remove

void remove(StrolchTransaction tx,
            T element)
     throws StrolchPersistenceException

Removes the given element

Parameters:

tx - the StrolchTransaction instance

element - the element to be removed

Throws:

StrolchPersistenceException - if the element does not exist

removeAll

void removeAll(StrolchTransaction tx,
               List<T> elements)
        throws StrolchPersistenceException

Removes the given elements

Parameters:

tx - the StrolchTransaction instance

elements - the elements to be removed

Throws:

StrolchPersistenceException - if any of the elements don't yet exist

removeAll

long removeAll(StrolchTransaction tx)

Removes all elements regardless of the type

Note: This method ignores versioning. Do NOT call this method unless you want to clear the model!

Parameters:

tx - the StrolchTransaction instance

Returns:

the number of elements removed

removeAllBy

long removeAllBy(StrolchTransaction tx,
                 String type)

Removes all elements of the given type

Note: This method ignores versioning. Do NOT call this method unless you want to clear the model!

Parameters:

tx - the StrolchTransaction instance

type - the type of elements to remove

Returns:

the number of elements removed

undoVersion

void undoVersion(StrolchTransaction tx,
                 T element)
          throws StrolchException

Undoes the given version by reverting to the previous version of the element given. If the element given is the first version, then the element is removed. If the previous version exists, then it is reverted to it. If the given element does not exist, nor it's previous version, then a StrolchPersistenceException is thrown

Note: This method should only be used in the same transaction where the element was created to undo a change in the same transaction. If there is a requirement to revert to a previous version, then the revertToVersion(StrolchTransaction, StrolchRootElement) method.

Parameters:

tx - the StrolchTransaction instance

element - the element which is to be reverted to a previous version

Throws:

StrolchException - if the version does not exist, if this version is not the latest version, if the previous version is missing or other problems arise

revertToVersion

T revertToVersion(StrolchTransaction tx,
                  T element)
           throws StrolchException

Reverts to the given version of the specified element. This method will retrieve the given version of the specified element, then set a new version on that element which is an increment of the current latest version and store this new version. The new element is then returned for convenience.

Note: This is the method which should be called when a change should be reverted. This method gurantees that the history is not changed and that a new version is saved but with the version of the element specified.

Parameters:

tx - the StrolchTransaction instance

element - the version of the element to revert to

Returns:

the new version of the element

Throws:

StrolchException - if the version does not exist

revertToVersion

T revertToVersion(StrolchTransaction tx,
                  String type,
                  String id,
                  int version)
           throws StrolchException

Reverts to the given version of the specified element. This method will retrieve the given version of the specified element, then set a new version on that element which is an increment of the current latest version and store this new version. The new element is then returned for convenience.

Note: This is the method which should be called when a change should be reverted. This method gurantees that the history is not changed and that a new version is saved but with the version of the element specified.

Parameters:

tx - the StrolchTransaction instance

type - the type of the element to revert to

id - the id of the element to revert to

version - the version of the specified element to revert to

Returns:

the new version of the element

Throws:

StrolchException - if the version does not exist