de.aristaflow.adept2.core.activityrepository

Interface IconManager

public interface IconManager

This interface provides the means for managing icons and IconDescriptors which includes retrieval, creation, updating and managing the states of IconDescriptorss. Icon and icon descriptors are identified by an ID which is therefore system-wide unique.
Icons are closely coupled to the corresponding icon descriptor. The latter serves as a lightweight representation of the icon. Versioning is done with the descriptor. Before releasing a descriptor, an icon has to be stored for it.

Icons are provided as byte-arrays. These need to contain a valid image in PNG-format. To avoid scaling problems, each icon can be provided in several dimensions. Each dimension is added separately and identified by the index in the dimension array. The dimension will be implicitly added to the corresponding icon descriptor. Obviously, each dimension can be removed separately.

If the provided icon (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
void	addDevelopmentIcon(SessionToken session, java.util.UUID iconID, byte[] icon, long branch) Adds the designated icon dimension to the designated icon in the designated branch and sets it IN_DEVELOPMENT if not done yet.
byte[]	getDevelopmentIcon(SessionToken session, java.util.UUID iconID, IconDescriptor.Dimension dimension, long branch) Gets the designated dimension of the development version of the designated icon in the designated branch.
ChangeableIconDescriptor	getDevelopmentIconDescriptor(SessionToken session, java.util.UUID iconID, long branch) Gets the development version of the icon descriptors for the designated icon ID in the designated branch.
java.util.Collection<ChangeableIconDescriptor>	getDevelopmentIconDescriptors(SessionToken session, long branch) Gets the development versions of all icon descriptors in the designated branch known by this manager.
RemoteIterator<java.util.List<ChangeableIconDescriptor>>	getDevelopmentIconDescriptorsIterator(SessionToken session, long branch) The same as getDevelopmentIconDescriptors(SessionToken, long) but with partial retrieval of the descriptors.
IconDescriptor	getIconDescriptorRevision(SessionToken session, java.util.UUID iconID, long revision) Gets the designated revision of the designated icon descriptor.
java.util.List<IconDescriptor>	getIconDescriptorRevisions(SessionToken session, java.util.UUID iconID) Gets all revisions of the designated icon descriptor or an empty list in case there are no revisions yet.
RemoteIterator<java.util.List<IconDescriptor>>	getIconDescriptorRevisionsIterator(SessionToken session, java.util.UUID iconID) The same as getIconDescriptorRevisions(SessionToken, UUID) but with partial retrieval of the descriptors.
java.util.Collection<IconDescriptor>	getIconDescriptorsRevision(SessionToken session, long revision) Gets all icon descriptors of the designated revision known by this manager.
RemoteIterator<java.util.List<IconDescriptor>>	getIconDescriptorsRevisionIterator(SessionToken session, long revision) The same as getIconDescriptorsRevision(SessionToken, long) but with partial retrieval of the descriptors.
byte[]	getIconRevision(SessionToken session, java.util.UUID iconID, IconDescriptor.Dimension dimension, long revision) Gets the designated revision and the designated dimension (index of corresponding dimension array) of the designated icon.
byte[]	getLatestIcon(SessionToken session, java.util.UUID iconID, IconDescriptor.Dimension dimension) Gets the (latest revision of the) designated icon (in PNG-format).
IconDescriptor	getLatestIconDescriptor(SessionToken session, java.util.UUID iconID) Gets the latest revision of the designated icon descriptor.
java.util.Collection<IconDescriptor>	getLatestIconDescriptors(SessionToken session, boolean productionOnly) Gets the latest revisions (IN_PRODUCTION and/or OUTDATED) of all icon descriptors known by this manager.
RemoteIterator<java.util.List<IconDescriptor>>	getLatestIconDescriptorsIterator(SessionToken session, boolean productionOnly) The same as getLatestIconDescriptors(SessionToken, boolean) but with partial retrieval of the descriptors.
void	outdateIcon(SessionToken session, java.util.UUID iconID) Outdates the latest revision of the designated icon explicitly which prevents its usage afterwards.
void	removeDevelopmentIcon(SessionToken session, java.util.UUID iconID, IconDescriptor.Dimension dimension, long branch) Removes the designated icon dimension from the designated branch.
void	revertDevelopmentIcon(SessionToken session, java.util.UUID iconID, long branch) Reverts the designated development icon (and its descriptor) in the designated branch that is all changes will be undone and the icon will logically be the same as the base revision of the branch.
CheckReport	simulateUpdateOfDevelopmentIcon(SessionToken session, java.util.UUID iconID, long branch) Simulates updating of the designated icon (and its descriptor) in the designated branch, that is only the designated icon of the branch is checked for whether it can be updated to the latest revision.
void	storeDevelopmentIconDescriptor(SessionToken session, IconDescriptor iconDescriptor, long branch) Stores the designated icon descriptor in the designated branch and sets it IN_DEVELOPMENT if not done yet.

Method Detail

getLatestIconDescriptors

java.util.Collection<IconDescriptor> getLatestIconDescriptors(SessionToken session,
                                                              boolean productionOnly)

Gets the latest revisions (IN_PRODUCTION and/or OUTDATED) of all icon 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 icon descriptors IN_PRODUCTION and/or OUTDATED known by this manager.

getLatestIconDescriptorsIterator

RemoteIterator<java.util.List<IconDescriptor>> getLatestIconDescriptorsIterator(SessionToken session,
                                                                                boolean productionOnly)

The same as getLatestIconDescriptors(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 icon descriptors IN_PRODUCTION and/or OUTDATED known by this manager as iterator.

getLatestIconDescriptor

IconDescriptor getLatestIconDescriptor(SessionToken session,
                                       java.util.UUID iconID)

Gets the latest revision of the designated icon descriptor.

Parameters:

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

iconID - The ID of the icon descriptor of which to retrieve the latest revision.

Returns:

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

Throws:

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

getLatestIcon

byte[] getLatestIcon(SessionToken session,
                     java.util.UUID iconID,
                     IconDescriptor.Dimension dimension)

Gets the (latest revision of the) designated icon (in PNG-format). The returned icon will be the one with the biggest dimension available.

Parameters:

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

iconID - The ID of the icon of which to retrieve the latest revision.

dimension - The dimension of the icon which to retrieve.

Returns:

The latest revision of the icon (in PNG-format) having the designated ID.

Throws:

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

getIconDescriptorsRevision

java.util.Collection<IconDescriptor> getIconDescriptorsRevision(SessionToken session,
                                                                long revision)

Gets all icon 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 icon descriptors known by this manager.

Returns:

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

getIconDescriptorsRevisionIterator

RemoteIterator<java.util.List<IconDescriptor>> getIconDescriptorsRevisionIterator(SessionToken session,
                                                                                  long revision)

The same as getIconDescriptorsRevision(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 icon descriptors known by this manager.

Returns:

All icon descriptors of the designated revision known by this manager as iterator.

getIconDescriptorRevisions

java.util.List<IconDescriptor> getIconDescriptorRevisions(SessionToken session,
                                                          java.util.UUID iconID)

Gets all revisions of the designated icon 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.

iconID - The ID of the icon descriptor of which to retrieve all revisions.

Returns:

All revisions of the icon descriptor having the designated ID.

Throws:

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

getIconDescriptorRevisionsIterator

RemoteIterator<java.util.List<IconDescriptor>> getIconDescriptorRevisionsIterator(SessionToken session,
                                                                                  java.util.UUID iconID)

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

Parameters:

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

iconID - The ID of the icon descriptor of which to retrieve all revisions as iterator.

Returns:

All revisions of the icon descriptor having the designated ID.

Throws:

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

getIconDescriptorRevision

IconDescriptor getIconDescriptorRevision(SessionToken session,
                                         java.util.UUID iconID,
                                         long revision)

Gets the designated revision of the designated icon descriptor.

Parameters:

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

iconID - The ID of the icon descriptor of which to retrieve a specific revision.

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

Returns:

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

Throws:

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

getIconRevision

byte[] getIconRevision(SessionToken session,
                       java.util.UUID iconID,
                       IconDescriptor.Dimension dimension,
                       long revision)

Gets the designated revision and the designated dimension (index of corresponding dimension array) of the designated icon.

Parameters:

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

iconID - The ID of the icon of which to retrieve a specific revision and dimension.

dimension - The dimension of the icon which to retrieve.

revision - The revision of the icon which to retrieve.

Returns:

The designated revision and dimension of the designated icon.

Throws:

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

getDevelopmentIconDescriptors

java.util.Collection<ChangeableIconDescriptor> getDevelopmentIconDescriptors(SessionToken session,
                                                                             long branch)

Gets the development versions of all icon 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 icon descriptors.

Returns:

The development versions of all icon 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.

getDevelopmentIconDescriptorsIterator

RemoteIterator<java.util.List<ChangeableIconDescriptor>> getDevelopmentIconDescriptorsIterator(SessionToken session,
                                                                                               long branch)

The same as getDevelopmentIconDescriptors(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 icon descriptors.

Returns:

The development versions of all icon 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.

getDevelopmentIconDescriptor

ChangeableIconDescriptor getDevelopmentIconDescriptor(SessionToken session,
                                                      java.util.UUID iconID,
                                                      long branch)

Gets the development version of the icon descriptors for the designated icon ID in the designated branch. The development version stems from the base revision of the designated branch, that is, an unchanged icon (descriptor) is a copy of the corresponding base revision while a changed icon (descriptor) is modified with respect to the base revision. Therefore the returned icon (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.

iconID - The ID of the icon of which to retrieve the development version of the icon descriptor of the designated branch.

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

Returns:

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

Throws:

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

getDevelopmentIcon

byte[] getDevelopmentIcon(SessionToken session,
                          java.util.UUID iconID,
                          IconDescriptor.Dimension dimension,
                          long branch)

Gets the designated dimension of the development version of the designated icon 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 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 its descriptor is stored or a dimension is added or removed the first time.

Parameters:

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

iconID - The ID of the icon of which to retrieve the development version of the designated branch.

dimension - The dimension of the icon which to retrieve.

branch - The branch of which to retrieve the corresponding icon (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 and dimension of the icon in the designated branch.

Throws:

UnknownEntityException - If the designated icon or the designated dimension does not exist or the designated branch is currently unused, an UnknownEntityException will be thrown.

storeDevelopmentIconDescriptor

void storeDevelopmentIconDescriptor(SessionToken session,
                                    IconDescriptor iconDescriptor,
                                    long branch)

Stores the designated icon 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 icon 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 icon descriptor just set its primary key to a non-existing one and store it. If the key exists, the icon 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.

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

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

Throws:

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

addDevelopmentIcon

void addDevelopmentIcon(SessionToken session,
                        java.util.UUID iconID,
                        byte[] icon,
                        long branch)

Adds the designated icon dimension to the designated icon 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 icon 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.
Since the icon does not have additional information, there will be no consistency checks when storing; the caller has to ensure consistency between an added icon and its icon descriptor. You may have to store a new icon descriptor before storing the icon itself.
When adding a new dimension, the icon description will be automatically updated, that is the dimension will be added. The width and height are determined by the designated byte representation.

Parameters:

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

iconID - The ID of the icon to which to add the designated dimension to the development version in the designated branch.

icon - The icon in a specific dimension to be added to the designated branch.

branch - The branch in which to add the new icon dimension.

Throws:

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

removeDevelopmentIcon

void removeDevelopmentIcon(SessionToken session,
                           java.util.UUID iconID,
                           IconDescriptor.Dimension dimension,
                           long branch)

Removes the designated icon dimension from the designated branch. The icon description will be automatically updated, that is the dimension will be removed and all following dimensions will be re-indexed.

Parameters:

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

iconID - The ID of the icon of which to remove the designated dimension from the development version in the designated branch.

dimension - The dimension of the icon which to remove.

branch - The branch from which to remove the designated icon dimension.

Throws:

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

revertDevelopmentIcon

void revertDevelopmentIcon(SessionToken session,
                           java.util.UUID iconID,
                           long branch)

Reverts the designated development icon (and its descriptor) in the designated branch that is all changes will be undone and the icon 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.

iconID - The ID of the icon of which to delete the development version in the designated branch.

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

Throws:

UnknownEntityException - If the designated icon 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.

simulateUpdateOfDevelopmentIcon

CheckReport simulateUpdateOfDevelopmentIcon(SessionToken session,
                                            java.util.UUID iconID,
                                            long branch)

Simulates updating of the designated icon (and its descriptor) in the designated branch, that is only the designated icon 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 icon instead of checking the whole branch will provide a much simpler way to resolve these conflicts.
When checking an icon 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.

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

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

Returns:

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

Throws:

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

outdateIcon

void outdateIcon(SessionToken session,
                 java.util.UUID iconID)

Outdates the latest revision of the designated icon 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 icon has to be checked. The latest revision may be used for a development version which in turn may be released later.
Outdating an OUTDATED icon 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.

iconID - The ID of the icon of which to explicitly outdate the latest revision.

Throws:

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