IBM FileNet P8, Version 5.2.1            

Working with Lockable Objects

The following code samples demonstrate operations that use lockable objects. For an overview of the Content Engine locking and unlocking mechanism, see Cooperative Locking.

An application that participates in cooperative locking must lock the object that it wants to modify, make its changes, then unlock the object. See Locking and Unlocking an Object.

While an object is in the locked state, the lock owner can extend the lock's timeout period if necessary. See Extending a Lock.

Before an application attempts to modify an object, an application that participates in cooperative locking must determine the lock status of the object. See Testing for a Lock.

Locking and Unlocking an Object

The following code snippet shows how to lock and unlock a Document object.

Java™ Example

...
   //If the document is not locked, update its properties.
   try
   {
      doc.lock(30, null); //lock the document for 30 seconds
      doc.save(RefreshMode.REFRESH);
   }
   catch (EngineRuntimeException fnEx)
   {
       if (fnEx.getExceptionCode().equals(ExceptionCode.E_OBJECT_LOCKED) )
           System.out.println("This object is currently locked.");
       else System.out.println(fnEx.getMessage() );
      return;
   }

   //Update document properties.
   //We're guaranteed that for the duration of the lock,
   //the property values will not be changed by cooperating applications.
   ...

   //Finished with updates to the document, so unlock it.
   doc.unlock();
   doc.save(RefreshMode.REFRESH);

C# Example

...
   //If the document is not locked, update its properties.
   try
   {
       doc.LockObject(30,null); //lock the document for 30 seconds
       doc.Save(RefreshMode.REFRESH);
   }
   catch (EngineRuntimeException fnEx)
   {
       if (fnEx.GetExceptionCode().Equals(ExceptionCode.E_OBJECT_LOCKED))
           System.Console.WriteLine("This object is currently locked.");
       else System.Console.WriteLine( (fnEx.Message) );
       return;
   }

   //Update document properties.
   //We're guaranteed that for the duration of the lock,
   //the property values will not be changed by cooperating applications.
   ...

   //Finished with updates to the document, so unlock it.
   doc.Unlock();
   doc.Save(RefreshMode.REFRESH);

Extending a Lock

A lock owner can extend the timeout period for an existing lock by calling the updateLock method.

Java Example

doc.updateLock(60); //extend the lock by 60 seconds
doc.save(RefreshMode.REFRESH);

C# Example

doc.UpdateLock(60); //extend the lock by 60 seconds
doc.Save(RefreshMode.REFRESH);

The value of the LockTimeout property of the Containable interface is reset when the updateLock method is successfully called.

Testing for a Lock

The following code snippet shows the recommended way for a cooperative locking application to test for a lock on an object that it wants to modify. (As opposed to the approach of calling the isLocked method as described in Checking Lock Status.) The code locks a Document object and relies on an exception to be thrown if the document is locked by another application. If the object is locked, the application retrieves the following information about the lock: the owner of the lock, the duration of the lock, and the token identifier of the lock.

Java Example

...
   try
   {
      doc.lock(60, null); //lock the document for 30 seconds
      doc.save(RefreshMode.REFRESH);
   }
   catch (EngineRuntimeException fnEx)
   {
       if (fnEx.getExceptionCode().equals(ExceptionCode.E_OBJECT_LOCKED) )
       {
           doc.refresh(); //get current values of document properties from the server
           System.out.println( "This document is currently locked by" + doc.get_LockOwner() + "\n"+
                "for " + doc.get_LockTimeout() + "seconds\n" +
                "and identified by token " + doc.get_LockToken().toString() );
       }
       else System.out.println(fnEx.getMessage() );
       return;
   }

   // If the document is not locked, lock it, modify it, then unlock it.
   ...

C# Example

...
   try
   {
      doc.LockObject(30,null); //lock the document for 30 seconds
      doc.Save(RefreshMode.REFRESH);
   }
   catch (EngineRuntimeException fnEx)
   {
      if (fnEx.GetExceptionCode().Equals(ExceptionCode.E_OBJECT_LOCKED) )
      {
           doc.Refresh(); //get current values of document properties from the server
           System.Console.WriteLine("This document is currently locked by" + doc.LockOwner + "\n" +
              "for " + doc.LockTimeout + "seconds\n" +
              "and identified by token " + doc.LockToken );
      }
      else System.Console.WriteLine(fnEx.Message);
      return;
   }
   
   // If the document is not locked, lock it, modify it, then unlock it.
   ...


Last updated: October 2015
locking_procedures.htm

© Copyright IBM Corporation 2015.