<?xml version="1.0"?>
<!--
  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.
-->
<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
  <properties>
    <title>design ocncurrency</title>
  </properties>
  <body>
    <section name="Table of contents">
      <macro name="toc">
        <param name="section" value="0"/>
        <param name="fromDepth" value="0"/>
        <param name="toDepth" value="4"/>
      </macro>
      <p>This document explains the requirements and the design of a concurrency framework.</p>
    </section>
    <section name="Introduction">
      <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 name="Requirements">
      <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 name="Design">
      <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 name="Structure">
      <subsection name="Package Overview">
        <p>
          Concurrency support is provided in a single package. 
        </p>
        <img src="../umlpictures/class-diagram-org.wamblee.concurrency.packages.jpg" alt="Package overview."/>
      </subsection>
      <subsection name="Locking">
        <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>
        <img src="../umlpictures/class-diagram-org.wamblee.concurrency.lock.jpg" alt="Lock interface and implementation. "/>
      </subsection>
    </section>
    <section name="Dynamics">
      <p>Since the current design is trivial, no sequence diagrams are provided. </p>
    </section>
    <section name="Design Rules">
      <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>
