de.aristaflow.adept2.core.activityrepository

Interface ResourceManager

public interface ResourceManager

This interface provides the means for managing (binary) resources and ResourceDescriptors which includes retrieval, creation, updating and managing the states of ResourceDescriptorss. Resources and resource descriptors are identified by an ID which is therefore system-wide unique.
Resources are closely coupled to the corresponding resource descriptors. The latter serves as a lightweight representation of the resource. Versioning is done with the descriptor.

If the provided resource (or its identifying attributes) of a method does not exist, an UnknownEntityException will be thrown.

Author:

Ulrich Kreher

Method Summary

Modifier and Type	Method and Description
byte[]	getDevelopmentResource(SessionToken session, java.util.UUID resourceID, long branch) Gets the development version of the designated resource in the designated branch.
ChangeableResourceDescriptor	getDevelopmentResourceDescriptor(SessionToken session, java.util.UUID resourceID, long branch) Gets the development version of the resource descriptors for the designated resource ID in the designated branch.
java.util.Collection<ChangeableResourceDescriptor>	getDevelopmentResourceDescriptors(SessionToken session, long branch) Gets the development versions of all resource descriptors in the designated branch known by this manager.
RemoteIterator<java.util.List<ChangeableResourceDescriptor>>	getDevelopmentResourceDescriptorsIterator(SessionToken session, long branch) The same as getDevelopmentResourceDescriptors(SessionToken, long) but with partial retrieval of the descriptors.
byte[]	getLatestResource(SessionToken session, java.util.UUID resourceID) Gets the (latest revision of the) designated resource.
ResourceDescriptor	getLatestResourceDescriptor(SessionToken session, java.util.UUID resourceID) Gets the latest revision of the designated resource descriptor.
java.util.Collection<ResourceDescriptor>	getLatestResourceDescriptors(SessionToken session, boolean productionOnly) Gets the latest revisions (IN_PRODUCTION and/or OUTDATED) of all resource descriptors known by this manager.
RemoteIterator<java.util.List<ResourceDescriptor>>	getLatestResourceDescriptorsIterator(SessionToken session, boolean productionOnly) The same as getLatestResourceDescriptors(SessionToken, boolean) but with partial retrieval of the descriptors.
ServerStream	getLatestResourceIncrementally(SessionToken session, java.util.UUID resourceID) Gets the (latest revision of the) designated resource as ServerStream.
ResourceDescriptor	getResourceDescriptorRevision(SessionToken session, java.util.UUID resourceID, long revision) Gets the designated revision of the designated resource descriptor.
java.util.List<ResourceDescriptor>	getResourceDescriptorRevisions(SessionToken session, java.util.UUID resourceID) Gets all revisions of the designated resource descriptor or an empty list in case there are no revisions yet.
RemoteIterator<java.util.List<ResourceDescriptor>>	getResourceDescriptorRevisionsIterator(SessionToken session, java.util.UUID resourceID) The same getResourceDescriptorRevisions(SessionToken, UUID) but with partial retrieval of the descriptors.
java.util.Collection<ResourceDescriptor>	getResourceDescriptorsRevision(SessionToken session, long revision) Gets all resource descriptors of the designated revision known by this manager.
RemoteIterator<java.util.List<ResourceDescriptor>>	getResourceDescriptorsRevisionIterator(SessionToken session, long revision) The same as getResourceDescriptorsRevision(SessionToken, long) but with partial retrieval of the descriptors.
byte[]	getResourceRevision(SessionToken session, java.util.UUID resourceID, long revision) Gets the designated revision of the designated resource.
ServerStream	getResourceRevisionIncrementally(SessionToken session, java.util.UUID resourceID, long revision) Gets the designated revision of the designated resource as ServerStream.
void	outdateResource(SessionToken session, java.util.UUID resourceID) Outdates the latest revision of the designated resource explicitly which prevents its usage afterwards.
void	revertDevelopmentResource(SessionToken session, java.util.UUID resourceID, long branch) Reverts the designated development resource (and its descriptor) in the designated branch that is all changes will be undone and the resource will logically be the same as the base revision of the branch.
CheckReport	simulateUpdateOfDevelopmentResource(SessionToken session, java.util.UUID resourceID, long branch) Simulates updating of the designated resource (and its descriptor) in the designated branch, that is only the designated resource of the branch is checked for whether it can be updated to the latest revision.
void	storeDevelopmentResourceDescriptor(SessionToken session, ResourceDescriptor resourceDescriptor, byte[] resource, long branch) Stores the designated resource descriptor in the designated branch and sets it IN_DEVELOPMENT if not done yet.

Method Detail

getLatestResourceDescriptors

java.util.Collection<ResourceDescriptor> getLatestResourceDescriptors(SessionToken session,
                                                                      boolean productionOnly)

Gets the latest revisions (IN_PRODUCTION and/or OUTDATED) of all resource descriptors known by this manager.

Parameters:

session - The session which is used to check for access rights on this method.

productionOnly - Whether only the revisions IN_PRODUCTCION should be retrieved.

Returns:

The latest revisions of all resource descriptors IN_PRODUCTION and/or OUTDATED known by this manager.

getLatestResourceDescriptorsIterator

RemoteIterator<java.util.List<ResourceDescriptor>> getLatestResourceDescriptorsIterator(SessionToken session,
                                                                                        boolean productionOnly)

The same as getLatestResourceDescriptors(SessionToken, boolean) but with partial retrieval of the descriptors.

Parameters:

session - The session which is used to check for access rights on this method.

productionOnly - Whether only the revisions IN_PRODUCTCION should be retrieved.

Returns:

The latest revisions of all resource descriptors IN_PRODUCTION and/or OUTDATED known by this manager as iterator.

getLatestResourceDescriptor

ResourceDescriptor getLatestResourceDescriptor(SessionToken session,
                                               java.util.UUID resourceID)

Gets the latest revision of the designated resource descriptor.

Parameters:

session - The session which is used to check for access rights on this method.

resourceID - The ID of the resource descriptor of which to retrieve the latest revision.

Returns:

The latest revision of the resource descriptor having the designated ID.

Throws:

UnknownEntityException - If the designated resource does not exist, an UnknownEntityException will be thrown.

getLatestResource

byte[] getLatestResource(SessionToken session,
                         java.util.UUID resourceID)

Gets the (latest revision of the) designated resource.

Parameters:

session - The session which is used to check for access rights on this method.

resourceID - The ID of the resource of which to retrieve the latest revision.

Returns:

The latest revision of the resource having the designated ID.

Throws:

UnknownEntityException - If the designated resource does not exist, an UnknownEntityException will be thrown.

getLatestResourceIncrementally

ServerStream getLatestResourceIncrementally(SessionToken session,
                                            java.util.UUID resourceID)

Gets the (latest revision of the) designated resource as ServerStream. The server input stream does not provide the complete content of the underlying resource but a proxy object requesting the content incrementally when transfered via the communication.

Parameters:

session - The session which is used to check for access rights on this method.

resourceID - The ID of the resource of which to retrieve the latest revision.

Returns:

The latest revision of the resource having the designated ID as ServerStream, that is, clients do not retrieve all of the content of the stream at once but incrementally.

Throws:

UnknownEntityException - If the designated resource does not exist, an UnknownEntityException will be thrown.

getResourceDescriptorsRevision

java.util.Collection<ResourceDescriptor> getResourceDescriptorsRevision(SessionToken session,
                                                                        long revision)

Gets all resource descriptors of the designated revision known by this manager. These are either IN_PRODUCTION or OUTDATED depending on whether they have been changed or set to outdated from the designated to the latest revision.

Parameters:

session - The session which is used to check for access rights on this method.

revision - The revision of which to retrieve all resource descriptors known by this manager.

Returns:

All resource descriptors of the designated revision known by this manager.

getResourceDescriptorsRevisionIterator

RemoteIterator<java.util.List<ResourceDescriptor>> getResourceDescriptorsRevisionIterator(SessionToken session,
                                                                                          long revision)

The same as getResourceDescriptorsRevision(SessionToken, long) but with partial retrieval of the descriptors.

Parameters:

session - The session which is used to check for access rights on this method.

revision - The revision of which to retrieve all resource descriptors known by this manager as iterator.

Returns:

All resource descriptors of the designated revision known by this manager.

getResourceDescriptorRevisions

java.util.List<ResourceDescriptor> getResourceDescriptorRevisions(SessionToken session,
                                                                  java.util.UUID resourceID)

Gets all revisions of the designated resource descriptor or an empty list in case there are no revisions yet.

Parameters:

session - The session which is used to check for access rights on this method.

resourceID - The ID of the resource descriptor of which to retrieve all revisions.

Returns:

All revisions of the resource descriptor having the designated ID.

Throws:

UnknownEntityException - If the designated resource ID does not exist, an UnknownEntityException will be thrown.

getResourceDescriptorRevisionsIterator

RemoteIterator<java.util.List<ResourceDescriptor>> getResourceDescriptorRevisionsIterator(SessionToken session,
                                                                                          java.util.UUID resourceID)

The same getResourceDescriptorRevisions(SessionToken, UUID) but with partial retrieval of the descriptors.

Parameters:

session - The session which is used to check for access rights on this method.

resourceID - The ID of the resource descriptor of which to retrieve all revisions.

Returns:

All revisions of the resource descriptor having the designated ID as iterator.

Throws:

UnknownEntityException - If the designated resource ID does not exist, an UnknownEntityException will be thrown.

getResourceDescriptorRevision

ResourceDescriptor getResourceDescriptorRevision(SessionToken session,
                                                 java.util.UUID resourceID,
                                                 long revision)

Gets the designated revision of the designated resource descriptor.

Parameters:

session - The session which is used to check for access rights on this method.

resourceID - The ID of the resource descriptor of which to retrieve a specific revision.

revision - The revision of the resource descriptor which to retrieve.

Returns:

The designated revision of the resource descriptor having the designated ID.

Throws:

UnknownEntityException - If the designated resource ID or the revision does not exist, an UnknownEntityException will be thrown.

getResourceRevision

byte[] getResourceRevision(SessionToken session,
                           java.util.UUID resourceID,
                           long revision)

Gets the designated revision of the designated resource.

Parameters:

session - The session which is used to check for access rights on this method.

resourceID - The ID of the resource of which to retrieve a specific revision.

revision - The revision of the resource which to retrieve.

Returns:

The designated revision of the designated resource.

Throws:

UnknownEntityException - If the designated resource ID or the revision does not exist, an UnknownEntityException will be thrown.

getResourceRevisionIncrementally

ServerStream getResourceRevisionIncrementally(SessionToken session,
                                              java.util.UUID resourceID,
                                              long revision)

Gets the designated revision of the designated resource as ServerStream. The server input stream does not provide the complete content of the underlying resource but a proxy object requesting the content incrementally when transfered via the communication.

Parameters:

session - The session which is used to check for access rights on this method.

resourceID - The ID of the resource of which to retrieve a specific revision.

revision - The revision of the resource which to retrieve.

Returns:

The designated revision of the designated resource as ServerStream, that is, clients do not retrieve all of the content of the stream at once but incrementally.

Throws:

UnknownEntityException - If the designated resource ID or the revision does not exist, an UnknownEntityException will be thrown.

getDevelopmentResourceDescriptors

java.util.Collection<ChangeableResourceDescriptor> getDevelopmentResourceDescriptors(SessionToken session,
                                                                                     long branch)

Gets the development versions of all resource descriptors in the designated branch known by this manager. The development versions stem from the base revision of the designated branch, that is, unchanged entities are copies of the corresponding base revisions while changed entities are modified with respect to the base revision. Therefore the returned (referenced) entities may be IN_DEVELOPMENT (changed entities), IN_PRODUCTION (unchanged entities whereas the base revision is the latest revision) or OUTDATED (unchanged entities).

Parameters:

session - The session which is used to check for access rights on this method.

branch - The branch of which to retrieve all resource descriptors.

Returns:

The development versions of all resource descriptors in the designated branch (changed or unchanged entities) known by this manager.

Throws:

UnknownEntityException - If the designated branch is currently unused, an UnknownEntityException will be thrown.

getDevelopmentResourceDescriptorsIterator

RemoteIterator<java.util.List<ChangeableResourceDescriptor>> getDevelopmentResourceDescriptorsIterator(SessionToken session,
                                                                                                       long branch)

The same as getDevelopmentResourceDescriptors(SessionToken, long) but with partial retrieval of the descriptors.

Parameters:

session - The session which is used to check for access rights on this method.

branch - The branch of which to retrieve all resource descriptors.

Returns:

The development versions of all resource descriptors in the designated branch (changed or unchanged entities) known by this manager as iterator.

Throws:

UnknownEntityException - If the designated branch is currently unused, an UnknownEntityException will be thrown.

getDevelopmentResourceDescriptor

ChangeableResourceDescriptor getDevelopmentResourceDescriptor(SessionToken session,
                                                              java.util.UUID resourceID,
                                                              long branch)

Gets the development version of the resource descriptors for the designated resource ID in the designated branch. The development version stems from the base revision of the designated branch, that is, an unchanged resource (descriptor) is a copy of the corresponding base revision while a changed resource (descriptor) is modified with respect to the base revision. Therefore the returned resource (descriptor) may be IN_DEVELOPMENT (changed), IN_PRODUCTION (unchanged whereas the base revision is the latest revision) or OUTDATED (unchanged).

Parameters:

session - The session which is used to check for access rights on this method.

resourceID - The ID of the resource of which to retrieve the development version of the resource descriptor of the designated branch.

branch - The branch of which to retrieve the resource descriptor of the designated icon ID.

Returns:

The development version of the designated resource descriptor in the designated branch (changed or unchanged).

Throws:

UnknownEntityException - If the designated branch is currently unused or the designated resource ID is unknown, an UnknownEntityException will be thrown.

getDevelopmentResource

byte[] getDevelopmentResource(SessionToken session,
                              java.util.UUID resourceID,
                              long branch)

Gets the development version of the designated resource in the designated branch. The returned entity will be IN_DEVELOPMENT if it has already been changed with respect to its base revision. Otherwise the entity will be a copy of the base revision of the branch and therefore IN_PRODUCTION (in case the base revision is the latest revision) or OUTDATED (in case the base revision is already outdated). This copy will be set IN_DEVELOPMENT as soon as the resource stored the first time.

Parameters:

session - The session which is used to check for access rights on this method.

resourceID - The ID of the resource of which to retrieve the development version of the designated branch.

branch - The branch of which to retrieve the corresponding resource (or a new copy of the corresponding base revision entity in case it has not been changed before in this branch).

Returns:

The development version of the resource in the designated branch.

Throws:

UnknownEntityException - If the designated resource ID or the designated branch does not exist, an UnknownEntityException will be thrown.

storeDevelopmentResourceDescriptor

void storeDevelopmentResourceDescriptor(SessionToken session,
                                        ResourceDescriptor resourceDescriptor,
                                        byte[] resource,
                                        long branch)

Stores the designated resource descriptor in the designated branch and sets it IN_DEVELOPMENT if not done yet. All changes are therefore persisted. The branch is usually the same as specified when retrieving the resource for development. However, it can be changed but the content of the target branch will be overwritten. This can be used to copy changes between branches.
To store a new resource just set its primary key to a non-existing one and store it. If the key exists, the resource descriptor will be updated instead of added!

Parameters:

session - The session which is used to check for access rights on this method and to identify the storing agent and the corresponding organisational position.

resourceDescriptor - The resource descriptor providing the new attributes to be set. Resource descriptors are identified by their ID, therefore the ID will not be able to be changed if there is at least one production revision.

resource - The (binary) resource to be stored to the designated branch. If null, only the descriptor will be updated.

branch - The branch in which to store the corresponding resource descriptor.

Throws:

UnknownEntityException - If the designated branch is currently unused, an UnknownEntityException will be thrown.

revertDevelopmentResource

void revertDevelopmentResource(SessionToken session,
                               java.util.UUID resourceID,
                               long branch)

Reverts the designated development resource (and its descriptor) in the designated branch that is all changes will be undone and the resource will logically be the same as the base revision of the branch.

Parameters:

session - The session which is used to check for access rights on this method.

resourceID - The ID of the resource of which to delete the development version in the designated branch.

branch - The branch in which to revert the designated resource and therefore undoing made changes.

Throws:

UnknownEntityException - If the designated resource does not exist in the designated branch or does not exist at all or the designated branch is currently unused, an UnknownEntityException will be thrown.

simulateUpdateOfDevelopmentResource

CheckReport simulateUpdateOfDevelopmentResource(SessionToken session,
                                                java.util.UUID resourceID,
                                                long branch)

Simulates updating of the designated resource (and its descriptor) in the designated branch, that is only the designated resource of the branch is checked for whether it can be updated to the latest revision. The returned check report therefore contains all conflicts due to versioning. These occur for concurrent changes in the designated branch and changing the latest revision (by releasing a new one). If conflicts occur, checking only for one resource instead of checking the whole branch will provide a much simpler way to resolve these conflicts.
When checking a resource that does not have any changes in the designated branch, the check report will contain no entries, indicating that there will be no problems when updating.

Parameters:

session - The session which is used to check for access rights on this method.

resourceID - The ID of the resource which to check for versioning conflicts due to updating to the latest revision.

branch - The branch in which to check the designated resource for versioning conflicts when updating.

Returns:

A check report providing information on versioning on the designated resource only.

Throws:

UnknownEntityException - If the designated resource does not exist in the designated branch or does not exist at all, an UnknownEntityException will be thrown.

outdateResource

void outdateResource(SessionToken session,
                     java.util.UUID resourceID)

Outdates the latest revision of the designated resource explicitly which prevents its usage afterwards. This state will indirectly outdate using entities (executable component descriptions, operations and activity template definitions). However, their state will not be changed explicitly, rather before using them the states of their used resource has to be checked. The latest revision may be used for a development version which in turn may be released later.
Outdating an OUTDATED resource will be ignored.

Parameters:

session - The session which is used to check for access rights on this method and to identify the outdating agent and the corresponding organisational position.

resourceID - The ID of the resource of which to explicitly outdate the latest revision.

Throws:

UnknownEntityException - If the designated resource does not exist, an UnknownEntityException will be thrown.