polygene-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From nic...@apache.org
Subject [3/3] zest-qi4j git commit: Adding some documentation to Locking library.
Date Thu, 09 Jul 2015 08:48:03 GMT
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 <hedmann@betfair.com>
Authored: Thu Jul 9 11:44:51 2015 +0300
Committer: Niclas Hedhman <hedmann@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 {}
+}


Mime
View raw message