<?xml version="1.0"?>
<!--
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.
-->

<document>

 <properties>
  <title>Commons Lang - User guide</title>
  <author email="dev@commons.apache.org">Commons Documentation Team</author>
 </properties>

 <body>
  <!-- $Id: userguide.xml 1148224 2011-07-19 08:28:56Z bayard $ -->

  <section name='User guide for Commons "Lang"'>
    <div align="center">
      <h1>The Commons <em>Lang</em> Package</h1>
      <h2>Users Guide</h2>
      <br />
      <a href="#Description">[Description]</a>
      <a href="#lang3.">[lang3.*]</a>
      <a href="#lang3.builder.">[lang3.builder.*]</a>
      <a href="#lang3.math.">[lang3.math.*]</a>
      <a href="#lang3.mutable.">[lang3.mutable.*]</a>
      <a href="#lang3.text.">[lang3.text.*]</a>
      <a href="#lang3.time.">[lang3.time.*]</a>
      <a href="#lang3.concurrent.">[lang3.concurrent.*]</a>
      <br /><br />
    </div>
  </section>

  <section name="Description">
   <p>The Commons Lang library provides much needed additions to the standard JDK's java.lang package. Very generic, very reusable components for everyday use.</p>
   <p>The top level package contains various Utils classes, whilst there are various subpackages including math, concurrent and builder. Using the Utils classes is generally simplicity itself. They are the equivalent of global functions in another language, a collection of stand-alone, thread-safe, static methods. In contrast, subpackages may contain interfaces which may have to be implemented or classes which may need to be extended to get the full functionality from the code. They may, however, contain more global-like functions. </p>
   <p>Lang 3.0 is JDK 1.5+; before that Lang was JDK 1.2+. In both cases you can find features of later JDKs being maintained by us and likely to be removed or modified in favour of the JDK in the next major version. Note that Lang 3.0 uses a different package than its predecessors, allowing it to be used at the same time as an earlier version. </p>
   <p>You will find deprecated methods as you stroll through the Lang documentation. These are removed in the next major version. </p>
   <p>Before we begin, it's a good time to mention the Utils classes. They all contain empty public constructors with warnings not to use. This may seem an odd thing to do, but it allows tools like Velocity to access the class as if it were a bean. In other words, yes we know about private constructors and have chosen not to use them. </p>
  </section>

   <section name="lang3.*">
    <subsection name="String manipulation - StringUtils, StringEscapeUtils, RandomStringUtils, Tokenizer, WordUtils">
     <p>Lang has a series of String utilities. The first is StringUtils, oodles and oodles of functions which tweak, transform, squeeze and cuddle java.lang.Strings. In addition to StringUtils, there are a series of other String manipulating classes; RandomStringUtils, StringEscapeUtils and Tokenizer. RandomStringUtils speaks for itself. It's provides ways in which to generate pieces of text, such as might be used for default passwords. StringEscapeUtils contains methods to escape and unescape Java, JavaScript, HTML, XML and SQL. Tokenizer is an improved alternative to java.util.StringTokenizer. </p>
     <p>These are ideal classes to start using if you're looking to get into Lang. StringUtils' capitalize, substringBetween/Before/After, split and join are good methods to begin with. If you use java.sql.Statements a lot, StringEscapeUtils.escapeSql might be of interest. </p>
     <p>In addition to these classes, WordUtils is another String manipulator. It works on Strings at the word level, for example WordUtils.capitalize will capitalize every word in a piece of text. WordUtils also contains methods to wrap text. </p>
    </subsection>

    <subsection name="Character handling - CharSetUtils, CharSet, CharRange, CharUtils">
     <p>In addition to dealing with Strings, it's also important to deal with chars and Characters. CharUtils exists for this purpose, while CharSetUtils exists for set-manipulation of Strings. Be careful, although CharSetUtils takes an argument of type String, it is only as a set of characters. For example, <code>CharSetUtils.delete("testtest", "tr")</code> will remove all t's and all r's from the String, not just the String "tr". </p>
     <p>CharRange and CharSet are both used internally by CharSetUtils, and will probaby rarely be used. </p>
    </subsection>

    <subsection name="JVM interaction - SystemUtils, CharEncoding">
     <p>SystemUtils is a simple little class which makes it easy to find out information about which platform you are on. For some, this is a necessary evil. It was never something I expected to use myself until I was trying to ensure that Commons Lang itself compiled under JDK 1.2. Having pushed out a few JDK 1.3 bits that had slipped in (<code>Collections.EMPTY_MAP</code> is a classic offender), I then found that one of the Unit Tests was dying mysteriously under JDK 1.2, but ran fine under JDK 1.3. There was no obvious solution and I needed to move onwards, so the simple solution was to wrap that particular test in a <code>if(SystemUtils.isJavaVersionAtLeast(1.3f)) {</code>, make a note and move on. </p>
     <p>The CharEncoding class is also used to interact with the Java environment and may be used to see which character encodings are supported in a particular environment. </p>
    </subsection>

    <subsection name="Serialization - SerializationUtils, SerializationException">
     <p>Serialization doesn't have to be that hard! A simple util class can take away the pain, plus it provides a method to clone an object by unserializing and reserializing, an old Java trick.</p>
    </subsection>

    <subsection name="Assorted functions - ObjectUtils, ClassUtils, ArrayUtils, BooleanUtils">
     <p>Would you believe it, ObjectUtils contains handy functions for Objects, mainly null-safe implementations of the methods on java.lang.Object. </p>
     <p>ClassUtils is largely a set of helper methods for reflection. Of special note are the comparators hidden away in ClassUtils, useful for sorting Class and Package objects by name; however they merely sort alphabetically and don't understand the common habit of sorting <code>java</code> and <code>javax</code> first. </p>
     <p>Next up, ArrayUtils. This is a big one with many methods and many overloads of these methods so it is probably worth an in depth look here. Before we begin, assume that every method mentioned is overloaded for all the primitives and for Object. Also, the short-hand 'xxx' implies a generic primitive type, but usually also includes Object. </p>
     <ul>
      <li>ArrayUtils provides singleton empty arrays for all the basic types. These will largely be of use in the Collections API with its toArray methods, but also will be of use with methods which want to return an empty array on error. </li>
      <li><code>add(xxx[], xxx)</code> will add a primitive type to an array, resizing the array as you'd expect. Object is also supported. </li>
      <li><code>clone(xxx[])</code> clones a primitive or Object array. </li>
      <li><code>contains(xxx[], xxx)</code> searches for a primitive or Object in a primitive or Object array. </li>
      <li><code>getLength(Object)</code> returns the length of any array or an IllegalArgumentException if the parameter is not an array. <code>hashCode(Object)</code>, <code>equals(Object, Object)</code>, <code>toString(Object)</code> </li>
      <li><code>indexOf(xxx[], xxx)</code> and <code>indexOf(xxx[], xxx, int)</code> are copies of the classic String methods, but this time for primitive/Object arrays. In addition, a lastIndexOf set of methods exists. </li>
      <li><code>isEmpty(xxx[])</code> lets you know if an array is zero-sized or null. </li>
      <li><code>isSameLength(xxx[], xxx[])</code> returns true if the arrays are the same length. </li>
      <li>Along side the add methods, there are also remove methods of two types. The first type remove the value at an index, <code>remove(xxx[], int)</code>, while the second type remove the first value from the array, <code>remove(xxx[], xxx)</code>. </li>
      <li>Nearing the end now. The <code>reverse(xxx[])</code> method turns an array around. </li>
      <li>The <code>subarray(xxx[], int, int)</code> method splices an array out of a larger array. </li>
      <li>Primitive to primitive wrapper conversion is handled by the <code>toObject(xxx[])</code> and <code>toPrimitive(Xxx[])</code> methods. </li>
     </ul>
     <p>Lastly, <code>ArrayUtils.toMap(Object[])</code> is worthy of special note. It is not a heavily overloaded method for working with arrays, but a simple way to create Maps from literals. </p>
     <h5>Using toMap</h5>
     <source> 
       Map colorMap = MapUtils.toMap(new String[][] {{
           {"RED", "#FF0000"},
           {"GREEN", "#00FF00"},
           {"BLUE", "#0000FF"}
       });
     </source>

     <p>Our final util class is BooleanUtils. It contains various Boolean acting methods, probably of most interest is the <code>BooleanUtils.toBoolean(String)</code> method which turns various positive/negative Strings into a Boolean object, and not just true/false as with Boolean.valueOf. </p>
    </subsection>

    <subsection name="Flotsam - BitField, Validate">
     <p>On reaching the end of our package, we are left with a couple of classes that haven't fit any of the topics so far. </p>
     <p>The BitField class provides a wrapper class around the classic bitmask integer, whilst the Validate class may be used for assertions (remember, we support Java 1.2). </p>
    </subsection>
   </section>

   <section name="lang3.builder.*">
   <!--
   CompareToBuilder
   EqualsBuilder
   HashCodeBuilder
   ReflectionToStringBuilder
   StandardToStringStyle
   ToStringBuilder
   ToStringStyle
   -->
    <p>When you write a hashcode, do you check Bloch's Effective Java? No? You just hack in a quick number? Well HashCodeBuilder will save your day. It, and its buddies (EqualsBuilder, CompareToBuilder, ToStringBuilder), take care of the nasty bits while you focus on the important bits, like which fields will go into making up the hashcode.</p>
   </section>

   <section name="lang3.math.*">
   <!--
   Fraction
   NumberUtils
   RandomUtils
   -->
    <p>Although Commons-Math also exists, some basic mathematical functions are contained within Lang. These include classes to a Fraction class, various utilities for random numbers, and the flagship class, NumberUtils which contains a handful of classic number functions. </p>
    <p>There are two aspects of this package I would like to highlight. The first is <code>NumberUtils.createNumber(String)</code>, a method which does its best to convert a String into a Number object. You have no idea what type of Number it will return, so you should call the relevant <code>xxxValue</code> method when you reach the point of needing a number. NumberUtils also has a related <code>isNumber</code> method. </p>
   </section>

   <section name="lang3.mutable.*">
   <!--
   Mutable
   MutableByte
   MutableDouble
   MutableFloat
   MutableInt
   MutableLong
   MutableObject
   MutableShort
   -->
    <p>New in 2.1, the mutable package provides mutable wrappers for primitive values (such as int, long, etc.) and Object. These wrappers are simiar to the wrappers provided by the Java API, but allow the wrapped value to be changed without needing to create a separate wrapper object.
    </p>
   </section>

   <section name="lang3.text.*">
   <!--
   CompositeFormat
   StrLookup
   StrSubstitutor
   StrBuilder
   StrMatcher
   StrTokenizer
   -->
   <p>The text package was added in Lang 2.2. It provides, amongst other classes, a replacement for StringBuffer named <code>StrBuilder</code>, a class for substituting variables within a String named <code>StrSubstitutor</code> and a replacement for StringTokenizer named <code>StrTokenizer</code>. While somewhat ungainly, the <code>Str</code> prefix has been used to ensure we don't clash with any current or future standard Java classes. </p>
   </section>

   <section name="lang3.time.*">
   <!--
   DateFormatUtils
   DateUtils
   DurationFormatUtils
   FastDateFormat
   StopWatch
   -->
    <p>Lang 2.0 saw the arrival of a time package. It contains some basic utilities for manipulating time (a delorean, police box and grandfather clock?). These include a StopWatch for simple performance measurements and an optimised FastDateFormat class. </p>
    <p>New in Lang 2.1 is the DurationFormatUtils class, which provides various methods for formatting durations. </p>
   </section>

   <section name="lang3.concurrent.*">
   <p>
     In Lang 3.0 a new <em>concurrent</em> package was introduced containing
     interfaces and classes to support programming with multiple threads. Its
     aim is to serve as an extension of the <em>java.util.concurrent</em>
     package of the JDK.
   </p>

   <subsection name="Concurrent initializers">
   <p>
     A group of classes deals with the correct creation and initialization of
     objects that are accessed by multiple threads. All these classes implement
     the <code>ConcurrentInitializer</code> interface which provides just a
     single method:
   </p>
   <source><![CDATA[
public interface ConcurrentInitializer<T> {
    T get() throws ConcurrentException;
}
   ]]></source>
   <p>
     A <code>ConcurrentInitializer</code> produces an object. By calling the
     <code>get()</code> method the object managed by the initializer can be
     obtained. There are different implementations of the interface available
     addressing various use cases:
   </p>
   <p>
     <code>ConstantInitializer</code> is a very straightforward implementation of
     the <code>ConcurrentInitializer</code> interface: An instance is passed an
     object when it is constructed. In its <code>get()</code> method it simply
     returns this object. This is useful, for instance in unit tests or in cases
     when you want to pass a specific object to a component which expects a
     <code>ConcurrentInitializer</code>.
   </p>
   <p>
     The <code>LazyInitializer</code> class can be used to defer the creation of
     an object until it is actually used. This makes sense, for instance, if the
     creation of the object is expensive and would slow down application startup
     or if the object is needed only for special executions. <code>LazyInitializer</code>
     implements the <em>double-check idiom for an instance field</em> as
     discussed in Joshua Bloch's "Effective Java", 2nd edition, item 71. It
     uses <strong>volatile</strong> fields to reduce the amount of
     synchronization. Note that this idiom is appropriate for instance fields
     only. For <strong>static</strong> fields there are superior alternatives.
   </p>
   <p>
     We provide an example use case to demonstrate the usage of this class: A
     server application uses multiple worker threads to process client requests.
     If such a request causes a fatal error, an administrator is to be notified
     using a special messaging service. We assume that the creation of the
     messaging service is an expensive operation. So it should only be performed
     if an error actually occurs. Here is where <code>LazyInitializer</code>
     comes into play. We create a specialized subclass for creating and
     initializing an instance of our messaging service. <code>LazyInitializer</code>
     declares an abstract <code>initialize()</code> method which we have to
     implement to create the messaging service object:
   </p>
   <source><![CDATA[
public class MessagingServiceInitializer
  extends LazyInitializer<MessagingService> {
    protected MessagingService initialize() throws ConcurrentException {
        // Do all necessary steps to create and initialize the service object
        MessagingService service = ...

        return service;
    }
}
   ]]></source>
   <p>
     Now each server thread is passed a reference to a shared instance of our
     new <code>MessagingServiceInitializer</code> class. The threads run in a
     loop processing client requests. If an error is detected, the messaging
     service is obtained from the initializer, and the administrator is
     notified:
   </p>
   <source><![CDATA[
public class ServerThread implements Runnable {
    /** The initializer for obtaining the messaging service. */
    private final ConcurrentInitializer<MessagingService> initializer;

    public ServerThread(ConcurrentInitializer<MessagingService> init) {
        initializer = init;
    }

    public void run() {
        while (true) {
            try {
                // wait for request
                // process request
            } catch (FatalServerException ex) {
                // get messaging service
                try {
                    MessagingService svc = initializer.get();
                    svc.notifyAdministrator(ex);
                } catch (ConcurrentException cex) {
                    cex.printStackTrace();
                }
            }
        }
    }
}
   ]]></source>
   <p>
     The <code>AtomicInitializer</code> class is very similar to
     <code>LazyInitializer</code>. It serves the same purpose: to defer the
     creation of an object until it is needed. The internal structure is also
     very similar. Again there is an abstract <code>initialize()</code> method
     which has to be implemented by concrete subclasses in order to create and
     initialize the managed object. Actually, in our example above we can turn
     the <code>MessagingServiceInitializer</code> into an atomic initializer by
     simply changing the <strong>extends</strong> declaration to refer to
     <code>AtomicInitializer&lt;MessagingService&gt;</code> as super class.
   </p>
   <p>
     The difference between <code>AtomicInitializer</code> and
     <code>LazyInitializer</code> is that the former uses classes from the
     <code>java.util.concurrent.atomic</code> package for its implementation
     (hence the name). This has the advantage that no synchronization is needed,
     thus the implementation is usually more efficient than the one of the
     <code>LazyInitializer</code> class. However, there is one drawback: Under
     high load, if multiple threads access the initializer concurrently, it is
     possible that the <code>initialize()</code> method is invoked multiple
     times. The class guarantees that <code>get()</code> always returns the
     same object though; so objects created accidently are immideately discarded.
   </p>
   <p>
     With <code>AtomicSafeInitializer</code> there is yet another variant
     implementing the lazy initializing pattern. Its implementation is close to
     <code>AtomicInitializer</code>; it also uses atomic variables internally
     and therefore does not need synchronization. The name &quot;Safe&quot; is
     derived from the fact that it implements an additional check which guarantees
     that the <code>initialize()</code> method is called only once. So it
     behaves exactly in the same way as <code>LazyInitializer</code>.
   </p>
   <p>
     Now, which one of the lazy initializer implementations should you use?
     First of all we have to state that is is problematic to give general
     recommendations regarding the performance of these classes. The initializers
     make use of low-level functionality whose efficiency depends on multiple
     factors including the target platform and the number of concurrent threads.
     So developers should make their own benchmarks in scenarios close to their
     specific use cases. The following statements are rules of thumb which have
     to be verified in practice.
   </p>
   <p>
     <code>AtomicInitializer</code> is probably the most efficient implementation
     due to its lack of synchronization and further checks. Its main drawback is
     that the <code>initialize()</code> method can be called multiple
     times. In cases where this is not an issue <code>AtomicInitializer</code> is
     a good choice. <code>AtomicSafeInitializer</code> and
     <code>LazyInitializer</code> both guarantee that the initialization method
     is called only once. Because <code>AtomicSafeInitializer</code> does not
     use synchronization it is probably slightly more efficient than
     <code>LazyInitializer</code>, but the concrete numbers might depend on the
     level of concurrency.
   </p>
   <p>
     Another implementation of the <code>ConcurrentInitializer</code> interface
     is <code>BackgroundInitializer</code>. It is again an abstract base class
     with an <code>initialize()</code> method that has to be defined by concrete
     subclasses. The idea of <code>BackgroundInitializer</code> is that it calls
     the <code>initialize()</code> method in a separate worker thread. An
     application creates a background initializer and starts it. Then it can
     continue with its work while the initializer runs in parallel. When the
     application needs the results of the initializer it calls its
     <code>get()</code> method. <code>get()</code> blocks until the initialization
     is complete. This is useful for instance at application startup. Here
     initialization steps (e.g. reading configuration files, opening a database
     connection, etc.) can be run in background threads while the application
     shows a splash screen and constructs its UI.
   </p>
   <p>
     As a concrete example consider an application that has to read the content
     of a URL - maybe a page with news - which is to be displayed to the user after
     login. Because loading the data over the network can take some time a
     specialized implementation of <code>BackgroundInitializer</code> can be
     created for this purpose:
   </p>
   <source><![CDATA[
public class URLLoader extends BackgroundInitializer<String> {
    /** The URL to be loaded. */
    private final URL url;

    public URLLoader(URL u) {
        url = u;
    }

    protected String initialize() throws ConcurrentException {
      try {
          InputStream in = url.openStream();
          // read content into string
          ...
          return content;
      } catch (IOException ioex) {
          throw new ConcurrentException(ioex);
      }
    }
}
   ]]></source>
   <p>
     An application creates an instance of <code>URLLoader</code> and starts it.
     Then it can do other things. When it needs the content of the URL it calls
     the initializer's <code>get()</code> method:
   </p>
   <source><![CDATA[
URL url = new URL("http://www.application-home-page.com/");
URLLoader loader = new URLLoader(url);
loader.start();  // this starts the background initialization

// do other stuff
...
// now obtain the content of the URL
String content;
try {
    content = loader.get();  // this may block
} catch (ConcurrentException cex) {
    content = "Error when loading URL " + url;
}
// display content
   ]]></source>
   <p>
     Related to <code>BackgroundInitializer</code> is the
     <code>MultiBackgroundInitializer</code> class. As the name implies, this
     class can handle multiplie initializations in parallel. The basic usage
     scenario is that a <code>MultiBackgroundInitializer</code> instance is
     created. Then an arbitrary number of <code>BackgroundInitializer</code>
     objects is added using the <code>addInitializer()</code> method. When adding
     an initializer a string has to be provided which is later used to obtain
     the result for this initializer. When all initializers have been added the
     <code>start()</code> method is called. This starts processing of all
     initializers. Later the <code>get()</code> method can be called. It waits
     until all initializers have finished their initialization. <code>get()</code>
     returns an object of type <code>MultiBackgroundInitializer.MultiBackgroundInitializerResults</code>.
     This object provides information about all initializations that have been
     performed. It can be checked whether a specific initializer was successful
     or threw an exception. Of course, all initialization results can be queried.
   </p>
   <p>
     With <code>MultiBackgroundInitializer</code> we can extend our example to
     perform multiple initialization steps. Suppose that in addition to loading
     a web site we also want to create a JPA entity manager factory and read a
     configuration file. We assume that corresponding <code>BackgroundInitializer</code>
     implementations exist. The following example fragment shows the usage of
     <code>MultiBackgroundInitializer</code> for this purpose:
   </p>
   <source><![CDATA[
MultiBackgroundInitializer initializer = new MultiBackgroundInitializer();
initializer.addInitializer("url", new URLLoader(url));
initializer.addInitializer("jpa", new JPAEMFInitializer());
initializer.addInitializer("config", new ConfigurationInitializer());
initializer.start();  // start background processing

// do other interesting things in parallel
...
// evaluate the results of background initialization
MultiBackgroundInitializer.MultiBackgroundInitializerResults results =
    initializer.get();
String urlContent = (String) results.getResultObject("url");
EntityManagerFactory emf =
    (EntityManagerFactory) results.getResultObject("jpa");
...
   ]]></source>
   <p>
     The child initializers are added to the multi initializer and are assigned
     a unique name. The object returned by the <code>get()</code> method is then
     queried for the single results using these unique names.
   </p>
   <p>
     If background initializers - including <code>MultiBackgroundInitializer</code>
     - are created using the standard constructor, they create their own
     <code>ExecutorService</code> which is used behind the scenes to execute the
     worker tasks. It is also possible to pass in an <code>ExecutorService</code>
     when the initializer is constructed. That way client code can configure
     the <code>ExecutorService</code> according to its specific needs; for
     instance, the number of threads available could be limited.
   </p>
   </subsection>

   <subsection name="Utility classes">
   <p>
     Another group of classes in the new <code>concurrent</code> package offers
     some generic functionality related to concurrency. There is the
     <code>ConcurrentUtils</code> class with a bunch of static utility methods.
     One focus of this class is dealing with exceptions thrown by JDK classes.
     Many JDK classes of the executor framework throw exceptions of type
     <code>ExecutionException</code> if something goes wrong. The root cause of
     these exceptions can also be a runtime exception or even an error. In
     typical Java programming you often do not want to deal with runtime
     exceptions directly; rather you let them fall through the hierarchy of
     method invocations until they reach a central exception handler. Checked
     exceptions in contrast are usually handled close to their occurrence. With
     <code>ExecutionException</code> this principle is violated. Because it is a
     checked exception, an application is forced to handle it even if the cause
     is a runtime exception. So you typically have to inspect the cause of the
     <code>ExecutionException</code> and test whether it is a checked exception
     which has to be handled. If this is not the case, the causing exception can
     be rethrown.
   </p>
   <p>
     The <code>extractCause()</code> method of <code>ConcurrentUtils</code> does
     this work for you. It is passed an <code>ExecutionException</code> and tests
     its root cause. If this is an error or a runtime exception, it is directly
     rethrown. Otherwise, an instance of <code>ConcurrentException</code> is
     created and initialized with the root cause. (<code>ConcurrentException</code>
     is a new exception class in the <code>o.a.c.l.concurrent</code> package.)
     So if you get such a <code>ConcurrentException</code>, you can be sure that
     the original cause for the <code>ExecutionException</code> was a checked
     exception. For users who prefer runtime exceptions in general there is also
     an <code>extractCauseUnchecked()</code> method which behaves like
     <code>extractCause()</code>, but returns the unchecked exception
     <code>ConcurrentRuntimeException</code> instead.
   </p>
   <p>
     In addition to the <code>extractCause()</code> methods there are
     corresponding <code>handleCause()</code> methods. These methods extract the
     cause of the passed in <code>ExecutionException</code> and throw the
     resulting <code>ConcurrentException</code> or <code>ConcurrentRuntimeException</code>.
     This makes it easy to transform an <code>ExecutionException</code> into a
     <code>ConcurrentException</code> ignoring unchecked exceptions:
   </p>
   <source><![CDATA[
Future<Object> future = ...;
try {
    Object result = future.get();
    ...
} catch (ExecutionException eex) {
    ConcurrentUtils.handleCause(eex);
}
   ]]></source>
   <p>
     There is also some support for the concurrent initializers introduced in
     the last sub section. The <code>initialize()</code> method is passed a
     <code>ConcurrentInitializer</code> object and returns the object created by
     this initializer. It is null-safe. The <code>initializeUnchecked()</code>
     method works analogously, but a <code>ConcurrentException</code> throws by the
     initializer is rethrown as a <code>ConcurrentRuntimeException</code>. This
     is especially useful if the specific <code>ConcurrentInitializer</code>
     does not throw checked exceptions. Using this method the code for requesting
     the object of an initializer becomes less verbose. The direct invocation
     looks as follows:
   </p>
   <source><![CDATA[
ConcurrentInitializer<MyClass> initializer = ...;
try {
    MyClass obj = initializer.get();
    // do something with obj
} catch (ConcurrentException cex) {
    // exception handling
}
   ]]></source>
   <p>
     Using the <code>initializeUnchecked()</code> method, this becomes:
   </p>
   <source><![CDATA[
ConcurrentInitializer<MyClass> initializer = ...;
MyClass obj = ConcurrentUtils.initializeUnchecked(initializer);
// do something with obj
   ]]></source>
   <p>
     Another utility class deals with the creation of threads. When using the
     <em>Executor</em> framework new in JDK 1.5 the developer usually does not
     have to care about creating threads; the executors create the threads they
     need on demand. However, sometimes it is desired to set some properties of
     the newly created worker threads. This is possible through the
     <code>ThreadFactory</code> interface; an implementation of this interface
     has to be created and pased to an executor on creation time. Currently, the
     JDK does not provide an implementation of <code>ThreadFactory</code>, so
     one has to start from scratch.
   </p>
   <p>
     With <code>BasicThreadFactory</code> Commons Lang has an implementation of
     <code>ThreadFactory</code> that works out of the box for many common use
     cases. For instance, it is possible to set a naming pattern for the new
     threads, set the daemon flag and a priority, or install a handler for
     uncaught exceptions. Instances of <code>BasicThreadFactory</code> are
     created and configured using the nested <code>Builder</code> class. The
     following example shows a typical usage scenario:
   </p>
   <source><![CDATA[
BasicThreadFactory factory = new BasicThreadFactory.Builder()
    .namingPattern("worker-thread-%d")
    .daemon(true)
    .uncaughtExceptionHandler(myHandler)
    .build();
ExecutorService exec = Executors.newSingleThreadExecutor(factory);
   ]]></source>
   <p>
     The nested <code>Builder</code> class defines some methods for configuring
     the new <code>BasicThreadFactory</code> instance. Objects of this class are
     immutable, so these attributes cannot be changed later. The naming pattern
     is a string which can be passed to <code>String.format()</code>. The
     placeholder <em>%d</em> is replaced by an increasing counter value. An
     instance can wrap another <code>ThreadFactory</code> implementation; this
     is achieved by calling the builder's <code>wrappedFactory()</code> method.
     This factory is then used for creating new threads; after that the specific
     attributes are applied to the new thread. If no wrapped factory is set, the
     default factory provided by the JDK is used.
   </p>
   </subsection>

   <subsection name="Synchronization objects">
   <p>
     The <code>concurrent</code> package also provides some support for specific
     synchronization problems with threads.
   </p>
   <p>
     <code>TimedSemaphore</code> allows restricted access to a resource in a
     given time frame. Similar to a semaphore, a number of permits can be
     acquired. What is new is the fact that the permits available are related to
     a given time unit. For instance, the timed semaphore can be configured to
     allow 10 permits in a second. Now multiple threads access the semaphore
     and call its <code>acquire()</code> method. The semaphore keeps track about
     the number of granted permits in the current time frame. Only 10 calls are
     allowd; if there are further callers, they are blocked until the time
     frame (one second in this example) is over. Then all blocking threads are
     released, and the counter of available permits is reset to 0. So the game
     can start anew.
   </p>
   <p>
     What are use cases for <code>TimedSemaphore</code>? One example is to
     artificially limit the load produced by multiple threads. Consider a batch
     application accessing a database to extract statistical data. The
     application runs multiple threads which issue database queries in parallel
     and perform some calculation on the results. If the database to be processed
     is huge and is also used by a production system, multiple factors have to be
     balanced: On one hand, the time required for the statistical evaluation
     should not take too long. Therefore you will probably use a larger number
     of threads because most of its life time a thread will just wait for the
     database to return query results. On the other hand, the load on the
     database generated by all these threads should be limited so that the
     responsiveness of the production system is not affected. With a
     <code>TimedSemaphore</code> object this can be achieved. The semaphore can
     be configured to allow e.g. 100 queries per second. After these queries
     have been sent to the database the threads have to wait until the second is
     over - then they can query again. By fine-tuning the limit enforced by the
     semaphore a good balance between performance and database load can be
     established. It is even possible to change the number of available permits
     at runtime. So this number can be reduced during the typical working hours
     and increased at night.
   </p>
   <p>
     The following code examples demonstrate parts of the implementation of such
     a scenario. First the batch application has to create an instance of
     <code>TimedSemaphore</code> and to initialize its properties with default
     values:
   </p>
   <source><![CDATA[
TimedSemaphore semaphore = new TimedSemaphore(1, TimeUnit.SECONDS, 100);
   ]]></source>
   <p>
     Here we specify that the semaphore should allow 100 permits in one second.
     This is effectively the limit of database queries per second in our
     example use case. Next the server threads issuing database queries and
     performing statistical operations can be initialized. They are passed a
     reference to the semaphore at creation time. Before they execute a query
     they have to acquire a permit.
   </p>
   <source><![CDATA[
public class StatisticsTask implements Runnable {
    /** The semaphore for limiting database load. */
    private final TimedSemaphore semaphore;

    public StatisticsTask(TimedSemaphore sem, Connection con) {
        semaphore = sem;
        ...
    }

    /**
     * The main processing method. Executes queries and evaluates their results.
     */
    public void run() {
        try {
            while (!isDone()) {
                semaphore.acquire();    // enforce the load limit

                executeAndEvaluateQuery();
            }
        } catch (InterruptedException iex) {
            // fall through
        }
    }
}
   ]]></source>
   <p>
     The important line here is the call to <code>semaphore.acquire()</code>.
     If the number of permits in the current time frame has not yet been reached,
     the call returns immediately. Otherwise, it blocks until the end of the
     time frame. The last piece missing is a scheduler service which adapts the
     number of permits allowed by the semaphore according to the time of day. We
     assume that this service is pretty simple and knows only two different time
     slots: working shift and night shift. The service is triggered periodically.
     It then determines the current time slot and configures the timed semaphore
     accordingly.
   </p>
   <source><![CDATA[
public class SchedulerService {
    /** The semaphore for limiting database load. */
    private final TimedSemaphore semaphore;
    ...

    /**
     * Configures the timed semaphore based on the current time of day. This
     * method is called periodically.
     */
    public void configureTimedSemaphore() {
        int limit;
        if (isWorkshift()) {
            limit = 50;    // low database load
        } else {
            limit = 250;   // high database load
        }

        semaphore.setLimit(limit);
    }
}
   ]]></source>
   <p>
     With the <code>setLimit()</code> method the number of permits allowed for
     a time frame can be changed. There are some other methods for querying the
     internal state of a timed semaphore. Also some statistical data is available,
     e.g. the average number of <code>acquire()</code> calls per time frame. When
     a timed semaphore is no more needed, its <code>shutdown()</code> method has
     to be called.
   </p>
   </subsection>
   </section>
</body>
</document>
