FileNet Content Services
Java Connector v3.0

com.filenet.wcm.api
Interface LockableObject

All Superinterfaces:
BaseObject, java.io.Serializable, ValueObject
All Known Subinterfaces:
CustomObject, Document, Document, Folder, Folder, PublishRequest, PublishTemplate, StoredSearch, StyleTemplate, WorkflowDefinition

public interface LockableObject
extends BaseObject

Not Implemented in CS Java Connector v3.0.

A LockableObject object represents a CustomObject, Document, or Folder class or subclass for which concurrent write access can be detected and prevented by any application that participates in cooperative locking.

This interface provides methods that work in conjunction with the Content Services server to provide cooperative locking functionality. An application can call these methods to set or remove a lock on a lockable object, extend the timeout period of an existing lock, and query the object's lock state.


Field Summary
 
Fields inherited from interface com.filenet.wcm.api.BaseObject
EXPORT_DEFAULT, EXPORT_ENCODED_CONTENT, EXPORT_FULL, EXPORT_OBJECT_ID, EXPORT_OBJECT_SECURITY, IMPORT_DEFAULT, IMPORT_OBJECT_ID, IMPORT_OWNER, IMPORT_PERMISSIONS, TYPE_ACTIVE_MARKING, TYPE_ANNOTATION, TYPE_ANY, TYPE_CBR_ENGINE_TYPE, TYPE_CHOICE, TYPE_CHOICELIST, TYPE_CLASS_SUBSCRIPTION, TYPE_CLASSDEFINITION, TYPE_CLASSDESCRIPTION, TYPE_COLUMN_DEFINITION, TYPE_COMPUTER, TYPE_CONTENT_CACHE_SERVICE, TYPE_CONTENT_MGR_SERVICE, TYPE_CONTENT_REFERENCE, TYPE_CONTENT_TRANSFER, TYPE_CUSTOMOBJECT, TYPE_DOCUMENT, TYPE_DOCUMENT_CLASSIFICATION_ACTION, TYPE_DOCUMENT_LIFECYCLE_ACTION, TYPE_DOCUMENT_LIFECYCLE_POLICY, TYPE_DOCUMENTSTATE, TYPE_DOMAIN, TYPE_DYNAMIC_REFERENTIAL_CONTAINMENT_RELATIONSHIP, TYPE_ENTIRENETWORK, TYPE_EVENT, TYPE_EVENT_ACTION, TYPE_FEATURE_ADD_ON, TYPE_FILESTORE, TYPE_FOLDER, TYPE_GROUP, TYPE_INSTANCE_SUBSCRIPTION, TYPE_LINK, TYPE_LOCALIZED_STRING, TYPE_MARKING_SET, TYPE_MULTIPLEVALUES, TYPE_OBJECT_STORE, TYPE_OBJECTSET, TYPE_OBJSTORE_SERVICE, TYPE_PERMISSION, TYPE_PROPERTY_DEFINITION, TYPE_PROPERTYDESCRIPTION, TYPE_PROPERTYDESCRIPTIONS, TYPE_PUBLISH_REQUEST, TYPE_PUBLISH_TEMPLATE, TYPE_READONLY_OBJECT_SET, TYPE_REALM, TYPE_REFERENTIAL_CONTAINMENT_RELATIONSHIP, TYPE_SECURITY_POLICY, TYPE_SECURITY_TEMPLATE, TYPE_STORAGE_POLICY, TYPE_STORED_SEARCH, TYPE_STYLE_TEMPLATE, TYPE_SUBSCRIPTION, TYPE_TABLE_DEFINITION, TYPE_TRANSIENT, TYPE_USER, TYPE_VERSIONSERIES, TYPE_WORKFLOW_CLASS_SUBSCRIPTION, TYPE_WORKFLOW_INSTANCE_SUBSCRIPTION, TYPE_WORKFLOWDEFINITION, TYPE_XML_PROPERTY_MAPPING_SCRIPT
 
Method Summary
 java.lang.String extendLock(int timeout)
          

Not Implemented in CS Java Connector v3.0.

 java.lang.String extendLock(java.lang.String token, int timeout)
          

Not Implemented in CS Java Connector v3.0.

 boolean isLocked()
          

Not Implemented in CS Java Connector v3.0.

 java.lang.String lock(int timeout)
          

Not Implemented in CS Java Connector v3.0.

 void unlock()
          

Not Implemented in CS Java Connector v3.0.

 void unlock(java.lang.String token)
          

Not Implemented in CS Java Connector v3.0.

 
Methods inherited from interface com.filenet.wcm.api.BaseObject
equals, exportObject, getClassId, getId, getName, getObjectStoreId, getObjectType, getSession, hashCode, thisBaseObject
 

Method Detail

lock

public java.lang.String lock(int timeout)
                      throws ObjectLockedException

Not Implemented in CS Java Connector v3.0.

Requests that this object be locked for the specified number of seconds. After this object is locked, you can call methods to update the object (for example, assign values to its properties with a setProperties call).

To successfully execute this method, the current user must have permission to modify this object's properties. For example, locking a Document object requires Permission.LEVEL_MODIFY_PROPERTIES_DOCUMENT or Permission.LEVEL_WRITE_DOCUMENT.

If the call succeeds:

You cannot lock:

Parameters:
timeout - An int value that represents the number of seconds after which the lock will expire. The range of values is 0 to 2147483647 seconds.

Returns:
A String (GUID) that represents this object's LockToken property.

Throws:
ObjectLockedException - Thrown if the object cannot be locked.

extendLock

public java.lang.String extendLock(java.lang.String token,
                                   int timeout)
                            throws ObjectLockedException

Not Implemented in CS Java Connector v3.0.

Changes the existing lock's timeout value. This method updates the object's DateLastModified property, updates its LockTimeout property to extend the timeout period by the specified number of seconds, and returns a String that represents the changed LockToken property value.

Only the owner of the lock can successfully call this method, which requires the value of the LockToken property (returned from the lock method) as a parameter. An ObjectLockedException is thrown if the caller is not the owner of the lock or if the token passed to the method is invalid. There is no limit to the number of times you can call this method.

Parameters:
token - A String that contains the value (GUID) of the lock to be modified. Cannot be null.
timeout - An int value that represents the changed timeout value, in seconds, for this object's lock. The range of values is 0 to 2147483647 seconds. Passing in 0 (zero) effectively unlocks the object.

Returns:
A String (GUID) representing the value of the modified LockToken property.

Throws:
ObjectLockedException - Thrown if the object's lock timeout cannot be extended.

extendLock

public java.lang.String extendLock(int timeout)
                            throws ObjectLockedException

Not Implemented in CS Java Connector v3.0.

Changes the existing lock's timeout value without supplying a lock token.

For non-batch operations, you can call either form of extendLock.
For batch operations:

The following code fragment illustrates the point:

 session.startBatch(false, false, false);

 String strToken = doc.lock(30); //strToken=null because lock is called inside a batch
 session.setBatchItemlabel("lock");

 ... call some methods on the locked document

 doc.extendLock(30); //can't use doc.extendLock(strToken,30) because strToken is null

 ... call some additional methods on the locked document here

 doc.unlock(); //can't use doc.unlock(strToken) because strToken is null
 session.setBatchItemLabel("unlock");

 session.executeBatch(); 

None of the calls after the startBatch call is actually executed until executeBatch is invoked. As a result, the value for the token variable remains null. However, if lock had been called before the startBatch call, the strToken variable would have a value and the unlock(strToken) call from within the batch would succeed.

This method updates the object's DateLastModified property and its LockTimeout property to extend the timeout period by the specified number of seconds. Only the owner of the lock can successfully call this method. An ObjectLockedException is thrown if the caller is not the owner of the lock. There is no limit to the number of times you can call this method.

Parameters:
timeout - An int value that represents the changed timeout value, in seconds, for this object's lock. The range of values is 0 to 2147483647 seconds. Passing in 0 (zero) effectively unlocks the object.

Returns:
A String (GUID) representing the value of the modified LockToken property.

Throws:
ObjectLockedException - Thrown if the object's lock timeout cannot be extended.

isLocked

public boolean isLocked()

Not Implemented in CS Java Connector v3.0.

Queries this object's lock state.

This convenience method examines the object's lock-related properties and determines whether the object is locked.

Note that this method returns an approximation of the locked state at the time of the call. Once this method executes and returns the value, the object's lock state could be immediately changed by another application's call to the lock method or it could expire. An alternative approach is to call the lock method and handle any exception thrown if the method fails.

This method returns false if the LockTimeout property is not set or is set to all zeroes, or if the lock has expired. The lock is determined to be expired if the DateLastModified property value plus the number of seconds specified by the LockTimeout property is less than the current system time. (If the DateLastModified property is not set, the value of the DateCreated property is used for the calculation.)

Returns:
true if this object is locked; otherwise, false.

unlock

public void unlock(java.lang.String token)

Not Implemented in CS Java Connector v3.0.

Explicitly removes the lock from this object. Only the owner of a lock may remove it. The caller must pass in the value of this object's LockToken property (which is the value returned from a lock or extendLock call). An ObjectLockedException is thrown if the caller is not the owner of the lock. A RemoteServerException is thrown if an invalid token is passed to the method.

Upon successful execution, the values for the object's LockOwner, LockToken, and LockTimeout properties are removed.

If you do not call unlock to explicitly remove the lock, the lock is implicitly removed when the lock's timeout value expires.

Parameters:
token - A String (GUID) that represents the value of this object's LockToken property. Cannot be null.

unlock

public void unlock()

Not Implemented in CS Java Connector v3.0.

Explicitly removes the lock from this object without supplying a lock token. Only the owner of a lock may remove it. An RemmoteServerException is thrown if the caller is not the owner of the lock.

For non-batch operations, you can call either form of unlock.
For batch operations:

Refer to the extendLock(timeout) method for a code example.

Upon successful execution, the values for the object's LockOwner, LockToken, and LockTimeout properties are removed. If you do not call unlock to explicitly remove the lock, the lock is implicitly removed when the lock's timeout value expires.


FileNet Content Services
Java Connector v3.0