Adding some documentation to Locking library.
Project: http://git-wip-us.apache.org/repos/asf/zest-qi4j/repo Commit: http://git-wip-us.apache.org/repos/asf/zest-qi4j/commit/4076eae3 Tree: http://git-wip-us.apache.org/repos/asf/zest-qi4j/tree/4076eae3 Diff: http://git-wip-us.apache.org/repos/asf/zest-qi4j/diff/4076eae3 Branch: refs/heads/develop Commit: 4076eae35756a67b472d3f7c17e60a0426662203 Parents: 0553e80 Author: Niclas Hedhman <[email protected]> Authored: Thu Jul 9 11:44:51 2015 +0300 Committer: Niclas Hedhman <[email protected]> Committed: Thu Jul 9 11:44:51 2015 +0300 ---------------------------------------------------------------------- build.gradle | 4 +- libraries/locking/dev-status.xml | 2 +- libraries/locking/src/docs/locking.txt | 39 +++++++++++++++++- .../qi4j/library/locking/ReadLockConcern.java | 5 ++- .../qi4j/library/locking/WriteLockConcern.java | 13 ++---- .../library/locking/DocumentationSupport.java | 42 ++++++++++++++++++++ 6 files changed, 88 insertions(+), 17 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/4076eae3/build.gradle ---------------------------------------------------------------------- diff --git a/build.gradle b/build.gradle index a98aa00..126e4af 100644 --- a/build.gradle +++ b/build.gradle @@ -23,8 +23,8 @@ project.ext { testFailures = [ ] mainClassName = 'org.qi4j.container.Main' groovycMain_mx = "700m" - groovycMain_permSize = "256m" - groovycMain_maxPermSize = "256m" + groovycMain_permSize = "512m" + groovycMain_maxPermSize = "512m" } buildscript { http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/4076eae3/libraries/locking/dev-status.xml ---------------------------------------------------------------------- diff --git a/libraries/locking/dev-status.xml b/libraries/locking/dev-status.xml index f8669b1..f549c99 100644 --- a/libraries/locking/dev-status.xml +++ b/libraries/locking/dev-status.xml @@ -24,7 +24,7 @@ <codebase>stable</codebase> <!-- none, brief, good, complete --> - <documentation>none</documentation> + <documentation>brief</documentation> <!-- none, some, good, complete --> <unittests>some</unittests> http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/4076eae3/libraries/locking/src/docs/locking.txt ---------------------------------------------------------------------- diff --git a/libraries/locking/src/docs/locking.txt b/libraries/locking/src/docs/locking.txt index a39f3c4..6f1f9ee 100644 --- a/libraries/locking/src/docs/locking.txt +++ b/libraries/locking/src/docs/locking.txt @@ -25,8 +25,43 @@ source=libraries/locking/dev-status.xml -------------- -Locking Library +The Locking Library is a simple way to mark method with Read or Write locks, and the details is handled by this +library. + +This library is heavily used in EntityStore implementations. -NOTE: This Library has no documentation yet. Learn how to contribute in <<community-docs>>. include::../../build/docs/buildinfo/artifact.txt[] + +The library creates a +java.util.concurrent.ReentrantReadWriteLock+ which is shared for all methods within the +composite. It then acquires the read or write lock in a concern that is applied to the methods of the composite, which +have the corresponding annotations. + +== +@ReadLock+ == +This annotation will apply the +ReadLockConcern+ to the method, and acquire the +lock.readLock()+ on entry and relase +it on exit of the method. See the +ReentrantReadWriteLock+ for details on how/when to use it and the exact semantics. + +== +@WriteLock+ == +This annotation will apply the +WriteLockConcern+ to the method, and acquire the +lock.writeLock()+ on entry and relase +it on exit of the method. See the +ReentrantReadWriteLock+ for details on how/when to use it and the exact semantics. + +== +LockingAbstractComposite+ == +This composite type is the easiest way to use this library. Simple extend you composite type interface with this +interface and start marking the methods with the above annotations. No other complex assembly is required. + +[source,java] +---- +public interface SomeService + extends ServiceComposite, LockingAbstractComposite +{ +} +---- + +or apply it during assembly, in case that is the only choice (such as existing/external interfaces) + +[snippet,java] +---- +source=libraries/locking/src/test/java/org/qi4j/library/locking/DocumentationSupport.java +tag=assembly +---- + http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/4076eae3/libraries/locking/src/main/java/org/qi4j/library/locking/ReadLockConcern.java ---------------------------------------------------------------------- diff --git a/libraries/locking/src/main/java/org/qi4j/library/locking/ReadLockConcern.java b/libraries/locking/src/main/java/org/qi4j/library/locking/ReadLockConcern.java index 55c96a3..39e8a80 100644 --- a/libraries/locking/src/main/java/org/qi4j/library/locking/ReadLockConcern.java +++ b/libraries/locking/src/main/java/org/qi4j/library/locking/ReadLockConcern.java @@ -66,7 +66,7 @@ public class ReadLockConcern * Fix for this bug: * http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6822370 * - * @param lock + * @param lock the lock to be acquired. */ protected void lock( Lock lock ) { @@ -74,7 +74,8 @@ public class ReadLockConcern { try { - while( !(lock.tryLock() || lock.tryLock( 1000, TimeUnit.MILLISECONDS )) ) + //noinspection StatementWithEmptyBody + while( !lock.tryLock( 1000, TimeUnit.MILLISECONDS ) ) { // On timeout, try again } http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/4076eae3/libraries/locking/src/main/java/org/qi4j/library/locking/WriteLockConcern.java ---------------------------------------------------------------------- diff --git a/libraries/locking/src/main/java/org/qi4j/library/locking/WriteLockConcern.java b/libraries/locking/src/main/java/org/qi4j/library/locking/WriteLockConcern.java index 956919a..f391667 100644 --- a/libraries/locking/src/main/java/org/qi4j/library/locking/WriteLockConcern.java +++ b/libraries/locking/src/main/java/org/qi4j/library/locking/WriteLockConcern.java @@ -44,7 +44,6 @@ public class WriteLockConcern throws Throwable { Lock writeLock = lock.writeLock(); - lock(writeLock); try { @@ -52,14 +51,7 @@ public class WriteLockConcern } finally { - try - { - writeLock.unlock(); - } - catch( Exception e ) - { - e.printStackTrace(); - } + writeLock.unlock(); } } @@ -73,7 +65,8 @@ public class WriteLockConcern { try { - while( !(lock.tryLock() || lock.tryLock( 1000, TimeUnit.MILLISECONDS )) ) + //noinspection StatementWithEmptyBody + while( !lock.tryLock( 1000, TimeUnit.MILLISECONDS ) ) { // On timeout, try again } http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/4076eae3/libraries/locking/src/test/java/org/qi4j/library/locking/DocumentationSupport.java ---------------------------------------------------------------------- diff --git a/libraries/locking/src/test/java/org/qi4j/library/locking/DocumentationSupport.java b/libraries/locking/src/test/java/org/qi4j/library/locking/DocumentationSupport.java new file mode 100644 index 0000000..c227bb7 --- /dev/null +++ b/libraries/locking/src/test/java/org/qi4j/library/locking/DocumentationSupport.java @@ -0,0 +1,42 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.qi4j.library.locking; + +import org.qi4j.bootstrap.AssemblyException; +import org.qi4j.bootstrap.LayerAssembly; +import org.qi4j.bootstrap.ModuleAssembly; +import org.qi4j.bootstrap.layered.ModuleAssembler; + +public class DocumentationSupport +{ +// START SNIPPET: assembly + public class MyModuleAssembler + implements ModuleAssembler{ + + @Override + public ModuleAssembly assemble( LayerAssembly layer, ModuleAssembly module ) + throws AssemblyException + { + module.services( MyService.class ).withTypes( LockingAbstractComposite.class ); + return module; + } + } +// END SNIPPET: assembly + public interface MyService {} +}
