You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by oz...@apache.org on 2007/08/19 17:39:09 UTC
svn commit: r567415 - in /commons/proper/transaction/branches/TRANSACTION_2:
./ src/java/org/apache/commons/transaction/file/
src/java/org/apache/commons/transaction/locking/
src/java/org/apache/commons/transaction/resource/
Author: ozeigermann
Date: Sun Aug 19 08:39:08 2007
New Revision: 567415
URL: http://svn.apache.org/viewvc?view=rev&rev=567415
Log:
Finished initial version of Javadocs.
Modified:
commons/proper/transaction/branches/TRANSACTION_2/project.properties
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/file/FileResourceManager.java
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/AbstractLockManager.java
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/DefaultHierarchicalLockManager.java
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/HierarchicalLockManager.java
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/LockManager.java
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/RWLockManager.java
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/SimpleLockManager.java
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/package.html
commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/resource/StreamableResource.java
Modified: commons/proper/transaction/branches/TRANSACTION_2/project.properties
URL: http://svn.apache.org/viewvc/commons/proper/transaction/branches/TRANSACTION_2/project.properties?view=diff&rev=567415&r1=567414&r2=567415
==============================================================================
--- commons/proper/transaction/branches/TRANSACTION_2/project.properties (original)
+++ commons/proper/transaction/branches/TRANSACTION_2/project.properties Sun Aug 19 08:39:08 2007
@@ -21,6 +21,8 @@
maven.javadoc.author=false
maven.javadoc.links=http://java.sun.com/javase/6/docs/api/
+maven.javadoc.protected=false
+maven.javadoc.package=false
maven.xdoc.date=left
maven.xdoc.poweredby.image=maven-feather.png
@@ -30,8 +32,8 @@
maven.compile.debug=on
maven.compile.deprecation=off
maven.compile.optimize=off
-maven.compile.source=1.5
-maven.compile.target=1.5
+maven.compile.source=1.6
+maven.compile.target=1.6
# Jar Manifest Additional Attributes
maven.jar.manifest.attributes.list=Implementation-Vendor-Id,X-Compile-Source-JDK,X-Compile-Target-JDK
Modified: commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/file/FileResourceManager.java
URL: http://svn.apache.org/viewvc/commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/file/FileResourceManager.java?view=diff&rev=567415&r1=567414&r2=567415
==============================================================================
--- commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/file/FileResourceManager.java (original)
+++ commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/file/FileResourceManager.java Sun Aug 19 08:39:08 2007
@@ -34,7 +34,14 @@
import org.apache.commons.transaction.util.FileHelper;
/**
- * Default file system implementation of a {@link ResourceManager resource manager}.
+ * Default file system implementation of a
+ * {@link ResourceManager resource manager}.
+ *
+ * <p>
+ * Only two {@link StreamableResource#getProperty(String) properties} are
+ * supported for reading: "lastModified" and "length" . None are supported for
+ * {@link StreamableResource#setProperty(String, Object) setting} or
+ * {@link StreamableResource#readLock() removing}.
*
* <p>
* This implementation is <b>NOT</b> <em>thread-safe</em>. Use
Modified: commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/AbstractLockManager.java
URL: http://svn.apache.org/viewvc/commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/AbstractLockManager.java?view=diff&rev=567415&r1=567414&r2=567415
==============================================================================
--- commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/AbstractLockManager.java (original)
+++ commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/AbstractLockManager.java Sun Aug 19 08:39:08 2007
@@ -28,7 +28,8 @@
import org.apache.commons.transaction.locking.LockException.Code;
/**
- * Abstract implementation of {@link LockManager}.
+ * Abstract implementation of {@link LockManager}. You can use this
+ * implementation as a base for your custom implementations.
*
* <p>
* This implementation is <em>thread-safe</em>.
@@ -66,7 +67,7 @@
throw new IllegalStateException("You need to start work before you can acquire a lock");
}
}
-
+
protected long computeRemainingTime(Thread thread) {
long timeout = effectiveGlobalTimeouts.get(thread);
long now = System.currentTimeMillis();
@@ -79,11 +80,11 @@
}
@Override
- public void lock(M managedResource, K key, boolean exclusive) throws LockException {
+ public void lock(M resourceManager, K key, boolean exclusive) throws LockException {
checkIsStarted();
long remainingTime = computeRemainingTime(Thread.currentThread());
- boolean locked = tryLockInternal(managedResource, key, exclusive, remainingTime,
+ boolean locked = tryLockInternal(resourceManager, key, exclusive, remainingTime,
TimeUnit.MILLISECONDS);
if (!locked) {
throw new LockException(Code.TIMED_OUT, key);
@@ -91,12 +92,12 @@
}
@Override
- public boolean tryLock(M managedResource, K key, boolean exclusive) {
+ public boolean tryLock(M resourceManager, K key, boolean exclusive) {
checkIsStarted();
- return tryLockInternal(managedResource, key, exclusive, 0, TimeUnit.MILLISECONDS);
+ return tryLockInternal(resourceManager, key, exclusive, 0, TimeUnit.MILLISECONDS);
}
- abstract protected boolean tryLockInternal(M managedResource, K key, boolean exclusive,
+ abstract protected boolean tryLockInternal(M resourceManager, K key, boolean exclusive,
long time, TimeUnit unit) throws LockException;
protected void reportTimeout(Thread thread) throws LockException {
@@ -136,7 +137,7 @@
public int hashCode() {
return k.hashCode() + m.hashCode();
}
-
+
public String toString() {
return m.toString() + ":" + k.toString();
}
Modified: commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/DefaultHierarchicalLockManager.java
URL: http://svn.apache.org/viewvc/commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/DefaultHierarchicalLockManager.java?view=diff&rev=567415&r1=567414&r2=567415
==============================================================================
--- commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/DefaultHierarchicalLockManager.java (original)
+++ commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/DefaultHierarchicalLockManager.java Sun Aug 19 08:39:08 2007
@@ -46,7 +46,7 @@
this.lm = lm;
}
- public void lockInHierarchy(M managedResource, String path, boolean exclusive)
+ public void lockInHierarchy(M resourceManager, String path, boolean exclusive)
throws LockException {
// strip off root path
// TODO misses sane checks
@@ -58,12 +58,12 @@
// this is the root path we want to lock
if (relativePath.length() == 0) {
- lock(managedResource, "/", exclusive);
+ lock(resourceManager, "/", exclusive);
return;
}
// always read lock root
- lock(managedResource, "/", false);
+ lock(resourceManager, "/", false);
String[] segments = relativePath.split("\\\\");
StringBuffer currentPath = new StringBuffer(relativePath.length());
@@ -79,10 +79,10 @@
if (i == segments.length - 1) {
// this is the resource itself
- lock(managedResource, key, exclusive);
+ lock(resourceManager, key, exclusive);
} else {
// this is one of the parent path segments
- lock(managedResource, key, false);
+ lock(resourceManager, key, false);
}
}
}
Modified: commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/HierarchicalLockManager.java
URL: http://svn.apache.org/viewvc/commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/HierarchicalLockManager.java?view=diff&rev=567415&r1=567414&r2=567415
==============================================================================
--- commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/HierarchicalLockManager.java (original)
+++ commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/HierarchicalLockManager.java Sun Aug 19 08:39:08 2007
@@ -16,8 +16,36 @@
*/
package org.apache.commons.transaction.locking;
-// Takes care of hierarchical locking with folders and resources
+/**
+ * Interface to manage locks on hierarchically organized resources.
+ *
+ * <p>
+ * Instead of a single key specifying a resource this manager expects a complete
+ * path to it. This path can be used to perform a number of lock requests to
+ * ensure the resource is properly locked inside the hierarchy. Which lock
+ * requests are performed is determined by the specific implementation.
+ *
+ * @see DefaultHierarchicalLockManager
+ */
public interface HierarchicalLockManager<K, M> extends LockManager<K, M> {
-
- public void lockInHierarchy(M managedResource, String path, boolean exclusive) throws LockException;
+
+ /**
+ * Locks a specific resource denoted by a resource manager it holds and a
+ * path. This requests ensures that the resource is properly locked in its
+ * hierarchy, possibly by issuing a number of additional lock requests.
+ *
+ * @param resourceManager
+ * resource manager that tries to acquire a lock
+ * @param path
+ * the complete path to the resource to be locked
+ * @param exclusive
+ * <code>true</code> if this lock shall be acquired in
+ * exclusive mode, <code>false</code> if it can be shared by
+ * other threads
+ * @throws LockException
+ * if the lock could not be acquired, possibly because of a
+ * timeout or a deadlock
+ */
+ public void lockInHierarchy(M resourceManager, String path, boolean exclusive)
+ throws LockException;
}
Modified: commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/LockManager.java
URL: http://svn.apache.org/viewvc/commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/LockManager.java?view=diff&rev=567415&r1=567414&r2=567415
==============================================================================
--- commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/LockManager.java (original)
+++ commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/LockManager.java Sun Aug 19 08:39:08 2007
@@ -20,6 +20,22 @@
import java.util.concurrent.locks.Lock;
/**
+ * Main interface to acquire and manage locks.
+ *
+ * <p>
+ * The idea is that a block of work is done between the calls of
+ * {@link #startWork(long, TimeUnit)} and {@link #endWork()}. Each resource
+ * touched can be locked either by {@link #lock(Object, Object, boolean)} or
+ * {@link #tryLock(Object, Object, boolean)}. In case the timeout given in
+ * {@link #startWork(long, TimeUnit)} is exceeded locking requests are
+ * terminated with a {@link LockException}. Finally, {@link #endWork()}
+ * releases all locks in a bulk.
+ *
+ * <p>
+ * The benefit of such an implementation is that you can no longer forget to
+ * release locks that would otherwise lurk around forever. Additionally, as
+ * there is a central manager for all locks implementations can perform
+ * additional checks like, for example, a deadlock detection.
*
* <p>
* Implementations are free to decide whether they want to make use of the
@@ -29,10 +45,14 @@
*
* <p>
* You can plug in your own lock manager version most easily. However, for
- * advanced features this will most likely require a custom implementation of {@link Lock} as well.
- *
+ * advanced features this will most likely require a custom implementation of
+ * {@link Lock} as well.
*
- * @param <K>
+ * @see RWLockManager
+ * @see HierarchicalLockManager
+ * @see DefaultHierarchicalLockManager
+ * @see AbstractLockManager
+ * @see SimpleLockManager
*/
public interface LockManager<K, M> {
/**
@@ -55,11 +75,37 @@
void endWork();
/**
- * @param managedResource
- * resource for on which this block of work shall be done
+ * Locks a resource denoted by a key and a resource manager.
+ *
+ * @param resourceManager
+ * resource manager that tries to acquire a lock
+ * @param key
+ * the key for the resource to be locked
+ * @param exclusive
+ * <code>true</code> if this lock shall be acquired in
+ * exclusive mode, <code>false</code> if it can be shared by
+ * other threads
+ * @throws LockException
+ * if the lock could not be acquired, possibly because of a
+ * timeout or a deadlock
*/
- void lock(M managedResource, K key, boolean exclusive) throws LockException;
+ void lock(M resourceManager, K key, boolean exclusive) throws LockException;
- boolean tryLock(M managedResource, K key, boolean exclusive);
+ /**
+ * Tries to acquire a lock on a resource denoted by a key and a resource
+ * manager.
+ *
+ * @param resourceManager
+ * resource manager that tries to acquire a lock
+ * @param key
+ * the key for the resource to be locked
+ * @param exclusive
+ * <code>true</code> if this lock shall be acquired in
+ * exclusive mode, <code>false</code> if it can be shared by
+ * other threads
+ * @return <code>true</code> if the lock was acquired, <code>false</code>
+ * otherwise
+ */
+ boolean tryLock(M resourceManager, K key, boolean exclusive);
}
Modified: commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/RWLockManager.java
URL: http://svn.apache.org/viewvc/commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/RWLockManager.java?view=diff&rev=567415&r1=567414&r2=567415
==============================================================================
--- commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/RWLockManager.java (original)
+++ commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/RWLockManager.java Sun Aug 19 08:39:08 2007
@@ -29,6 +29,16 @@
import org.apache.commons.transaction.locking.LockException.Code;
import org.apache.commons.transaction.locking.locks.ResourceRWLock;
+/**
+ * Advanced read/write lock implementation of a {@link LockManager} based on
+ * {@link ResourceRWLock}.
+ *
+ * <p>
+ * <em>Note</em>: This implementation performs deadlock detection.
+ *
+ * <p>
+ * This implementation is <em>thread-safe</em>.
+ */
public class RWLockManager<K, M> extends AbstractLockManager<K, M> implements LockManager<K, M> {
private Log log = LogFactory.getLog(getClass());
@@ -78,11 +88,11 @@
return new ResourceRWLock(name);
}
- protected boolean tryLockInternal(M managedResource, K key, boolean exclusive, long time,
+ protected boolean tryLockInternal(M resourceManager, K key, boolean exclusive, long time,
TimeUnit unit) throws LockException {
reportTimeout(Thread.currentThread());
- KeyEntry<K, M> entry = new KeyEntry<K, M>(key, managedResource);
+ KeyEntry<K, M> entry = new KeyEntry<K, M>(key, resourceManager);
String resourceName = entry.toString();
Modified: commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/SimpleLockManager.java
URL: http://svn.apache.org/viewvc/commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/SimpleLockManager.java?view=diff&rev=567415&r1=567414&r2=567415
==============================================================================
--- commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/SimpleLockManager.java (original)
+++ commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/SimpleLockManager.java Sun Aug 19 08:39:08 2007
@@ -28,7 +28,7 @@
import org.apache.commons.transaction.locking.LockException.Code;
/**
- * Default implementation of {@link LockManager}.
+ * Default implementation of {@link LockManager} based on {@link ReentrantLock}.
*
* <p>
* This is a minimal implementation that only knows a single type of lock.
@@ -49,11 +49,11 @@
return new ReentrantLock();
}
- protected boolean tryLockInternal(M managedResource, K key, boolean exclusive, long time,
+ protected boolean tryLockInternal(M resourceManager, K key, boolean exclusive, long time,
TimeUnit unit) throws LockException {
reportTimeout(Thread.currentThread());
- KeyEntry<K, M> entry = new KeyEntry<K, M>(key, managedResource);
+ KeyEntry<K, M> entry = new KeyEntry<K, M>(key, resourceManager);
ReentrantLock lock = create();
ReentrantLock existingLock = allLocks.putIfAbsent(entry, lock);
Modified: commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/package.html
URL: http://svn.apache.org/viewvc/commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/package.html?view=diff&rev=567415&r1=567414&r2=567415
==============================================================================
--- commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/package.html (original)
+++ commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/locking/package.html Sun Aug 19 08:39:08 2007
@@ -1,6 +1,21 @@
<html>
<body>
-<h1>Locking</h1>
-<p>
+<h1>Locking:</h1>
+
+<p>Central package for locking related stuff. It contains interfaces and implementations to handle your locks in a transactional way. That means you divide your work in blocks and free all locks accumulated in that block at its very end. A common, shared timeout protects all locking requests.
+
+<p>The central interface is the one of the
+<a href="LockManager.html">lock manager</a>.
+It's recommended implementation is the
+<a href="RWLockManager.java">read/write lock manager</a> that
+features read/write locks and efficient deadlock detection.
+
+<p>If you have hierarchical resources to lock you can use the
+<a href="HierarchicalLockManager.html">hierarchical lock manager interface </a>
+with its <a href="DefaultHierarchicalLockManager.html">default implementation</a>.
+
+<p>If you need a custom implementation of a lock mamanger it is recommended
+to base your work on the <a href="AbstractLockManager.html">on an abstract base</a>.
+
</body>
</html>
Modified: commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/resource/StreamableResource.java
URL: http://svn.apache.org/viewvc/commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/resource/StreamableResource.java?view=diff&rev=567415&r1=567414&r2=567415
==============================================================================
--- commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/resource/StreamableResource.java (original)
+++ commons/proper/transaction/branches/TRANSACTION_2/src/java/org/apache/commons/transaction/resource/StreamableResource.java Sun Aug 19 08:39:08 2007
@@ -64,38 +64,184 @@
/**
* Gets the children of the resource.
*
- * @return a list of children (empty if this is a file), never <code>null</code>
- * @throws ResourceException in case anything goes fatally wrong
+ * @return a list of children (empty if this is a file), never
+ * <code>null</code>
+ * @throws ResourceException
+ * in case anything goes fatally wrong
*/
List<? extends StreamableResource> getChildren() throws ResourceException;
+ /**
+ * Gets the parent of this resource, i.e. the directory this resource
+ * resides in or <code>null</code> if this is the root folder.
+ *
+ * @return the parent directory or <code>null</code> if there is none
+ * @throws ResourceException
+ * in case anything goes fatally wrong
+ */
StreamableResource getParent() throws ResourceException;
+ /**
+ * Gets a specific child of this resource. This method returns a resource
+ * even if it does not exist.
+ *
+ * @param name
+ * the name of the child resource
+ * @return the resource object - even if it does not exist
+ * @throws ResourceException
+ * in case anything goes fatally wrong
+ */
StreamableResource getChild(String name) throws ResourceException;
+ /**
+ * Gets the input stream associated to this resource. You are responsible
+ * for closing the stream after using it.
+ *
+ * @return the input stream for reading
+ * @throws ResourceException
+ * in case anything goes fatally wrong
+ */
InputStream readStream() throws ResourceException;
+ /**
+ * Gets the output stream associated to this resource. You are responsible
+ * for closing the stream after using it.
+ *
+ * @param append
+ * determines whether you append to the existing content
+ * @return the output stream for writing
+ * @throws ResourceException
+ * in case anything goes fatally wrong
+ */
OutputStream writeStream(boolean append) throws ResourceException;
+ /**
+ * <em>Physically</em> deletes this resource.
+ *
+ * @throws ResourceException
+ * in case anything goes fatally wrong or you have not been able
+ * to delete the resource
+ */
void delete() throws ResourceException;
+ /**
+ * Moves (or renames) this resource to a new one. If nothing goes wrong this
+ * resource will be deleted afterwards.
+ *
+ * @param destination
+ * the new resource
+ * @throws ResourceException
+ * in case anything goes fatally wrong or you have not been able
+ * to move this resource
+ */
void move(StreamableResource destination) throws ResourceException;
+ /**
+ * Copies this resource to a new one. If nothing goes wrong there will be
+ * two existing resources afterwards.
+ *
+ * @param destination
+ * the new resource
+ * @throws ResourceException
+ * in case anything goes fatally wrong or you have not been able
+ * to copy this resource
+ */
void copy(StreamableResource destination) throws ResourceException;
+ /**
+ * Checks if this resource <em>physically</em> exists.
+ *
+ * @return <code>true</code> if it exists
+ */
boolean exists();
+ /**
+ * Creates this resource or a <em>physical</em> directory. In case there
+ * already is a physical resource having the same name, this request will
+ * fail and throw an exception.
+ *
+ * @throws ResourceException
+ * in case anything goes fatally wrong or you have not been able
+ * to create this resource as a directory
+ */
void createAsDirectory() throws ResourceException;
+ /**
+ * Creates this resource or a <em>physical</em> file. In case there
+ * already is a physical resource having the same name, this request will
+ * fail and throw an exception.
+ *
+ * @throws ResourceException
+ * in case anything goes fatally wrong or you have not been able
+ * to create this resource as a file
+ */
void createAsFile() throws ResourceException;
+ /**
+ * Retrieves a specific property. Which properties there are and whether you
+ * can create new ones depends on the specific implementation.
+ *
+ * @param name
+ * the name of the property
+ * @return the value of the property or <code>null</code> if there is no
+ * such property
+ */
Object getProperty(String name);
- void setProperty(String name, Object newValue);
+ /**
+ * Sets a specific property. Not all implementations support his operation.
+ * If unsupported an exception in thrown.
+ *
+ * @param name
+ * the name of the property
+ * @param newValue
+ * the new value
+ * @throws UnsupportedOperationException
+ * if this operation is not supported by the specific
+ * implementation
+ */
+
+ void setProperty(String name, Object newValue) throws UnsupportedOperationException;
- void removeProperty(String name);
+ /**
+ * Removes a specific property. Not all implementations support his
+ * operation. If unsupported an exception in thrown.
+ *
+ * @param name
+ * the name of the property
+ * @throws UnsupportedOperationException
+ * if this operation is not supported by the specific
+ * implementation
+ */
+ void removeProperty(String name) throws UnsupportedOperationException;
+ /**
+ * Explicitly sets a read lock on this resource. This means no other thread
+ * can write to this resource while this read lock is held. Other threads
+ * are allowed to set further read locks, though.
+ *
+ * <p>
+ * Not all implementations support his operation as it only makes sense in a
+ * transactional environment. There is no <code>unlock</code> operation as
+ * the release of all locks has to be controlled by the transaction manager.
+ *
+ * <p>
+ * If unsupported nothing will happen.
+ */
void readLock();
+ /**
+ * Explicitly sets a write lock on this resource. This means no other thread
+ * can neither write nor read to this resource while this write lock is
+ * held.
+ *
+ * <p>
+ * Not all implementations support his operation as it only makes sense in a
+ * transactional environment. There is no <code>unlock</code> operation as
+ * the release of all locks has to be controlled by the transaction manager.
+ *
+ * <p>
+ * If unsupported nothing will happen.
+ */
void writeLock();
}