com.sapportals.portal.pcd.gl

Interface ILock


public interface ILock


Method Summary
 String getChangelistId()
          Returns the id of the change recording change list containing the object this lock is associated with, or null if the object is not checked out.
 String getDescription()
          Returns the description which was stored with the lock when this lock object was created.
 long getRemainigLifespan()
          Returns the remaining lifespan (time to expiration) of this lock object in milliseconds.
 long getRemainingProtectionSpan()
          Returns the remaining protection span of this lock object in milliseconds.
 String getSessionId()
          Returns the session id which was relevant for the lock when this lock object was created.
 LockState getState()
          Returns the current state of this lock object.
 LockState getStateAndRefresh(String userId, String sessionId)
          Returns the current state of this lock object and perform a refresh (see refresh(java.lang.String, java.lang.String)for more information) on the lock if possible.
 String getUserId()
          Returns the id of the owner of the lock when this lock object was created.
 boolean isChangeRecordingLock()
          Returns true if the object for which this lock was created is checked out in a change recording change list.
 void refresh(String userId, String sessionId)
          Refresh the lock entry which means that it's last modification time is updated.
 void release(String userId, String sessionId)
          Release the lock (i.e. unlock the resource), which removes the lock in the regsitry.
 ILock take(String userId, String sessionId, String description)
          Take this lock from its current owner/session after it's lifespan is over.
 ILock take(String userId, String sessionId, String description, boolean administrativeMode)
          Take this lock from its current owner/session even before it's lifespan is over.
 

Method Detail

getUserId

String getUserId()
                 throws LockingException
Returns the id of the owner of the lock when this lock object was created. If the state of this lock object is LockState.ACTIVE, this is still the owner of the lock.

Returns:
the user id
Throws:
LockingException - if the lock registry is not accessible

getChangelistId

String getChangelistId()
                       throws LockingException
Returns the id of the change recording change list containing the object this lock is associated with, or null if the object is not checked out.

Returns:
the containing change recording change list id
Throws:
LockingException - if the change recording service is not accessible

isChangeRecordingLock

boolean isChangeRecordingLock()
Returns true if the object for which this lock was created is checked out in a change recording change list. Change recording locks does not have a life span and protection span - they are active as long as the corresponding object is checked out. Change recording locks can be taken by the same user who checked out the corresponding object.

Returns:
true if this is a change recording lock, false otherwise.

getSessionId

String getSessionId()
                    throws LockingException
Returns the session id which was relevant for the lock when this lock object was created. If the state of this lock object is LockState.ACTIVE, this is still the session id which is stored in the central lock regisrty.

Returns:
the session id
Throws:
LockingException - if the lock registry is not accessible

getDescription

String getDescription()
                      throws LockingException
Returns the description which was stored with the lock when this lock object was created. If the state of this lock object is LockState.ACTIVE, this is still the description which is stored in the central lock regisrty.

Returns:
the description
Throws:
LockingException - if the lock registry is not accessible

getRemainingProtectionSpan

long getRemainingProtectionSpan()
                                throws LockingException
Returns the remaining protection span of this lock object in milliseconds. When the value is less than 0 (zero) any user/session can take over this lock object (see method take(String,String,String)). However, this lock object will remain in state LockState.ACTIVEeven with a negative protection span, until the lock expires ((see getRemainigLifespan())).

Returns:
the remaining protection span in milliseconds
Throws:
LockingException - if the lock registry is not accessible or if the lock has been released in the meanwhile (i.e. its state is LockState.INACTIVE)

getRemainigLifespan

long getRemainigLifespan()
                         throws LockingException
Returns the remaining lifespan (time to expiration) of this lock object in milliseconds. When the value is 0 (zero) the lock will be released automatically (removed from lock registry) and the state of the lock object will be transferred to inactive LockState.INACTIVE

Returns:
the remaining lifespan in milliseconds
Throws:
LockingException - if the lock registry is not accessible or if the lock has been released in the meanwhile (i.e. its state is LockState.INACTIVE)

getState

LockState getState()
                   throws LockingException
Returns the current state of this lock object. Please refer to LockStatefor a description of the various states that a lock object can have.

Returns:
the current state of this lock object
Throws:
LockingException - if the lock registry is not accessible

getStateAndRefresh

LockState getStateAndRefresh(String userId,
                             String sessionId)
                             throws LockingException
Returns the current state of this lock object and perform a refresh (see refresh(java.lang.String, java.lang.String)for more information) on the lock if possible. On this instance, getStateAndRefresh can only be called by the user/session that is returned by this.getUserId() and this.getSessionId() respectively. In case that current user/session is identical with the result of this.getUserId()/ this.getSessionId() but the lock has changed it's owner, LockState.BROKENis returned and the refresh is not carried out on the lock. If no lock is active for the resource with id this.getResourceId(), no refresh is carried out and LockState.INACTIVEreturned as result.

Parameters:
userId - id of the current user
sessionId - id of the current session (only considered, if doRefresh has value true
Returns:
the current state of this lock object
Throws:
LockingException - if the lock registry is not accessible if userId differs from the value returned by this.getUserId(), or
if the parameter sessionId differs from the result of this.getSessionId() if the lock has been released in the meanwhile (i.e. it's state is LockState.INACTIVE)

refresh

void refresh(String userId,
             String sessionId)
             throws LockingException
Refresh the lock entry which means that it's last modification time is updated. After a specified time interval, the so called lifespan, the lock can be taken by another user. After a succesfull call of refresh, the current client can rely on owning the lock for the full lifespan. The only exception is that a user with administration privileges takes (by calling method take(String, String, String, boolean)) the lock in this time interval.

A client, which called refresh during a working session and has never received a LockingException for one the the reasons described below, can rely on being the only application that applied changes on the respective resource for this time interval (assuming that all other clients cooperate and respect locks).

refresh can only be called by the person owning the lock. Additionaly, this lock object instance can only used for refresh by the user/session that is returned by methods this.getUserId() and this.getSessionId() respectively. This means that a call of this method is only succesful, if


user id in the lock (central lock registry)   =   this.getUserId()   =   parameter userId

and

session id in the lock (central lock registry)   =   this.getSessionId()   =   parameter sessionId
holds.

Parameters:
userId - the id of the current user
sessionId - the id of the current session
Throws:
LockingException - if the lock registry is not accessible if the lock has been released in the meanwhile (i.e. it's state is LockState.INACTIVE), if lock is owned by another user, which means that this lock object is broken (i.e. it's state is LockState.BROKEN), or
if the parameter userId differs from the value returned by this.getUserId(), or
if the parameter sessionId differs from the result of this.getSessionId()

release

void release(String userId,
             String sessionId)
             throws LockingException
Release the lock (i.e. unlock the resource), which removes the lock in the regsitry. This sets this lock object's state to LockState.INACTIVE(see method getState()for details).

release can only be called by the user/session owning the lock. Additionaly, this lock object instance can only used for refresh by the user/session that is returned by methods this.getUserId() and this.getSessionId() respectively. This means that a call of this method is only succesful, if


user id in the lock (central lock registry)   =   this.getUserId()   =   parameter userId

and

session id in the lock (central lock registry)   =   this.getSessionId()   =   parameter sessionId
holds.

Parameters:
userId -
sessionId -
Throws:
LockingException - if the lock registry is not accessible if the lock does not exist anymore in the registry, which means that this lock object is not active anymore (i.e. it's state is not LockState.ACTIVE) if lock is owned by another user, which means that this lock object is broken (i.e. it's state is LockState.BROKEN), or
if the parameter userId differs from the value returned by this.getUserId(), or
if the parameter sessionId differs from the result of this.getSessionId()

take

ILock take(String userId,
           String sessionId,
           String description)
           throws LockingException
Take this lock from its current owner/session after it's lifespan is over. This is the regular mode of the take-operation. In the succesful case, a lock object is returned, which has state LockState.ACTIVE, is owned by the user who has userId as id and has the session id that defined by the value of parameter sessionId. The description data is appended to the existing description of the respective lock. At the same time, this lock object is transfered to state LockState.BROKEN.

Parameters:
userId - the current user, who will become the new owner of the lock associated with this lock object
description - the additional descriptive data
sessionId -
Returns:
a new lock object describing the effective lock after take has been completed successfully
Throws:
LockingException - if the lock registry is not accessible
if the lock does not exist anymore in the registry, which means that this lock object is not active anymore (i.e. it's state is not LockState.ACTIVE)
if the lifespan of this lock object is not over yet, so it can not be taken by another user in the regular mode

take

ILock take(String userId,
           String sessionId,
           String description,
           boolean administrativeMode)
           throws LockingException
Take this lock from its current owner/session even before it's lifespan is over. Please use this method carefully! If parameter administrativeMode is true the current lifespan for this lock object is ignored. This is the administrative mode of the take-operation. If administrativeMode is false, the behaviour of this method is just like take(String,String, String).
In the successful case, a lock object is returned, which has state LockState.ACTIVEand is owned by the user who has userId as id. At the same time, this lock object is transfered to state LockState.BROKEN.

Parameters:
userId - the current user, who will become the new owner of the lock associated with this lock object
sessionId - the current user, who will become the new owner of the lock associated with this lock object
description - the additional descriptive data
administrativeMode - if true, ignore lock's lifespan
Returns:
a new lock object describing the effective lock after take has been completed successfully
Throws:
LockingException - if the lock registry is not accessible
if the lock does not exist anymore in the registry, which means that this lock object is not active anymore (i.e. it's state is not LockState.ACTIVE)
if the lifespan of this lock object is not over yet, so it can not be taken by another user in the regular mode (this can only occur, if administrativeMode was set to false)
Access Rights

This class can be accessed from:


SC DC Public Part ACH
[sap.com] EP-BASIS-API [sap.com] tc/epbc/pcd/gl/api - EP-PIN
[sap.com] EP-BASIS-API [sap.com] tc/epbc/pcd/gl/api api EP-PIN
[sap.com] KMC-WPC [sap.com] tc/kmc/wpc/wpcfacade api EP-PIN-WPC-WCM
[sap.com] EP-BASIS [sap.com] tc/epbc/pcd/pars/srvgldeprecated api BC-PIN-PCD


Copyright 2011 SAP AG Complete Copyright Notice