You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@polygene.apache.org by ni...@apache.org on 2015/07/09 10:48:03 UTC
[3/3] zest-qi4j git commit: Adding some documentation to Locking
library.
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 <he...@betfair.com>
Authored: Thu Jul 9 11:44:51 2015 +0300
Committer: Niclas Hedhman <he...@betfair.com>
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 {}
+}