com.sap.netweaver.bc.uwl.connect

Interface IPushChannel

public interface IPushChannel

This interface defines typical methods needed to be used by the ProviderConnector. A handle to IPushChannel is got by calling IUWLService.getPushChannel() method. Typically, when certain Action is performed on an Item, it is necessary to update the Item in the UWL persistence cache. IPushChannel acts as a communication channel from Provider Connector to the UWL system.
IPushChannel interface also defines method to push items to UWL.

See Also:

IUWLService.getPushChannel(), IProviderConnector, ConnectorResult

Method Summary

void	attachSubProcess(IProviderConnector pc, String userWhoCreatedItem, long parentItemId, String subProcessId) Method to attach a sub process with an item.
boolean	deleteItem(IProviderConnector pc, UWLContext uwlContext, Item item) Method that deletes the item from the UWL cache.
void	deleteSharedItemsWithExternalIds(IProviderConnector pc, String system, List externalIds) This method deletes all shared items with external ids passed.
boolean	detachSubProcess(IProviderConnector pc, UWLContext uwlContext, long parentItemId, Action action, Map actionProperties) Method to detach a sub process from an item.
void	forceRefresh(String userId, String providerId, String systemId, String itemType) Force the refresh of items for a user from a particular provider and system on a particular item type
Item	getItemByKey(ItemKey key) Connector implementation can get hold of an Item object using this method.
ItemKey	getItemKeyByInternalId(long itemId) Method that returns the Key for item.
ItemCollection	getItemsByKey(ItemKey key) Connector implementation can get hold of an Items object using this method.
Date	getLastCachedTime(IProviderConnector pc, String system, String userId, String itemType) Method to retrieve last cachend time for a user.
boolean	isUserActive(String userId) Method that checks if there is an UWL session existing for the user that is asked for.
List	pushItems(IProviderConnector pc, com.sap.security.api.IUser user, ConnectorResult pushedItems) Method used to push items to UWL.
void	pushSharedItem(IProviderConnector pc, Item item, Set assignedUsers) This is meant only for Adhoc Workflow Connector.
boolean	updateItem(IProviderConnector pc, UWLContext uwlContext, Item item) This method should be called if item is changed in the provider system.

Method Detail

isUserActive

boolean isUserActive(String userId)

Method that checks if there is an UWL session existing for the user that is asked for. Provider Connector may optionally use this information before pushing items.

Parameters:

userId -

Returns:

true if user has active session with UWL service,false otherwise

getLastCachedTime

Date getLastCachedTime(IProviderConnector pc,
                       String system,
                       String userId,
                       String itemType)

Method to retrieve last cachend time for a user.

Parameters:

pc -

userId - needed

itemType -

Returns:

last cached time for the user. Time returned is provider system's time if it was set else uwl time.

pushItems

List pushItems(IProviderConnector pc,
               com.sap.security.api.IUser user,
               ConnectorResult pushedItems)
               throws UWLException

Method used to push items to UWL. If items contained inside do not have Item type assigned, then they are computed by UWL. This method can be used to send new items, modified items and deleted items to UWL.

Parameters:

pc - Provider Connector that is pushing the item.

user - User to whom the items belong, not null.

pushedItems - contains information on Items pushed.

Returns:

non null list of items that could not be saved. Empty list if everything is successful.

Throws:

UWLException - in case of system problems

pushSharedItem

void pushSharedItem(IProviderConnector pc,
                    Item item,
                    Set assignedUsers)
                    throws UWLException

This is meant only for Adhoc Workflow Connector. This method can be used to send a shared item that is assigned to multiple users in one method call.
If the item sent already exists, then it is deleted completely and then the new item that is sent is inserted into UWL cache. An items existence is checked by looking at its external id, connector id,system id combination.
En example usage is

 Item item = new Items(); //create the item and fill all its fields
 item.setShared();
 Set users=new HashSet();
 users.add("USER.PRIVATE_DATASOURCE.un:test88");
 users.add(someIUser.getUniqueId());
 users.add("USER.PRIVATE_DATASOURCE.un:testuser1");
 try{
 uwlReceiver.pushSharedItems( this, item, users);
 }catch( UWLException ex){
   ///oops, something went wrong. log it.
 }
 

Parameters:

pc -

item - not null needed.

assignedUsers - should contain one or more portal user ids. Do note that UWL always uses the uniqueID of IUser object and not uniqueName() of the IUser object. If this is empty only items current user is treated as the assignee. Do note this assignedUsers differs from items attribute assigned users. This difference arises from the fact that under substition cases, assignedUsers passed in this method may include substituted users for whom item may not be assigned actually.

Throws:

UWLException - if any of the assignedUsers is not present in the UM.

See Also:

Item

updateItem

boolean updateItem(IProviderConnector pc,
                   UWLContext uwlContext,
                   Item item)
                   throws UWLException

This method should be called if item is changed in the provider system. Upon successful completion of this method, uwl cache is updated. However certain attributes of the item like systemid, userid,connector id,externalid can not be updated.

Parameters:

pc - the provider connector.

uwlContext - could be null, in which case, user's active sessions information in the memory may not be uptodate.

item - the item in question. should belong to the provider connector that calls this method.

Returns:

true if item is found , false if item not found

Throws:

UWLException - in case of cache problems

deleteItem

boolean deleteItem(IProviderConnector pc,
                   UWLContext uwlContext,
                   Item item)
                   throws UWLException

Method that deletes the item from the UWL cache. Deleting the item also removes cached custom attributes. For deletion to happen, item should be existing in the UWL cache and should have been retrieved or pushed from the ProviderConnector.If this method is called and item is not removed from the provider system, there is a possibility that item is re feteched next time.

Parameters:

pc - not null

uwlContext - could be null, if null, user's active sessions are not uptodate with the deletion of item. If this method is called from an IActionHandler code, pass proper uwlContext.

item - not null, should have valid externalId,systemId,connectorId. If it is a shared item it is okey for userId not to be filled in this Item. But it is highly recommended to pass the user id of atlest one user who is assigned to it.

Returns:

true if deletion succeeds,false if item is not found in the cache

Throws:

UWLException - if there is cache related problem or connector is not registered.

getItemByKey

Item getItemByKey(ItemKey key)
                  throws UWLException

Connector implementation can get hold of an Item object using this method.

Returns:

If item not found returns null.

Throws:

UWLException - in case of cache related problems.

getItemsByKey

ItemCollection getItemsByKey(ItemKey key)
                             throws UWLException

Connector implementation can get hold of an Items object using this method. userId can be null, which will return all items for the specified external id, system and connector.

Returns:

If items not found returns null.

Throws:

UWLException - in case of cache related problems.

getItemKeyByInternalId

ItemKey getItemKeyByInternalId(long itemId)
                               throws UWLException

Method that returns the Key for item. In case item is a shared item, user id returned is not a valid one.

Parameters:

itemId -

Returns:

non null connector id. If item is not found it returns null

Throws:

UWLException

deleteSharedItemsWithExternalIds

void deleteSharedItemsWithExternalIds(IProviderConnector pc,
                                      String system,
                                      List externalIds)
                                      throws UWLException

This method deletes all shared items with external ids passed.

Parameters:

pc - not null

system - system to which these shared items belong to

externalIds, - non null String list of External Identifiers.

Throws:

UWLException - if there is deletion error

attachSubProcess

void attachSubProcess(IProviderConnector pc,
                      String userWhoCreatedItem,
                      long parentItemId,
                      String subProcessId)
                      throws UWLException

Method to attach a sub process with an item. By calling this method Connector informs UWL that sub process is created for the item.

Parameters:

pc - connector not null

userWhoCreatedItem - not null, contains user who is creating it

itemId - key of parent item on which a sub process is started

subProcessId - identifier for the sub proess.

Throws:

UWLException - if there is cache problem.

detachSubProcess

boolean detachSubProcess(IProviderConnector pc,
                         UWLContext uwlContext,
                         long parentItemId,
                         Action action,
                         Map actionProperties)
                         throws UWLException

Method to detach a sub process from an item. This method should typically be called as part of IActionHandler implementation.

Parameters:

pc - connector not null

uwlContext - not null

actionProperties - not null properties passed in the performAction method of IActionHandler

parentItemId - key of item on which a sub process was started earlier

action - terminating action of the sub process, could be null. If action is not null, if parent item represented by itemId has the same action, parent item's action is invoked.

Returns:

true if action is executed on the parent item successfully, false otherwise

Throws:

UWLException - in case of cache problems

forceRefresh

void forceRefresh(String userId,
                  String providerId,
                  String systemId,
                  String itemType)
                  throws UWLException

Force the refresh of items for a user from a particular provider and system on a particular item type

Parameters:

userId -

providerId -

systemId -

itemType -

Throws:

UWLException

Access Rights

This class can be accessed from:

SC	DC	Public Part	ACH
[sap.com] UWLJWF	[sap.com] tc/kmc/bc.uwl/api	-	EP-BC-UWL
[sap.com] UWLJWF	[sap.com] tc/kmc/bc.uwl/api	default	EP-BC-UWL