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  }