<?xml version='1.0' encoding='UTF-8'?>
<!--
  JBoss, Home of Professional Open Source
  Copyright 2010, Red Hat Middleware LLC, and individual contributors
  by the @authors tag. See the copyright.txt in the distribution for a
  full listing of individual contributors.

  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 chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" []>
<chapter id="solder-beanutilities">
  <title>Bean Utilities</title>
  <para>
      Solder provides a number of base classes which can be extended to create custom beans. Solder
      also provides bean builders which can be used to dynamically create beans using a fluent API. 
   </para>
  <variablelist>
    <varlistentry>
      <term>
        <code>AbstractImmutableBean</code>
      </term>
      <listitem>
        <para>
               An immutable (and hence thread-safe) bean, whose constructor will substitute specification defaults if
               <code>null</code> is passed for a particular attribute. Subclasses must implement the 
               <code>create()</code> and <code>destroy()</code> methods.
            </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <code>AbstractImmutableProducer</code>
      </term>
      <listitem>
        <para>
               An immutable (and hence thread-safe) abstract class for creating producers. Subclasses must implement
               <code>produce()</code> and <code>dispose()</code>.
            </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <code>BeanBuilder</code>
      </term>
      <listitem>
        <para>
               A builder for creating immutable beans which can read the type and annotations from an 
               <code>AnnotatedType</code>.
            </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <code>Beans</code>
      </term>
      <listitem>
        <para>
               A set of utilities for working with beans.
            </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <code>ForwardingBean</code>
      </term>
      <listitem>
        <para>
               A base class for implementing <code>Bean</code> which forwards all calls to <code>delegate()</code>.
            </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <code>ForwardingInjectionTarget</code>
      </term>
      <listitem>
        <para>
               A base class for implementing <code>InjectionTarget</code> which forwards all calls to <code>delegate()</code>.
            </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <code>ForwardingObserverMethod</code>
      </term>
      <listitem>
        <para>
               A base class for implementing <code>ObserverMethod</code> which forwards all calls to <code>delegate()</code>.
            </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <code>ImmutableBean</code>
      </term>
      <listitem>
        <para>
               An immutable (and hence thread-safe) bean, whose constructor will substitute specification defaults if
               <code>null</code> is passed for a particular attribute. An implementation of 
               <code>ContextualLifecycle</code> may be registered to receive lifecycle callbacks.
            </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <code>ImmutableInjectionPoint</code>
      </term>
      <listitem>
        <para>
               An immutable (and hence thread-safe) injection point.
            </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <code>ImmutableNarrowingBean</code>
      </term>
      <listitem>
        <para>
               An immutable (and hence thread-safe) narrowing bean. Narrowing beans allow you to build a general purpose
               bean (likely a producer method), and register it for a narrowed type (or qualifiers).
            </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <code>ImmutablePassivationCapableBean</code>
      </term>
      <listitem>
        <para>
               An immutable (and hence thread-safe) bean, whose constructor will substitute specification defaults if
               <code>null</code> is passed for a particular attribute. An implementation of 
               <code>ContextualLifecycle</code> may be registered to receive lifecycle callbacks. The bean implements
               <code>PassivationCapable</code>, and an id must be provided.
            </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <code>ImmutablePassivationCapableNarrowingBean</code>
      </term>
      <listitem>
        <para>
               An immutable (and hence thread-safe) narrowing bean. Narrowing beans allow you to build a general purpose
               bean (likely a producer method), and register it for a narrowed type (or qualifiers). The bean implements
               <code>PassivationCapable</code>, and an id must be provided.
            </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term>
        <code>NarrowingBeanBuilder</code>
      </term>
      <listitem>
        <para>
               A builder for creating immutable narrowing beans which can read the type and annotations from an 
               <code>AnnotatedType</code>.
            </para>
      </listitem>
    </varlistentry>
  </variablelist>
  <para>
      The use of these classes is in general trivially understood with an understanding of basic programming patterns
      and the CDI specification, so no in depth explanation is provided here. The JavaDoc for each class and method 
      provides more detail.
   </para>
</chapter>
