public interface ResourceLockManager
ResourceLockManager rlm = IOAPI.getAPI().getResourceLockManager(); String identifier = rlm.obtainLock( new URI("http://www.escenic.com/"), "header", // fragment 86400*1000, // lock only valid for one day "I am working on this right now" // comment );The lock may now be acted upon. Typically this includes sending the identifier to other services that want to verify the contents of the lock. Clients that want to find out what is behind the identifier may use the get() method. The identifier is your unique handle to this lock and should be kept private to the client that obtained the lock. Think of it as the password for this particular resource lock. Using the identifier it is possible to refresh and release the lock. It is not possible to obtain the identifier in any other way than
obtainLock()
ResourceLock lock = rlm.get(identifier);The
lock
variable now contains all the information about the lock, such as the URI, the fragment identifiers
and so on, and can be used by clients to verify that the operation they want to perform matches the locks they have
acquired.
List<ResourceLock> locks = rlm.getLocks("http://www.escenic.com"/);Other clients (not holding the lock's identifier) may also obtain a list of resource locks, however the resource lock will not expose its internal identifier. Using the resource lock it is only possible to see which fragments have been locked, and to force a release by passing the
ResourceLock
to breakLock()
:
if (! locks.isEmpty()) { rlm.forceRelease(locks.get(0)); }
Modifier and Type | Method and Description |
---|---|
boolean |
forceRelease(ResourceLock pResourceLock)
Releases the resource, or part of the resource forcibly disregarding any locks that have been obtained elsewhere.
|
ResourceLock |
get(String pLockHandle)
Looks up an existing lock and returns the
ResourceLock which represents that lock. |
List<ResourceLock> |
getLocks(URI pURI)
Returns the list of all locks that exist for the given resource.
|
boolean |
isLocked(URI pURI)
Check whether a resource, identified by URI, is locked or not.
|
String |
obtainExclusiveLock(URI pURI,
List<String> pLockHandles,
long pMillisToLive,
String pMessage)
Acquires a system wide lock for an entire resource.
|
String |
obtainLock(URI pURI,
List<String> pFragments,
long pMillisToLive,
String pMessage)
Acquires a system wide lock for an entire resource or one or more fragments in question.
|
void |
refresh(String pLockHandle,
long pMillisToLive)
Updates an existing lock identified by
pIdentifie r and updates its time-to-live accordingly. |
boolean |
release(String pLockHandle)
Releases the given lock identified by the given identifier.
|
String obtainLock(URI pURI, List<String> pFragments, long pMillisToLive, String pMessage) throws AlreadyLockedException, IllegalArgumentException
Acquires a system wide lock for an entire resource or one or more fragments in question.
The URI can be any valid URI but cannot contain a fragment identifier. If pUri
has a a fragment
identifier then IllegalArgumentException
is thrown.
If fragments is null
then the entire resource is locked. A valid fragment is a fragment identifier as
per the URI specification.
After a successful lock, the method returns the lock identifier which uniquely identifies this lock. The
details of the resource lock may be obtained by passing it to the get(String)
method.
The returned identifier identifies the resource lock and must be kept by the client in order for the client to be able to continue working with the locks.
The client must specify how long the lock is to be kept alive before being removed by the server. The client should specify a meaningful length of time. This is purely a safety measure allowing the locks to be alive for a while even if the client has lost its connection to the server or is temporarily inaccessible. The server will keep the lock for the specified amount of time and will be removed afterwards.
The server may also impose a hard limit on the length of time it wants to keep locks around. If pMillisToLive
exceeds this limit it is simply capped to that limit.
pURI
- the URI of the resource to lock; the URI cannot contain fragment identifierspFragments
- A list of fragment identifiers, or null
for a full resource lockpMillisToLive
- The time (in milliseconds) that the lock should exist. pMillisToLive
must be >= 1.pMessage
- A message from the client, or null
for no messageAlreadyLockedException
- if the lock is incompatible with other locks on the same resourceIllegalArgumentException
- if pUri
is null
or has a fragment identifier, or if pMillis
is less than 1, or if pFragments
contains illegal fragment
identifiers.String obtainExclusiveLock(URI pURI, List<String> pLockHandles, long pMillisToLive, String pMessage) throws AlreadyLockedException, IllegalArgumentException
Acquires a system wide lock for an entire resource.
The URI can be any valid URI but cannot contain a fragment identifier. If pUri
has a a fragment
identifier then IllegalArgumentException
is thrown.
After a successful lock, the method returns the lock identifier which uniquely identifies this lock. The
details of the resource lock may be obtained by passing it to the get(String)
method.
The returned identifier identifies the resource lock and must be kept by the client in order for the client to be able to continue working with the locks.
The client must specify how long the lock is to be kept alive before being removed by the server. The client should specify a meaningful length of time. This is purely a safety measure allowing the locks to be alive for a while even if the client has lost its connection to the server or is temporarily inaccessible. The server will keep the lock for the specified amount of time and will be removed afterwards.
The server may also impose a hard limit on the length of time it wants to keep locks around. If pMillisToLive
exceeds this limit it is simply capped to that limit.
pURI
- the URI of the resource to lock; the URI cannot contain fragment identifierspLockHandles
- A list of already locked handles. The list may be null
.pMillisToLive
- The time (in milliseconds) that the lock should exist. pMillisToLive
must be >= 1.pMessage
- A message from the client, or null
for no messageAlreadyLockedException
- if the lock is incompatible with other locks on the same resourceIllegalArgumentException
- if pUri
is null
or has a fragment identifier, or if pMillis
is less than 1, or if pFragments
contains illegal fragment
identifiers.ResourceLock get(String pLockHandle) throws IllegalOperationException
ResourceLock
which represents that lock.
If the lock does not exist, the method throws an IllegalOperationException
.pLockHandle
- The unique identifier of an existing lock, returned by obtainLock(java.net.URI, java.util.List<java.lang.String>, long, java.lang.String)
IllegalOperationException
- if the lock does not exist.obtainLock(java.net.URI,java.util.List,long,String)
void refresh(String pLockHandle, long pMillisToLive) throws IllegalOperationException
pIdentifie
r and updates its time-to-live accordingly.
The lock will not be removed by the server before the specified amount of time has passed.pLockHandle
- The unique identifier of an existing lock, returned by obtainLock(java.net.URI, java.util.List<java.lang.String>, long, java.lang.String)
pMillisToLive
- The time (in milliseconds) that the lock should exist, pMillisToLive
must be >= 1IllegalOperationException
- if the lock does not exist.obtainLock(java.net.URI,java.util.List,long,String)
boolean release(String pLockHandle)
true
after a
successful refresh. If the method returns false
this is because the lock has been forced open by
another client (using forceRelease(neo.xredsys.api.ResourceLock)
), or deleted by the server when the lock exceeded its time-to-live.pLockHandle
- The unique identifier of an existing lock, returned by obtainLock(java.net.URI, java.util.List<java.lang.String>, long, java.lang.String)
true
if the release was successful, false
if the lock did not existobtainLock(java.net.URI,java.util.List,long,String)
List<ResourceLock> getLocks(URI pURI)
pURI
- The URI of the resourceboolean forceRelease(ResourceLock pResourceLock)
true
after a successful refresh. If the method returns false
this is because
the lock has been forced open by another client (using forceRelease(neo.xredsys.api.ResourceLock)
), or deleted by the server when the
lock exceeded its time-to-live.pResourceLock
- The resource lock to break, usually obtained from getLocks()
.true
if the release was successful, false
if the lock did not existgetLocks(URI)
boolean isLocked(URI pURI)
pURI
- the URI of the resource to checktrue
if the resource, identified by pURI, is locked. false
if the resource is not locked© 1998- 2021 Escenic AS