com.flexive.shared.interfaces
Interface BriefcaseEngine

All Known Subinterfaces:
BriefcaseEngineLocal

public interface BriefcaseEngine

Bean handling Briefcases.

A briefcase is a object store which may be accessed with FxSQL or the API provided by this bean.

Author:
Gregor Schober (gregor.schober@flexive.com), UCS - unique computing solutions gmbh (http://www.ucs.at), Daniel Lichtenberger (daniel.lichtenberger@flexive.com), UCS - unique computing solutions gmbh (http://www.ucs.at)

Method Summary
 void addItemData(long briefcaseId, BriefcaseItemData itemData)
          Add a single item data for a briefcase item
 void addItemData(long briefcaseId, java.util.List<BriefcaseItemData> itemDatas)
          Add multiple item datas for a briefcase
 void addItems(long id, java.util.Collection<FxPK> contents)
          Add the given items to the briefcase.
 void clear(long id)
          Removes all items of the given briefcase.
 long create(java.lang.String name, java.lang.String description, java.lang.Long aclId)
          Creates a new empty briefcase.
 long create(java.lang.String name, java.lang.String description, java.lang.Long aclId, LifeCycleInfo forcedLifeCycleInfo)
          Create a new empty briefcase, overriding the default lifecycle info (e.g.
 long[] getItems(long id)
          Load all item IDs stored in the given briefcase.
 java.util.List<FxReferenceMetaData<FxPK>> getMetaData(long briefcaseId)
          Loads the metadata instance(s) associated to the briefcase items.
 FxReferenceMetaData<FxPK> getMetaData(long briefcaseId, FxPK pk)
          Loads the metadata instance(s) associated to given briefcase item.
 Briefcase load(long id)
          Loads the briefcase with the given id.
 java.util.List<Briefcase> loadAll(boolean includeShared)
          Gets a list of all briefcase for the calling user.
 void mergeMetaData(long id, java.util.Collection<FxReferenceMetaData<FxPK>> metaData)
          Merges the given metadata fields into the existing metadata stored in the items.
 void modify(long id, java.lang.String name, java.lang.String description, java.lang.Long aclId)
          Modifies a briefcase.
 void moveItems(long fromId, long toId, java.util.Collection<FxPK> contents)
          Moves items from one briefcase to another.
 java.util.List<BriefcaseItemData> queryItemData(long briefcaseId, java.lang.Long itemId, java.lang.String metaData, java.lang.Integer intFlag1, java.lang.Integer intFlag2, java.lang.Integer intFlag3, java.lang.Long longFlag1, java.lang.Long longFlag2, BriefcaseItemData.SortField sortField, BriefcaseItemData.SortOrder sortOrder)
          Load matching item datas (non-null flags are queried)
 int queryItemDataCount(long briefcaseId, java.lang.Long itemId, java.lang.String metaData, java.lang.Integer intFlag1, java.lang.Integer intFlag2, java.lang.Integer intFlag3, java.lang.Long longFlag1, java.lang.Long longFlag2)
          Evaluate the count of matching item datas (non-null flags are queried)
 void remove(long id)
          Removes the briefcase with the specified id.
 void removeItemData(long briefcaseId, java.lang.Long itemId)
          Remove item datas
 void removeItems(long id, java.util.Collection<FxPK> contents)
          Removes the given items from the briefcase.
 void setItems(long id, java.util.Collection<FxPK> contents)
          Replace the current briefcase content with the given objects (i.e.
 void setMetaData(long id, java.util.Collection<FxReferenceMetaData<FxPK>> metaData)
          Replaces the current metadata for the given items.
 void updateItemData(long briefcaseId, BriefcaseItemData updateData)
          Update a data item (except the position).
 void updateItems(long id, java.util.Collection<FxPK> addContents, java.util.Collection<FxPK> removeContents)
          Adds/removes the given items for the briefcase.
 

Method Detail

create

long create(java.lang.String name,
            java.lang.String description,
            java.lang.Long aclId)
            throws FxApplicationException
Creates a new empty briefcase.

Parameters:
name - the name of the briefcase.
description - the description (may be empty)
aclId - the ACL to use if the briefcase should be shared, or null if the briefcase is only visible for the owner.
Returns:
the unique briefcase id
Throws:
FxApplicationException - if the create failed

create

long create(java.lang.String name,
            java.lang.String description,
            java.lang.Long aclId,
            LifeCycleInfo forcedLifeCycleInfo)
            throws FxApplicationException
Create a new empty briefcase, overriding the default lifecycle info (e.g. for imports). The lifecycle info may only be specified when the calling user is a global supervisor.

Parameters:
description - the description (may be empty)
aclId - the ACL to use if the briefcase should be shared, or null if the briefcase is only visible for the owner.
forcedLifeCycleInfo - the lifecycle info to store for the briefcase, or null if the default values should be used
Returns:
the unique briefcase id
Throws:
FxApplicationException - if the create failed
Since:
3.2.0

loadAll

java.util.List<Briefcase> loadAll(boolean includeShared)
                                  throws FxApplicationException
Gets a list of all briefcase for the calling user.

Parameters:
includeShared - if enabled shared briefcases will be included, if disabled only the briefcases created by the calling user will be returned
Returns:
the briefcases
Throws:
FxApplicationException - if the function fails

load

Briefcase load(long id)
               throws FxApplicationException
Loads the briefcase with the given id.

Parameters:
id - the id
Returns:
the briefcase
Throws:
FxApplicationException - if a error occured
FxNotFoundException - if it could not be found or was not readable by the calling user.

remove

void remove(long id)
            throws FxApplicationException
Removes the briefcase with the specified id.

The calling user may remove a briefcase if he is the owner, or if he has ben granted the remove permission via the briefcases ACL.
A global supervisor may remove and briefcase.
A mandator supervisor may remove all briefcases that belong to his domain.

Parameters:
id - the id
Throws:
FxApplicationException - if the calling user lacks the remove permission and is not the owner, or if a other error occured.

modify

void modify(long id,
            java.lang.String name,
            java.lang.String description,
            java.lang.Long aclId)
            throws FxApplicationException
Modifies a briefcase.

Parameters:
name - the new name of the briefcase, or null to keep the old value
description - the new description, or null to keep the old value
aclId - the new ACL, or -1 to remove a old acl, or null to keep the old value
id - the id of the briefcase to modify
Throws:
FxApplicationException - if the modify operation failed

clear

void clear(long id)
           throws FxApplicationException
Removes all items of the given briefcase.

Parameters:
id - the briefcase ID
Throws:
FxApplicationException - if the briefcase could not be cleared

addItems

void addItems(long id,
              java.util.Collection<FxPK> contents)
              throws FxApplicationException
Add the given items to the briefcase.

Parameters:
id - the briefcase ID
contents - the content instances to be added
Throws:
FxApplicationException - if the items could not be added
Since:
3.1

setItems

void setItems(long id,
              java.util.Collection<FxPK> contents)
              throws FxApplicationException
Replace the current briefcase content with the given objects (i.e. clear the briefcase, then add the given objects).

Parameters:
id - the briefcase ID
contents - the new briefcase content
Throws:
FxApplicationException - if the content could not be replaced
Since:
3.1

updateItems

void updateItems(long id,
                 java.util.Collection<FxPK> addContents,
                 java.util.Collection<FxPK> removeContents)
                 throws FxApplicationException
Adds/removes the given items for the briefcase.

Parameters:
id - the briefcase ID
addContents - items to be added
removeContents - items to be removed
Throws:
FxApplicationException - if the briefcase could not be updated
Since:
3.1

setMetaData

void setMetaData(long id,
                 java.util.Collection<FxReferenceMetaData<FxPK>> metaData)
                 throws FxApplicationException
Replaces the current metadata for the given items.

Since metadata on a briefcase is typically shared by more than one application (or plugin), this method should be used carefully. For everyday purposes, mergeMetaData(long, java.util.Collection) is considered to be a better alternative.

Parameters:
id - the briefcase ID
metaData - the metadata updates (item IDs are stored in the metadata instances themselves)
Throws:
FxApplicationException - if the metadata could not be updated
Since:
3.1

mergeMetaData

void mergeMetaData(long id,
                   java.util.Collection<FxReferenceMetaData<FxPK>> metaData)
                   throws FxApplicationException
Merges the given metadata fields into the existing metadata stored in the items. Existing values get overwritten. To remove a value, specify its key with a null or empty string.

This method should be used whenever it is not necessary to control the entire metadata associated to a briefcase item, since it provides transactional safety for concurrent modifications of briefcase items.

Parameters:
id - the briefcase ID
metaData - the metadata updates (item IDs are stored in the metadata instances themselves)
Throws:
FxApplicationException - if the metadata could not be updated
Since:
3.1

getMetaData

java.util.List<FxReferenceMetaData<FxPK>> getMetaData(long briefcaseId)
                                                      throws FxApplicationException
Loads the metadata instance(s) associated to the briefcase items. If an item has no metadata stored, it is not returned by this method.

Parameters:
briefcaseId - the briefcase ID
Returns:
the metadata instances
Throws:
FxApplicationException - if the metadata could not be retrieved
Since:
3.1

getMetaData

FxReferenceMetaData<FxPK> getMetaData(long briefcaseId,
                                      FxPK pk)
                                      throws FxApplicationException
Loads the metadata instance(s) associated to given briefcase item. If an item has no metadata stored, or no item with the given ID was found, null is returned.

Parameters:
briefcaseId - the briefcase ID
pk - the item PK
Returns:
the metadata instances
Throws:
FxApplicationException - if the metadata could not be retrieved
Since:
3.1

removeItems

void removeItems(long id,
                 java.util.Collection<FxPK> contents)
                 throws FxApplicationException
Removes the given items from the briefcase.

Parameters:
id - the briefcase ID
contents - the objects to be removed
Throws:
FxApplicationException - if the items could not be removed
Since:
3.1

getItems

long[] getItems(long id)
                throws FxApplicationException
Load all item IDs stored in the given briefcase.

Parameters:
id - the briefcase ID
Returns:
the item IDs
Throws:
FxApplicationException - if the items could not be loaded

moveItems

void moveItems(long fromId,
               long toId,
               java.util.Collection<FxPK> contents)
               throws FxApplicationException
Moves items from one briefcase to another. Item data will not be moved!

Parameters:
fromId - the source briefcase ID
toId - the target briefcase ID
contents - the items to be moved
Throws:
FxApplicationException
Since:
3.1

addItemData

void addItemData(long briefcaseId,
                 BriefcaseItemData itemData)
                 throws FxApplicationException
Add a single item data for a briefcase item

Parameters:
briefcaseId - id of the briefcase
itemData - item data
Throws:
FxApplicationException - on errors
Since:
3.2.0

addItemData

void addItemData(long briefcaseId,
                 java.util.List<BriefcaseItemData> itemDatas)
                 throws FxApplicationException
Add multiple item datas for a briefcase

Parameters:
briefcaseId - id of the briefcase
itemDatas - item datas
Throws:
FxApplicationException - on errors
Since:
3.2.0

removeItemData

void removeItemData(long briefcaseId,
                    java.lang.Long itemId)
                    throws FxApplicationException
Remove item datas

Parameters:
briefcaseId - id of the briefcase
itemId - item id or if null for all items
Throws:
FxApplicationException - on errors

queryItemData

java.util.List<BriefcaseItemData> queryItemData(long briefcaseId,
                                                java.lang.Long itemId,
                                                java.lang.String metaData,
                                                java.lang.Integer intFlag1,
                                                java.lang.Integer intFlag2,
                                                java.lang.Integer intFlag3,
                                                java.lang.Long longFlag1,
                                                java.lang.Long longFlag2,
                                                BriefcaseItemData.SortField sortField,
                                                BriefcaseItemData.SortOrder sortOrder)
                                                throws FxApplicationException
Load matching item datas (non-null flags are queried)

Parameters:
briefcaseId - id of the briefcase
itemId - item id
metaData - meta data
intFlag1 - integer flag 1
intFlag2 - integer flag 2
intFlag3 - integer flag 3
longFlag1 - long flag 1
longFlag2 - long flag 2
sortField - sort field
sortOrder - sort order
Returns:
list of matching item datas
Throws:
FxApplicationException - on errors
Since:
3.2.0

queryItemDataCount

int queryItemDataCount(long briefcaseId,
                       java.lang.Long itemId,
                       java.lang.String metaData,
                       java.lang.Integer intFlag1,
                       java.lang.Integer intFlag2,
                       java.lang.Integer intFlag3,
                       java.lang.Long longFlag1,
                       java.lang.Long longFlag2)
                       throws FxApplicationException
Evaluate the count of matching item datas (non-null flags are queried)

Parameters:
briefcaseId - id of the briefcase
itemId - item id
metaData - meta data
intFlag1 - integer flag 1
intFlag2 - integer flag 2
intFlag3 - integer flag 3
longFlag1 - long flag 1
longFlag2 - long flag 2
Returns:
number of matching item datas
Throws:
FxApplicationException - on errors
Since:
3.2.0

updateItemData

void updateItemData(long briefcaseId,
                    BriefcaseItemData updateData)
                    throws FxApplicationException
Update a data item (except the position). The updateItem must contain a valid briefcase and object/item id

Parameters:
briefcaseId - id of the briefcase
updateData - data to update
Throws:
FxApplicationException - on errors
Since:
3.2.0