root/trunk/src/java/org/jcoderz/commons/config/ConfigEntityHelper.java

/*
 * $Id$
 *
 * Copyright 2006, The jCoderZ.org Project. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 *
 *    * Redistributions of source code must retain the above copyright
 *      notice, this list of conditions and the following disclaimer.
 *    * Redistributions in binary form must reproduce the above
 *      copyright notice, this list of conditions and the following
 *      disclaimer in the documentation and/or other materials
 *      provided with the distribution.
 *    * Neither the name of the jCoderZ.org Project nor the names of
 *      its contributors may be used to endorse or promote products
 *      derived from this software without specific prior written
 *      permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS" AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS
 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
 * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
package org.jcoderz.commons.config;

import java.util.Collection;

import javax.ejb.ObjectNotFoundException;

import org.jcoderz.commons.InternalErrorException;
import org.jcoderz.commons.EntityNotFoundException;


/**
 * Static access methods for the
 * {@link org.jcoderz.commons.config.ConfigEntity} Entity Bean.
 *
 * With this helper Configuration Entries (ConfigEntity) can be found by
 * there primary key, or all entries will be selected.
 *
 * For performance issues the ConfigEntities are available as common
 * Entity Beans that are readable and writable, and as ReadOnly EntityBeans
 * (ConfigReaderEntity) which are only readable and will be automatically
 * by the application server.
 * Therefore the different finders are provided for both types.
 *
 * The ReadOnly Pattern is generated by ant target 'add-readonly-entities'
 * and its generator task 'make-readonly-beans'.
 *
 */
public final class ConfigEntityHelper
{
   private ConfigEntityHelper ()
   {
      // no instances allowed - only static helper methods
   }

   /**
    * Finds a ConfigEntity by
    * {@link java.lang.String} (primary key).
    * @param id the configuration key id.
    * @return the ConfigEntity denoted by the given PK.
    * @throws EntityNotFoundException if no entity can be found by the
    *       given primary key
    * @throws InternalErrorException if a Remote, Finder or Naming
    *       exception occurs
    */
   public static ConfigEntity findByPrimaryKey (String id)
         throws EntityNotFoundException, InternalErrorException
   {
      return findByPrimaryKey(id, false);
   }

   /**
    * Finds a ConfigEntity as ReadOnly by
    * {@link java.lang.String} (primary key).
    * Remark that this instance is only a ReadOnly entity bean!
    * @param id the configuration key id.
    * @return the ConfigEntity denoted by the given PK.
    * @throws EntityNotFoundException if no entity can be found by the
    *       given primary key
    * @throws InternalErrorException if a Remote, Finder or Naming
    *       exception occurs
    */
   public static ConfigEntity findReadOnlyByPrimaryKey (String id)
         throws EntityNotFoundException, InternalErrorException
   {
      return findByPrimaryKey(id, true);
   }

   /**
    * Returns all participants data.
    * @return a collection with all all participants data.
    * @throws InternalErrorException if a Remote, Finder or Naming
    *       exception occurs
    */
   public static Collection findAll ()
         throws InternalErrorException
   {
      return findAll(false);
   }

   /**
    * Returns all participants data as Read Only instances.
    * Remark that retrieved instances are ReadOnly!
    * @return a collection with all all participants data.
    * @throws InternalErrorException if a Remote, Finder or Naming
    *       exception occurs
    */
   public static Collection findAllReadOnly ()
         throws InternalErrorException
   {
      return findAll(true);
   }

   /**
    * Finds a ConfigEntity by
    * {@link java.lang.String} (primary key).
    * @param id the configuration key id.
    * @param readOnly true, if a read only instance should be retrieved; false
    *       for a read-write instance.
    * @return the ConfigEntity denoted by the given PK.
    * @throws EntityNotFoundException if no entity can be found by the
    *       given primary key
    * @throws InternalErrorException if a Remote, Finder or Naming
    *       exception occurs
    */
   private static ConfigEntity findByPrimaryKey (String id, boolean readOnly)
         throws EntityNotFoundException, InternalErrorException
   {
      final ConfigEntityPK pk = new ConfigEntityPK(id.toString());
      ConfigEntity result;
      try
      {
         if (!readOnly)
         {
            result = ConfigEntityUtil.getHome().findByPrimaryKey(pk);
         }
         else
         {
            result = ConfigReaderEntityUtil.getHome().findByPrimaryKey(pk);
         }
      }
      catch (ObjectNotFoundException e)
      {
         throw new EntityNotFoundException(ConfigEntityBean.TABLE_NAME,
               "findByPrimaryKey", id, ConfigEntityBean.class.getName(),
               e);
      }
      // remaining exceptions: Remote, Finder, Naming
      catch (Exception e)
      {
         throw new InternalErrorException("DB access failed", e);
      }
      return result;
   }

   /**
    * Returns all participants data.
    * @param readOnly true, if Entity Beans should be ReadOnly. False for
    *       read-write instances.
    * @return a collection with all all participants data.
    * @throws InternalErrorException if a Remote, Finder or Naming
    *       exception occurs
    */
   public static Collection findAll (boolean readOnly)
         throws InternalErrorException
   {
      Collection result;
      try
      {
         if (!readOnly)
         {
            result = ConfigEntityUtil.getHome().findAll();
         }
         else
         {
            result = ConfigReaderEntityUtil.getHome().findAll();
         }
      }
      // remaining exceptions: Remote, Finder, Naming
      catch (Exception e)
      {
         throw new InternalErrorException("DB access failed", e);
      }
      return result;
   }
}