View Javadoc

    1   /* Copyright 2004, 2005 Acegi Technology Pty Limited
    2    *
    3    * Licensed under the Apache License, Version 2.0 (the "License");
    4    * you may not use this file except in compliance with the License.
    5    * You may obtain a copy of the License at
    6    *
    7    *     http://www.apache.org/licenses/LICENSE-2.0
    8    *
    9    * Unless required by applicable law or agreed to in writing, software
    10   * distributed under the License is distributed on an "AS IS" BASIS,
    11   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12   * See the License for the specific language governing permissions and
    13   * limitations under the License.
    14   */
    15
    16  package org.acegisecurity.domain.dao;
    17
    18  /***
    19   * Indicates an implementation capable of initializing an object, such that
    20   * any lazy loading is guaranteed to have been completed.
    21   *
    22   * <p>
    23   * Structured as a separate interface (rather than a subclass of
    24   * <code>Dao</code>), as it is not required for all persistence strategies.
    25   * </p>
    26   *
    27   * <p>In general the recommended approach to lazy initialization is as follows:
    28   *
    29   * <ul>
    30   *
    31   * <li>Do not use OpenSessionInView. You can use it if you like, but you'll have
    32   * less difficulty in the long-run if you plan your use cases and adopt the other
    33   * recommendations below.</li>
    34   *
    35   * <li>Set your mapping documents to use lazy initialization where possible. Only
    36   * mark an association as eager loaded if <b>every</b> single use case requires it
    37   * and you are happy with this eager loading being reflected in a mapping document
    38   * instead of Java code.</li>
    39   *
    40   * <li>Subclass the <code>Dao</code> implementation and add use case specific finder/read
    41   * methods that will use the persistence engine's eager loading capabilities. <b>Generally
    42   * this approach will deliver the best overall application performance</b>, as you will
    43   * (i) only be eager loading if and when required and (ii) you are directly using the
    44   * persistence engine capabilities to do so. It also places the eager loading management
    45   * in the <code>Dao</code>, which is an ideal location to standardise it.</li>
    46   *
    47   * <li>If you would prefer to achieve persistence engine independence and/or reduce
    48   * the number of <code>Dao</code> subclasses that exist in your application, you may
    49   * prefer to modify your services layer so that it uses the <code>InitializationCapable</code>
    50   * interface. However, this interface should be used judiciously given that it does
    51   * not allow the persistence engine to optimise eager loading for given use cases
    52   * and (probably) will lead to a mixture of places where fetching logic can be obtained.</li>
    53   *
    54   * <p>Generally your best strategy is subclassing the <code>Dao</code>. It means the
    55   * most code, but it's also by far the most efficient and offers flexibility to further
    56   * fine-tune specific use cases. Whichever way you go, try to be consistent throughout
    57   * your application (this will ease your future migration and troubleshooting needs).
    58   *
    59   * @author Ben Alex
    60   * @version $Id: InitializationCapable.java,v 1.4 2005/11/17 00:55:47 benalex Exp $
    61   */
    62  public interface InitializationCapable {
    63      //~ Methods ================================================================
    64
    65      /***
    66       * Initializes the indicated object.
    67       *
    68       * <p>
    69       * May throw an exception if the implementation so desires.
    70       * </p>
    71       *
    72       * @param entity to initialize
    73       */
    74      public void initialize(Object entity);
    75
    76  	/***
    77  	 * Indicaets whether the passed object is initialized or not.
    78  	 *
    79  	 * @param entity to determine if initialized
    80  	 * @return <code>true</code> if initialized, <code>false</code> is uninitialized or
    81  	 * 		   the initialization status is unknown
    82  	 */
    83  	public boolean isInitialized(Object entity);
    84  }