oracle.ifs.beans
Class LockObject

java.lang.Object
  |
  +--oracle.ifs.beans.LibraryObject
        |
        +--oracle.ifs.beans.TieLibraryObject
              |
              +--oracle.ifs.beans.SystemObject
                    |
                    +--oracle.ifs.beans.TieSystemObject
                          |
                          +--oracle.ifs.beans.LockObject

All Implemented Interfaces:

IfsEventHandler, LibraryObjectInterface, SystemObjectInterface, Traceable

Direct Known Subclasses:

TieLockObject

public class LockObject

extends TieSystemObject

The LockObject class is intended to encapsulate information associated with a lock on a PublicObject such as the state of the lock, timeout of the lock, the lock holder, etc.

The different lock types are:

• Unlock - no lock
• Hard lock - the PublicObject cannot be modified nor deleted
• Soft lock - the PublicObject cannot be modified, but can be deleted. Soft locks are generally used to lock older versioned PublicObjects. Older versions should not be modified, but can be deleted.
• User lock - only the lock holder can modify the PublicObject. A PublicObject has a user lock when it is "checked-out". This prevents any other user from modifying the PublicObject until it is checked back in and unlocked.
• Timed lock - used primarily by the WebDAV protocol. A lock is held until the time expires. Upon expiration, the PublicObject is automatically unlocked by the LockAgent.
• Session lock - used primarily by the iFS system. The lock is discarded whenever the session ends.

  The LockHolder attribute refers to the DirectoryUser that holds the USERLOCK and is implicitly set for User Lock. Similarly, the LockedForSession attribute is the id of the session that holds the SESSIONLOCK and is implicitly set for Session Lock.

  The LockState attribute is not updateable. Going from one LockState to another using PublicObject.lock(LockObjectDefinition lodef) method results in a new LockObject being created. The old LockObject is orphaned. Orphaned LockObjects are freed by the GarbageCollectionAgent.

  A LockObject can be multiply referenced by several PublicObjects. The PublicObject.lock(LockObject lo) method enables one to share LockObjects.

  A LockObject can be updated using the PublicObject.updateLock(LockObject lo) method. When the PublicObject.unlock() method is invoked, the LockObject attribute on the PublicObject is set to null. The LockObject is orphaned and freed by the GarbageCollectionAgent.

  Since the LockObject is a SystemObject, it can only be explicitly created and updated by administrators. They are otherwise created in the context of locking operations through special system options.

  The semantics discussed in the method descriptions below for managing locks on a PublicObject reflect the out-of-the-box locking behavior. The policy for locking/unlocking a PublicObject in various lockstates; modifying and freeing a locked PublicObject can be changed by modifying the Policy on the ClassObject representing that PublicObject. You can also change the Policy for a specific instance, if desired.

  To define a new policy with a custom semantic, construct a Policy object using the API. Details on how to create a new policy are in the Developer's Guide. The OPERATION attribute for the Policy must equal the OPERATION for which you are trying to change the semantic. The implementation for the policy must reside in the server side subclass of LockObject class, i.e. S_TieLockObject or its subclass. The implementation method must also take a server side S_PublicObject as a parameter and be public. The implementation is dynamically invoked.

  The policy can be associated with the ClassObject representing the PublicObject or the instance by using LibraryObject.putPolicy(Policy po). Associating the Policy with the ClassObject affects the behavior for all PublicObjects in the system. Associating the Policy with the instance only applies the policy for that specific instance.

  See Also:

  Policy

  Field Summary

  static java.lang.String	CLASS_NAME This class name for this class.
  static java.lang.String	LOCKEDFORSESSION_ATTRIBUTE Indicates the Long id of the session that holds the lock.
  static java.lang.String	LOCKHOLDER_ATTRIBUTE Indicates the DirectoryUser that is the owner of the lock and is used for USERLOCK's.
  static java.lang.String	LOCKSTATE_ATTRIBUTE Indicates the integer constant state of the lock and is the type of lock on this object.
  static int	LOCKSTATE_HARDLOCK Represents a HardLock state.
  static int	LOCKSTATE_SESSIONLOCK Represents a SessionLock state.
  static int	LOCKSTATE_SOFTLOCK Represents a SoftLock state.
  static int	LOCKSTATE_USERLOCK Represents a UserLock state.
  static java.lang.String	LOCKTIMEOUT_ATTRIBUTE The actual time at which the lock on a publicobject should auto-expire.

  Fields inherited from class oracle.ifs.beans.SystemObject

  ACTIVE_ATTRIBUTE, POLICYBUNDLE_ATTRIBUTE, PROPERTYBUNDLE_ATTRIBUTE

  Method Summary

  DirectoryUser	getLockHolder() Returns the directory user who holds the lock on the PublicObject(s) (that refer to this lockobject)
  int	getLockState() Returns the lock state of this object
  java.lang.String	getLockStateLabel() Gets the localized String label for the LockState set for this instance.
  java.util.Date	getLockTimeOut() Returns the Lock time value for this LockObject.
  PublicObject[]	getReferringPublicObjects() Get the PublicObjects that refer to this LockObject
  PublicObject[]	getReferringPublicObjects(SortSpecification sort) Get the PublicObjects that refer to this LockObject, sorted according to the specified SortSpecification.
  boolean	isLockedForSession() Returns true if the PublicObject that refers to this LockObject has a session lock i.e.
  boolean	isLockedForSessionByCurrentSession() Returns true if there is a session lock held by this object, and it is held by the invoking session.
  boolean	isShared() Checks if this lockobject is referenced by multiple PublicObject's
  void	setLockState(int lockstate) Sets the Lock state of the LockObject
  void	setLockTimeOut(java.util.Date timeout) Sets the Lock time out of the LockObject.
  static java.lang.String	toLockStateLabel(int lockState) Converts the specified LockState constant to a localized label.
  static java.lang.String	toLockStateLabel(int lockState, LibrarySession session) Converts the specified LockState constant to a localized label, using the Localizer from the specified LibrarySession.
  static java.lang.String	toLockStateLabel(int lockState, Localizer localizer) Converts the specified LockState constant to a localized label, using the specified Localizer.

  Methods inherited from class oracle.ifs.beans.SystemObject

  getPolicyBundle, getPropertyBundle, isActive, putPolicy, putProperty, putProperty, removeAllPolicies, removeAllProperties, removePolicy, removePolicy, removeProperty, setActive, setPolicyBundle, setPropertyBundle

  Methods inherited from class oracle.ifs.beans.LibraryObject

  equals, free, free, getAttribute, getAttributeByUpperCaseName, getAttributes, getAttributesByUpperCaseNames, getClassId, getClassObject, getDefinition, getId, getLabel, getName, getSession, handleEvent, hasNameAttribute, invokeServerMethod, isInstanceOf, isTraced, lookupInstanceLabel, postEvent, postEvent, renderAsReader, renderAsStream, setAttribute, setAttribute, setAttributes, setAttributes, setName, toString, trace, update

  Methods inherited from interface oracle.ifs.common.LibraryObjectInterface

  getId

  Methods inherited from interface oracle.ifs.common.Traceable

  getTraceLogger, isTraced, trace

  Field Detail

  CLASS_NAME

  public static final java.lang.String CLASS_NAME

  This class name for this class. Useful for methods that take a class name argument.

  LOCKTIMEOUT_ATTRIBUTE

  public static final java.lang.String LOCKTIMEOUT_ATTRIBUTE

  The actual time at which the lock on a publicobject should auto-expire. Represented as a date.

  LOCKHOLDER_ATTRIBUTE

  public static final java.lang.String LOCKHOLDER_ATTRIBUTE

  Indicates the DirectoryUser that is the owner of the lock and is used for USERLOCK's.
  This will be implicitly set for UserLock's and is not settable directly on the object.

  LOCKSTATE_ATTRIBUTE

  public static final java.lang.String LOCKSTATE_ATTRIBUTE

  Indicates the integer constant state of the lock and is the type of lock on this object. The different states control the circumstances under which this object can be modified and/or deleted.

  LOCKEDFORSESSION_ATTRIBUTE

  public static final java.lang.String LOCKEDFORSESSION_ATTRIBUTE

  Indicates the Long id of the session that holds the lock. This will be implicitly set for SessionLock's and is not settable.

  LOCKSTATE_HARDLOCK

  public static final int LOCKSTATE_HARDLOCK

  Represents a HardLock state. No modifications or deletions are allowed on a hard locked PublicObject.

  A PublicObject can be hard locked by either:

  • an administrator
  • a user with Lock and Update permission on the PublicObject

  A PublicObject that is hard locked can be unlocked by an administrator or by a user with Unlock and Update permission.

  A PublicObject can be hard locked if it is currently:

  • unlocked
  • user locked by current user
  • session locked by current session

  If the current state is soft lock, the PublicObject has to first be unlocked before attempting a hard lock.

  To share a LockObject that is in the hard lock state using the PublicObject.lock(LockObject lo), the user must have Lock permission in the ACL of the PublicObject that is going to share the LockObject.

  To update a LockObject that is in hard lock state using the PublicObject.updateLock(LockObjectDefinition lodef) method, the user must have Lock permission in the ACL of the PublicObject that is referred to by this LockObject.

  LOCKSTATE_SOFTLOCK

  public static final int LOCKSTATE_SOFTLOCK

  Represents a SoftLock state. No modifications are allowed on a soft locked PublicObject.

  A PublicObject can be soft locked by either:

  • an administrator
  • a user with Lock and Update permission on the PublicObject

  A PublicObject that is soft locked can be unlocked by an administrator or by a user with unlock and Update permission.

  A PublicObject can be soft locked if it is currently:

  • unlocked
  • user locked by current user
  • session locked by current session

  If current state is hard lock, the PublicObject has to first be unlocked before attempting a soft lock.

  To share a LockObject that is in the soft lock state using the PublicObject.lock(LockObject lo), the user must have the Lock permission in the ACL of the PublicObject that is going to share the LockObject.

  To update a LockObject that is in the soft lock state using the PublicObject.updateLock(LockObjectDefinition lodef) method, the user must have Lock permission in the ACL of the PublicObject that is referred to by this LockObject.

  iFS uses soft locks in its default versioning policy to prevent previous versions from being modified.

  LOCKSTATE_USERLOCK

  public static final int LOCKSTATE_USERLOCK

  Represents a UserLock state. No modifications or deletions are allowed by anyone other than the user holding the lock.

  A PublicObject can be user locked by:

  • an administrator
  • a user with Update permission

  A PublicObject that is user locked can be unlocked by the user who locked it or by an administrator.

  A PublicObject can be user locked if it is currently:

  • unlocked
  • session locked by current session

  If the current state is hard or soft locked, the PublicObject cannot be user locked. It will have to first be unlocked.

  To share a LockObject that is in the user locked state using the PublicObject.lock(LockObject lo) method, the user requesting to share the lock must be the LockHolder on this LockObject.

  To update a LockObject that is in the user locked state using the PublicObject.updateLock(LockObjectDefinition lodef) method, the user requesting to update the lock must be the LockHolder on this LockObject.

  iFS uses the user lock state to lock Family, VersionSeries, VersionDescription and Document upon checking out a versioned document in its default versioning policy.

  LOCKSTATE_SESSIONLOCK

  public static final int LOCKSTATE_SESSIONLOCK

  Represents a SessionLock state. No modifications or deletions are allowed by anyone other than the session holding the session lock.

  A PublicObject can be session locked by:

  • an administrator
  • a user with update permission.

  A PublicObject that is session locked can only be unlocked by the session that holds the lock or by an administrator.

  If the session ends without unlocking the session lock on a PublicObject, iFS automatically releases the lock on the PublicObject.

  A PublicObject can be session locked if it is currently:

  • unlocked
  • user locked by the user who owns the current session

  If the current state is hard or soft locked, a PublicObject cannot be session locked. It will have to first be unlocked.

  To share a LockObject that is in the session lock state using the PublicObject.lock(LockObject lo) method, the session id of the session requesting to share the lock must be same as the LockedForSession attribute value on this LockObject.

  To update a LockObject that is in the session lock state using the PublicObject.updateLock(LockObjectDefinition lodef) method, the session id of the session requesting to update the lock must be the same as the LockedForSession attribute value on this LockObject.

  Method Detail

  getLockTimeOut

  public java.util.Date getLockTimeOut()
                                throws IfsException

  Returns the Lock time value for this LockObject. That is the time at which the lock on the PublicObject (that refers to this LockObject) automatically expires.

  Returns:

  the time at which the lock should automatically expire

  Throws:

  IfsException - if operation fails

  setLockTimeOut

  public void setLockTimeOut(java.util.Date timeout)
                      throws IfsException

  Sets the Lock time out of the LockObject. It is the actual time at which the lock on the PublicObject (that refers to this LockObject) automatically expires.

  Parameters:

  timeout - the actual time at which the lock should expire

  Throws:

  IfsException - if operation fails

  getLockState

  public int getLockState()
                   throws IfsException

  Returns the lock state of this object

  Returns:

  The integer lock state

  Throws:

  IfsException - if operation fails.

  setLockState

  public void setLockState(int lockstate)
                    throws IfsException

  Sets the Lock state of the LockObject

  Parameters:

  int - lockstate the integer value for the lockstate

  Throws:

  IfsException - if operation fails

  getLockHolder

  public DirectoryUser getLockHolder()
                              throws IfsException

  Returns the directory user who holds the lock on the PublicObject(s) (that refer to this lockobject)

  Returns:

  the lockholder of the User Lock

  Throws:

  IfsException - if operation fails.

  isLockedForSession

  public boolean isLockedForSession()
                             throws IfsException

  Returns true if the PublicObject that refers to this LockObject has a session lock i.e. the LockState of this object is LOCKSTATE_SESSIONLOCK and it has a LockedForSession attribute value that is not 0.

  Returns:

  true if there is a session lock held on this object.

  Throws:

  IfsException - if operation fails.

  isLockedForSessionByCurrentSession

  public boolean isLockedForSessionByCurrentSession()
                                             throws IfsException

  Returns true if there is a session lock held by this object, and it is held by the invoking session.

  Returns:

  true if there is a session lock held by this object, and it is held by the invoking session.

  Throws:

  IfsException - if operation fails.

  getLockStateLabel

  public java.lang.String getLockStateLabel()
                                     throws IfsException

  Gets the localized String label for the LockState set for this instance.

  Returns:

  the label corresponding to the LockState

  Throws:

  IfsException - if operation fails.

  toLockStateLabel

  public static java.lang.String toLockStateLabel(int lockState)
                                           throws IfsException

  Converts the specified LockState constant to a localized label. The default Localizer is used.

  Parameters:

  lockState - the LockState constant.

  Returns:

  the label corresponding to the specified LockState constant.

  Throws:

  IfsException - if operation fails.

  toLockStateLabel

  public static java.lang.String toLockStateLabel(int lockState,
                                                  LibrarySession session)
                                           throws IfsException

  Converts the specified LockState constant to a localized label, using the Localizer from the specified LibrarySession.

  Parameters:

  lockState - the LockState constant

  session - the LibrarySession, whose current Localizer will be used for the conversion

  Returns:

  the label corresponding to the specified LockState constant

  Throws:

  IfsException - if operation fails.

  toLockStateLabel

  public static java.lang.String toLockStateLabel(int lockState,
                                                  Localizer localizer)
                                           throws IfsException

  Converts the specified LockState constant to a localized label, using the specified Localizer. If a null is specified for the Localizer, a temporary Localizer (constructed based on the default Locale) is used for the conversion.

  Parameters:

  lockState - the LockState constant.

  localizer - the Localizer that performs the conversion

  Returns:

  the label corresponding to the specified LockState constant.

  Throws:

  IfsException - if operation fails.

  getReferringPublicObjects

  public PublicObject[] getReferringPublicObjects()
                                           throws IfsException

  Get the PublicObjects that refer to this LockObject

  Returns:

  array of PublicObjects that refer to this lockobject

  Throws:

  IfsException - if operation fails.

  getReferringPublicObjects

  public PublicObject[] getReferringPublicObjects(SortSpecification sort)
                                           throws IfsException

  Get the PublicObjects that refer to this LockObject, sorted according to the specified SortSpecification.

  Parameters:

  sort - specification of how the referring PublicObjects are to be sorted

  Returns:

  array of PublicObjects that refer to this lockobject

  Throws:

  IfsException - if operation fails.

  isShared

  public boolean isShared()
                   throws IfsException

  Checks if this lockobject is referenced by multiple PublicObject's

  Returns:

  boolean indicating if this lockobject is shared by several PublicObject's

  Throws:

  IfsException - if operation fails.