com.sap.netweaver.bc.uwl

Interface IUWLItemManager

public interface IUWLItemManager

The IUWLItemManager class provides functionality regarding retrieval and execution of Itemss. Methods in this class contain retrieving Items, their attachments, sorting or filtering them and performing Actions on them.

A handle to IUWLItemManager is got by calling IUWLService.getItemManager() method. Implementation of this interface is thread safe.
Usually many of the ItemManager methods need connection to the back end, for example getting the attachments or Description for the item. For performance reasons very first time when the user loads the UWL, client of UWL Service could optionally set uwlContext.setAllowBackEndConnections(false) and this forces UWL to take everything from cache for that method invocation and not to initiate any back end connections.

See Also:

IUWLService, QueryProperties, QueryResult.isPossiblyOutDated(), UWLContext.isBackEndConnectionsAllowed()

Method Summary

ItemCollection	filterItems(UWLContext context, ItemCollection items, CompoundExpression filter) Filters items based upon the filter passed.
Action	getActionForItem(UWLContext ctx, Item item, String actionName) Searches for the action in the the configuration.
Action	getActionForItem(UWLContext ctx, long itemId, String actionName) Looks in the configuration whether action is defined.
IActionHandler	getActionHandler(String handlerId) Look up registered action handler by its id.
Map	getActionProperties(UWLContext context, Item item, Action action, Map actionProperties, boolean needsItemValidation) This method should be called only if Action is registered with the UI.
String	getActionUrl(UWLContext context, Item item, Action action, Map actionProperties) This method should be called only if isActionLaunchable() returs true.
String	getActionUrl(UWLContext context, long[] itemIds, String action) Method that could be called to get one single url for launching multiple items.
String	getActionUrl(UWLContext context, long item, String action) This method should be called only if isActionLaunchable() returs true.
Map	getAllActionsForItem(UWLContext context, Item item) Returns all the possible actions on that item, taken from the configuration and the provider connector itself.
Attachment[]	getAttachmentHeaders(UWLContext context, Item item) Retreives the attachment headers for this item.
Action	getDefaultActionForItem(UWLContext ctx, Item item) Searches in the configuration for default action defined for the Item's Itemtype.
WorkLog	getHistoryForItem(UWLContext context, Item item) Return the history log data of the item, retrieved from the provider connector.
Item	getItemByExternalId(UWLContext context, String connectorId, String systemId, String externalId)
Item	getItemByUwlId(UWLContext context, long uwlId) Same as getItemByUwlId(context,uwlId,true,true)
Item	getItemByUwlId(UWLContext context, long uwlId, boolean fillAllAttributes, boolean fillDescription, boolean fillAttachmentHeaders) Method to retrieve an item.
QueryResult	getItems(UWLContext context, QueryProperties queryProps, CompoundExpression filter) Method to retrieve Items.
QueryResult	getItemsForItemType(UWLContext context, String itemType, QueryProperties queryProps, CompoundExpression viewFilter) Method to retrieve Items for a particular item type passed.If returned items are not fully uptodate, isPossiblyOutDated() on the result return true.
QueryResult	getItemsForView(UWLContext context, UWLView view, QueryProperties queryProps, CompoundExpression filter) Method to retrieve Items for a particular View.If returned items are not fully uptodate, isPossiblyOutDated() on the result return true.
String	getItemTypeForItem(UWLContext context, long itemId) Finds item type for the item identified by itemId.
ItemTypeCount[]	getItemTypesBySize(UWLContext ctx, String configurationGroup, String substitutedUser) Returns most popular item types and their count.
Attachment	getPopulatedAttachment(UWLContext context, long itemId, String internalAttachmentId) Locates an attachment identified by the internalAttachmentId for the item and populates it and returns.
Item	getSubProcessTrackingItem(UWLContext context, Item parentItem) Retrieves the sub process tracking item.
Set	getSubstitutedForUsersWithItems(UWLContext ctx, String itemType) Returns only those user ids for which the current user has substitued and has items for them.
int[]	getTotalAndEmphasizedItemCountForView(UWLContext context, UWLView view, String configurationGroup, String substitutedUser) Returns items that need to be emphasized and total items in a particular View.
boolean	isActionLaunchable(UWLContext context, Item item, Action action) Finds if action passed for the item is of launchable type.
ProviderStatus	performAction(UWLContext context, Item item, Action action, Map actionProperties) Call this method if and only if isActionLaunchable() returns false.
ProviderStatus	performAction(UWLContext context, Item item, String action) Performs action on the item passed.
ProviderStatus[]	performAction(UWLContext context, long[] itemKeys, String action, Map actionProperties) Performs action on all the items whose keys are passed.
ProviderStatus	performAction(UWLContext context, long itemId, Action action, Map actionProperties) Call this method if and only if isActionLaunchable() returns false.
ProviderStatus	performAction(UWLContext context, String externalItemId, String systemId, String connector, String action, Map actionProperties) Call this method if and only if isActionLaunchable() returns false.
void	populateAttachmentContent(UWLContext context, Item item, Attachment hollowAttachment) Fills the content of the hollowAttachment depending upon the attachment type.
void	populateAttachmentContents(UWLContext context, Item item, Attachment[] hollowAttachments) Fills the content of the hollowAttachments depending upon the attachment type.
Item	refreshAndGetItemByUwlId(UWLContext context, long uwlId) This method refreshes the item from the backend and returns it.
QueryResult	refreshCacheAndGetItems(UWLContext context, UWLView view, QueryProperties queryProps, CompoundExpression viewFilter) Connects to all providerConnectors and gets items from them.
QueryResult	search(UWLContext context, String textToSearch, UWLView view, QueryProperties queryProps, CompoundExpression filter) Search in the cache for items matching the text.
void	sortItems(UWLContext context, ItemCollection items, String[] sortKeys, boolean[] sortOrder) Method to explicitly sort the items based on the sort fields and the order passed.

Method Detail

getItems

public QueryResult getItems(UWLContext context,
                            QueryProperties queryProps,
                            CompoundExpression filter)
                     throws UWLException

Method to retrieve Items. If returned items are not fully uptodate, isPossiblyOutDated() on the result return true. In such a situation, this method needs to be called again if possibly through a timer set for few seconds to get the updated items. If end user needs recent items another option is to call refreshCacheAndGetItems() however that comes with the performance penalty since connections need to made to the provider systems.

Parameters:

context - , required, not null. Should have the valid portalRequest set inside it.

Returns:

QueryResult contains the items and the last connected status of different provider conenctors. Returned items are hollow, i.e. they are not filled with description ,custom attributes specified int the configuration, attachments etc.. To retreive a full item, use getItemByUwlId() method.

Throws:

UWLException - if items could not be retreived.

See Also:

QueryResult.isPossiblyOutDated(), UWLContext.isBackEndConnectionsAllowed()

getItemsForView

public QueryResult getItemsForView(UWLContext context,
                                   UWLView view,
                                   QueryProperties queryProps,
                                   CompoundExpression filter)
                            throws UWLException

Method to retrieve Items for a particular View.If returned items are not fully uptodate, isPossiblyOutDated() on the result return true. In such a situation, this method needs to be called again if possibly through a timer set for few seconds to get the updated items. If end user needs recent items another option is to call refreshCacheAndGetItems() however that comes with the performance penalty since connections need to made to the provider systems.

Parameters:

context - , required, not null.

Returns:

QueryResult contains the items and the last connected status of different provider conenctors. Returned items are hollow, i.e. they are not filled with description ,custom attributes specified int the configuration, attachments etc.. To retreive a full item, use getItemByUwlId() method.

Throws:

UWLException - if items could not be retreived.

See Also:

QueryResult.isPossiblyOutDated(), UWLContext.isBackEndConnectionsAllowed()

getItemsForItemType

public QueryResult getItemsForItemType(UWLContext context,
                                       String itemType,
                                       QueryProperties queryProps,
                                       CompoundExpression viewFilter)
                                throws UWLException

Method to retrieve Items for a particular item type passed.If returned items are not fully uptodate, isPossiblyOutDated() on the result return true.

Parameters:

context - , required, not null. Should have the valid portalRequest set inside it.

Returns:

QueryResult contains the items and the last connected status of different provider conenctors. Returned items are hollow, i.e. they are not filled with description ,custom attributes specified int the configuration, attachments etc.. To retreive a full item, use getItemByUwlId() method.

Throws:

UWLException - if items could not be retreived.

See Also:

QueryResult.isPossiblyOutDated(), UWLContext.isBackEndConnectionsAllowed()

refreshCacheAndGetItems

public QueryResult refreshCacheAndGetItems(UWLContext context,
                                           UWLView view,
                                           QueryProperties queryProps,
                                           CompoundExpression viewFilter)
                                    throws UWLException

Connects to all providerConnectors and gets items from them. These items are then cached and returned.Cache is kept and is refreshed by connecting to different provider connectors again.

Parameters:

context - , required, not null. Should have the valid portalRequest set inside it.

Returns:

QueryResult contains the items and the last connected status of different provider conenctors. Returned items are hollow, i.e. they are not filled with description ,custom attributes specified int the configuration, attachments etc.. To retreive a full item, use getItemByUwlId() method.

Throws:

UWLException - if items could not be retreived.

filterItems

public ItemCollection filterItems(UWLContext context,
                                  ItemCollection items,
                                  CompoundExpression filter)
                           throws UWLException

Filters items based upon the filter passed. Filtering can be more efficiently done by passing the filter information in the getItems()methods.

Parameters:

context -

Returns:

ItemCollection filtered items

Throws:

UWLException - if session is invalid.

search

public QueryResult search(UWLContext context,
                          String textToSearch,
                          UWLView view,
                          QueryProperties queryProps,
                          CompoundExpression filter)
                   throws UWLException

Search in the cache for items matching the text. Item's subject, description and attributes are compared for matching the text passed.

Parameters:

context -

Returns:

QueryResult containing the search results.

Throws:

UWLException

sortItems

public void sortItems(UWLContext context,
                      ItemCollection items,
                      String[] sortKeys,
                      boolean[] sortOrder)
               throws UWLException

Method to explicitly sort the items based on the sort fields and the order passed. Sorting can be done only on certain fields. These fields are listed in the Item documentation. It is more performant to sort while getting items itself by passing the sort information thro QueryProperties.

Parameters:

context -

items -

sortKeys - see Item for valid sort keys.

sortOrder - every entry corresponding to sortKey, if true ascending, else descending.

Throws:

UWLException

getTotalAndEmphasizedItemCountForView

public int[] getTotalAndEmphasizedItemCountForView(UWLContext context,
                                                   UWLView view,
                                                   String configurationGroup,
                                                   String substitutedUser)
                                            throws UWLException

Returns items that need to be emphasized and total items in a particular View. View contains the information regarding whether read or unread or new items be displayed emphasized. Typically emphasized items are displayed in bold in the User interface just like unread items in the Microsoft Outlook.

If cache is invalid for at least one of the item types contained in the view passed, return values contain -1,-1 respectively. This method doesnt make connections to the ProviderConnectors for performance reasons.

Parameters:

context -

configurationGroup - optional

substitutedUser - optional. If null ignored. If set to current user, only current users count is returned, if set to a substituted users, only items for this count is returned.

view - not null, contains metadata on emphasized mode.

Returns:

int[0] contains total items count, int[1] contains emphasized items.

Throws:

UWLException - if there is any database related error.

See Also:

UWLView.setEmphasizedItems(java.lang.String), QueryProperties.setSubstitutedUser(java.lang.String)

getItemTypesBySize

public ItemTypeCount[] getItemTypesBySize(UWLContext ctx,
                                          String configurationGroup,
                                          String substitutedUser)
                                   throws UWLException

Returns most popular item types and their count. Popularity is measured by the amount of items belonging to a particular item type. While calculating this ItemType hierarchy is also taken into account.

Parameters:

ctx -

configurationGroup - optional

substitutedUser - optional. If null ignored. If set to current user, only current users count is returned, if set to a substituted users, only items for this count is returned.

Returns:

array of ItemTypeCount strcture in the descending order

Throws:

UWLException - if there is any error

See Also:

QueryProperties.setSubstitutedUser(java.lang.String), ItemType

getSubstitutedForUsersWithItems

public Set getSubstitutedForUsersWithItems(UWLContext ctx,
                                           String itemType)
                                    throws UWLException

Returns only those user ids for which the current user has substitued and has items for them. If Tom substitues for Jon,Uli,Uwe but only Uwe,Uli have items then only Uli,Uwe are returned.
This method also taken into account the application context passed thro ctx parameter. This is applicable for collaboration room scenarios only.
Do note that substituting users and their count is also passed thro the QueryResult. However this is applicable for the view that is selected only.

Parameters:

ctx - not null

itemType - could be null. Use this to restrict to particular item type. If not specified all item types are considered.

Returns:

non null, non modifiable set of user ids. These are IUser.getUniqueId() identifiers.

Throws:

UWLException - if there are system problems.

See Also:

IUser, QueryProperties.setSubstitutedUser(java.lang.String), QueryResult.getSubstitutingUsers()

getAttachmentHeaders

public Attachment[] getAttachmentHeaders(UWLContext context,
                                         Item item)
                                  throws UWLException

Retreives the attachment headers for this item.

Parameters:

context - not null

item - not null

Returns:

Attachment[] Attachment's content is not populated, only header information is retreived. use populateAttachmentContent to fill the content of an attachment. This return value is not null.

Throws:

UWLException

See Also:

populateAttachmentContent(com.sap.netweaver.bc.uwl.UWLContext, com.sap.netweaver.bc.uwl.Item, com.sap.netweaver.bc.uwl.Attachment)

populateAttachmentContent

public void populateAttachmentContent(UWLContext context,
                                      Item item,
                                      Attachment hollowAttachment)
                               throws UWLException

Fills the content of the hollowAttachment depending upon the attachment type. For performance reasons, it is advicible to first get attachment headers and then in the next step, to fill the attachment contents if required.

Parameters:

context -

item -

hollowAttachment - not null

Throws:

UWLException

See Also:

Attachment

populateAttachmentContents

public void populateAttachmentContents(UWLContext context,
                                       Item item,
                                       Attachment[] hollowAttachments)
                                throws UWLException

Fills the content of the hollowAttachments depending upon the attachment type. For performance reasons, it is advicible to first get attachment headers and then in the next step, to fill the attachment contents if required.

Parameters:

context -

item -

hollowAttachments -

Throws:

UWLException

getPopulatedAttachment

public Attachment getPopulatedAttachment(UWLContext context,
                                         long itemId,
                                         String internalAttachmentId)
                                  throws UWLException

Locates an attachment identified by the internalAttachmentId for the item and populates it and returns.

Parameters:

context - requried

itemId - identifier of the item that owns the attachment

internalAttachmentId - should match the attachment.getInternalId()

Returns:

null if attachment is not found

Throws:

UWLException

getItemByUwlId

public Item getItemByUwlId(UWLContext context,
                           long uwlId,
                           boolean fillAllAttributes,
                           boolean fillDescription,
                           boolean fillAttachmentHeaders)
                    throws UWLException

Method to retrieve an item. Returned item has description ,attachment, custom attributes filled depending upon the flags passed in this method.

Parameters:

context -

uwlId -

fillAttachmentHeaders -

Returns:

Item never null , if item is not found exception is thrown.

Throws:

UWLException - if no item is found

getItemByExternalId

public Item getItemByExternalId(UWLContext context,
                                String connectorId,
                                String systemId,
                                String externalId)
                         throws UWLException

Parameters:

context - needed. Contains Users information

connectorId - needed. Specifies the Connector which fetched the item

systemId - system to which the item belogs

externalId - identifier of the item in the sytem

Returns:

Item never null , if item is not found exception is thrown. Item will contain all attributes and description.

Throws:

UWLException

getSubProcessTrackingItem

public Item getSubProcessTrackingItem(UWLContext context,
                                      Item parentItem)
                               throws UWLException

Retrieves the sub process tracking item. Tracking item (also known as request item) is retrieved by using parent items sub process id as the external id for tracking item. It is assumed that AdhocWorkflowConnector is responsible for giving the tracking item.

Returns:

null if subprocess item doesnt exist

Throws:

UWLException - in case of errors.

getItemByUwlId

public Item getItemByUwlId(UWLContext context,
                           long uwlId)
                    throws UWLException

Same as getItemByUwlId(context,uwlId,true,true)

Throws:

UWLException

refreshAndGetItemByUwlId

public Item refreshAndGetItemByUwlId(UWLContext context,
                                     long uwlId)
                              throws UWLException

This method refreshes the item from the backend and returns it. This is useful if user has reason to believe that item is modified outside the UWL for example, some attachments are added etc. For security reasons, a check is done to see if the user specified by the context is indeed the owner of the item. If item belongs to some other user, it is not retrieved.

Parameters:

context - not null

uwlId -

Returns:

Item if found, return value is not null. If item is not found exception is thrown.

Throws:

UWLException - if item is not found

getItemTypeForItem

public String getItemTypeForItem(UWLContext context,
                                 long itemId)
                          throws UWLException

Finds item type for the item identified by itemId.

Parameters:

context - required

Returns:

item type for the the item whose id is specified

Throws:

UWLException - if item is not found

performAction

public ProviderStatus[] performAction(UWLContext context,
                                      long[] itemKeys,
                                      String action,
                                      Map actionProperties)
                               throws UWLException

Performs action on all the items whose keys are passed.

Parameters:

context - not null

action - required, not null

Returns:

ProviderStatus[] contains execution status for each item

Throws:

UWLException

performAction

public ProviderStatus performAction(UWLContext context,
                                    Item item,
                                    String action)
                             throws UWLException

Performs action on the item passed. If action is not applicable, Provider status with error is returned.

Parameters:

context -

item - not null

action - not null

Returns:

ProviderStatus contains execution status for each item

Throws:

UWLException

performAction

public ProviderStatus performAction(UWLContext context,
                                    long itemId,
                                    Action action,
                                    Map actionProperties)
                             throws UWLException

Call this method if and only if isActionLaunchable() returns false.

Parameters:

context -

action -

Returns:

ProviderStatus

Throws:

UWLException

performAction

public ProviderStatus performAction(UWLContext context,
                                    Item item,
                                    Action action,
                                    Map actionProperties)
                             throws UWLException

Call this method if and only if isActionLaunchable() returns false.

Parameters:

context -

item -

action -

actionProperties -

Returns:

ProviderStatus

Throws:

UWLException

performAction

public ProviderStatus performAction(UWLContext context,
                                    String externalItemId,
                                    String systemId,
                                    String connector,
                                    String action,
                                    Map actionProperties)
                             throws UWLException

Call this method if and only if isActionLaunchable() returns false.

Parameters:

context -

externalItemId -

systemId -

connector -

action -

actionProperties -

Returns:

ProviderStatus

Throws:

UWLException

getActionHandler

public IActionHandler getActionHandler(String handlerId)
                                throws UWLException

Look up registered action handler by its id. Exception thrown if not found.

Parameters:

handlerId - id of the action handler. See Action class.

Returns:

Action handler.

Throws:

UWLException - Thrown if not found

See Also:

IActionHandler, Action

getActionUrl

public String getActionUrl(UWLContext context,
                           Item item,
                           Action action,
                           Map actionProperties)
                    throws UWLException

This method should be called only if isActionLaunchable() returs true.

Parameters:

context - not null

item - needed

action - not null

Returns:

url which could be launched by the client.

Throws:

UWLException

getActionUrl

public String getActionUrl(UWLContext context,
                           long[] itemIds,
                           String action)
                    throws UWLException

Method that could be called to get one single url for launching multiple items. For this to work, the Action handler associated with the action must implement IMultiItemLaucher interface.
URL may contain the dynamic parameters from the configuration XML too.

Parameters:

context - needed

itemIds - needed

action - needed

Returns:

URL to launch all the items.

Throws:

UWLException

See Also:

IMultiItemLauncher

getActionUrl

public String getActionUrl(UWLContext context,
                           long item,
                           String action)
                    throws UWLException

This method should be called only if isActionLaunchable() returs true.

Parameters:

context - not null

item - identifier for the item

action - action name for which URL is to be launched.

Returns:

could be null if action is not launchable or action is not found

Throws:

UWLException - in case of system problems or if Item is not found

getActionProperties

public Map getActionProperties(UWLContext context,
                               Item item,
                               Action action,
                               Map actionProperties,
                               boolean needsItemValidation)
                        throws UWLException

This method should be called only if Action is registered with the UI.

Parameters:

context - not null

item - needed

action - not null

needsItemValidation - - flag indicating that the item passed has to be validated

Returns:

actionProperties filled with all dynamic properties

Throws:

UWLException

isActionLaunchable

public boolean isActionLaunchable(UWLContext context,
                                  Item item,
                                  Action action)
                           throws UWLException

Finds if action passed for the item is of launchable type. Typical launchable actions have handlers like UrlLauncher, SAPAPPLauncher, MiniAppLauncher etc. More details on these can be found in the (Action) documentation.

Parameters:

context -

item - not null

action - not null

Returns:

boolean true if action is launchable.

Throws:

UWLException

See Also:

IActionHandler

getActionForItem

public Action getActionForItem(UWLContext ctx,
                               Item item,
                               String actionName)
                        throws UWLException

Searches for the action in the the configuration. Hierarchy of Item types is traversed for locating the default action.

Parameters:

item - not null

actionName - not null

Returns:

Action could be null if action is not found.

Throws:

UWLException

getDefaultActionForItem

public Action getDefaultActionForItem(UWLContext ctx,
                                      Item item)
                               throws UWLException

Searches in the configuration for default action defined for the Item's Itemtype. Hierarchy of Item types is traversed for locating the default action. If action is not found in the configuration then Provider Connector is asked and then attachments are looked up.

Parameters:

item - not null

Returns:

Action could be null if action is not found.

Throws:

UWLException

See Also:

ItemType.getDefaultAction()

getActionForItem

public Action getActionForItem(UWLContext ctx,
                               long itemId,
                               String actionName)
                        throws UWLException

Looks in the configuration whether action is defined. Hierarchy of Item types is traversed for locating the default action. If action is not found in the configuration then Provider Connector is asked and then attachments are looked up.

Parameters:

ctx -

itemId -

actionName -

Returns:

Action could be null if action not found

Throws:

UWLException

getAllActionsForItem

public Map getAllActionsForItem(UWLContext context,
                                Item item)
                         throws UWLException

Returns all the possible actions on that item, taken from the configuration and the provider connector itself. This may or may not include any attachment type actions depending upon what the connector returns. However getActionForItem looks up in the attachment also. This method possibly marks item as incomplete if Provider decides not to connect to the backend depending upon isBackEndConnectionsAllowed() value from the context.

Parameters:

context - needed

item - not null needed

Returns:

Map

Throws:

UWLException

See Also:

com.sap.netweaver.bc.uwl.connect.IProivderConnector#getAllActionsForItem

getHistoryForItem

public WorkLog getHistoryForItem(UWLContext context,
                                 Item item)
                          throws UWLException

Return the history log data of the item, retrieved from the provider connector. May return null.

Parameters:

context - required

item - not null, required

Returns:

History data

Throws:

UWLException

See Also:

WorkLog