This topic provides code samples for working with lockable objects. For an overview of the Content Engine locking and unlocking mechanism, see Cooperative Locking Concepts.
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 attempting to modify an object, an application participating in cooperative locking must determine the lock status of the object. See Testing for a Lock.
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);
A lock owner can extend the timeout period for an existing lock by calling the updateLock
method, as follows.
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 executed.
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. (This is 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. ...