<?xml version="1.0" encoding="UTF-8"?>
<!--
  Copyright 2002-2004 The Apache Software Foundation or its licensors,
  as applicable.
  
  Licensed 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.
-->
<!DOCTYPE document PUBLIC "-//WAMBLEE.ORG//ENTITIES Include Extension for Xdoc V1//EN"
"includeExtension-v1.dtd">
<document> 
  <header> 
    <title>Concurrency Design</title> 
  </header> 
  <body> 
    <p>This document explains the requirements and the design of a concurrency framework.</p>
    
    <section>
      <title>Introduction</title>
      
      <p>
        Even though concurrency support is provided as part the Java platform standard edition, 
        this support focusses only on concurrency within a single virtual machine. Therefore, 
        separate concurrency support is required that can be used transparently within a standard
        single JVM environment as well as in a clustered environment. The current concurrency
        support is implemented only for a single JVM, but implementations for a clustered
        environment are also possible. 
      </p>
      <p>
        The current functionality is really small. It will be extended as soon as more concurrency
        problems are found. 
      </p>
    </section>
    <section id="requirements">
      <title>Requirements</title>
      
      <ol>
        <li>It shall be possible to use reentrant pessimistic locks in a platform 
          independent manner, regardless of whether a clustered environment is
          used or not. </li>
      </ol>
    </section>
    
    <section id="design">
      <title>Design</title>
      <p>
        To cover the requirements <code>Lock</code> interface is provided 
        which is the interface for a single reentrant pessimistic lock. There is one impkementation
        of this lock for within a single JVM environment. It is possible also to provide a lock
        which is suitable within a clustered environment. 
      </p>
      
    </section>
    
    <section id="structure">
      <title>Structure</title>
      
      <section>
        <title>Package Overview</title>
        
        <p>
          Concurrency support is provided in a single package. 
        </p>
        <figure src="../umlpictures/class-diagram-org.wamblee.concurrency.packages.jpg" 
          alt="Package overview." />
        
      </section>
      
      <section>
        <title>Locking</title>
        
        <p>
          The <code>JvmLock</code> class is the implementation of the <code>Lock</code> interface
          for within a single JVM environment. It uses the standard <code>ReentrantLock</code> class
          from the Java runtime environment for its implementation. In addition, a <code>LockAdvice</code>
          class is present by which method invocations can be automatically guarded by a lock using
          AOP. 
        </p>
        <figure src="../umlpictures/class-diagram-org.wamblee.concurrency.lock.jpg" 
          alt="Lock interface and implementation. " />
        
      </section>
      
    </section>
    
    <section id="dynamics">
      <title>Dynamics</title>
      
      <p>Since the current design is trivial, no sequence diagrams are provided. </p>
      
    </section>
    
    <section>
      <title>Design Rules</title>
      
      <p>
        To use the concurrency support effectively, the following rules should be followed:
      </p>
      <ul>
        <li>Beware that pessimistic locking is not suitable for cases with high concurrency,
          especially when used in a clustered environment. In cases of high concurrency, consider
          alternative approaches to pessimistic locking, such as optimistic locking or serialization
          in combination with batch processing.</li>
      </ul>
    </section>
    
  </body>
</document>
