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  import org.acegisecurity.domain.PersistableEntity;
    19
    20  import java.io.Serializable;
    21
    22  import java.util.Collection;
    23  import java.util.List;
    24
    25  /***
    26   * Provides fundamental DAO capabilities for a single concrete {@link
    27   * PersistableEntity}, using JDK 1.5 generics.
    28   *
    29   * <P>
    30   * This interface provides a portable approach to Data Access Object (DAO)
    31   * functionality across various object relational persistance solutions.
    32   * </p>
    33   *
    34   * <p>
    35   * It is not envisioned that this interface will provide <b>all</b> data access
    36   * requirements for applications, however it should provide all of the
    37   * standard create, read, update, delete (CRUD) and finder functions that are
    38   * routinely needed. Specialized subclasses (that provide finer-grained
    39   * functionality) of the <code>Dao</code> interface are encouraged.
    40   * </p>
    41   *
    42   * <P>
    43   * A <code>Dao</code> implementation (or a subclass of <code>Dao</code>) should
    44   * be the sole entry point into the persistance layer of an application. The
    45   * persistence layer should only respond to requests from the services layer.
    46   * The services layer is where all transaction demarcation, security
    47   * authorization, casting to and from concrete {@link
    48   * org.acegisecurity.domain.PersistableEntity}s, workflow and business
    49   * logic should take place.
    50   * </p>
    51   *
    52   * <p>
    53   * Each <code>Dao</code> implementation will support one
    54   * <code>PersistableEntity</code> classes only. The supported
    55   * <code>PersistableEntity</code> class must be indicated via the {@link
    56   * #supports(Class)} method.
    57   * </p>
    58   *
    59   * @author Ben Alex
    60   * @version $Id: Dao.java,v 1.7 2005/11/17 00:55:47 benalex Exp $
    61   */
    62  public interface Dao<E extends PersistableEntity> {
    63      //~ Methods ================================================================
    64
    65      /***
    66       * Create a new object, with the current {@link
    67       * PersistableEntity#getInternalId()} value being ignored.
    68       *
    69       * @param value (without the identity property initialized)
    70       *
    71       * @return the value created (with the identity property initialised)
    72       */
    73      public E create(E value);
    74
    75      /***
    76       * Delete an object.
    77       *
    78       * @param value the value to delete
    79       */
    80      public void delete(E value);
    81
    82      /***
    83       * Return all persistent instances, including subclasses.
    84       *
    85       * @return all persistence instances (an empty <code>List</code> will be
    86       *         returned if no matches are found)
    87       */
    88      public List<E> findAll();
    89
    90      /***
    91       * Find a <code>List</code> of <code>PersistableEntity</code>s, searched by
    92       * their identifiers.
    93       *
    94       * @param ids collection of identifiers to locate
    95       *
    96       * @return the values with those identifiers (an empty <code>List</code>
    97       *         will be returned if no matches are found)
    98       */
    99      public List<E> findId(Collection<Serializable> ids);
    100
    101     /***
    102      * Load a persistent instance by its identifier, although some properties
    103      * may be lazy loaded depending on the underlying DAO implementation and/or
    104      * persistence engine mapping document.
    105      *
    106      * @param id the identifier of the persistent instance desired to be
    107      *        retrieved
    108      *
    109      * @return the request item, or <code>null</code> if not found
    110      */
    111     public E readId(Serializable id);
    112
    113 	/***
    114 	 * Loads a persistent instance by its identifier, along with any
    115 	 * lazy loaded properties associated with that instance.
    116 	 *
    117      * @param id the identifier of the persistent instance desired to be
    118      *        retrieved
    119      *
    120      * @return the request item, or <code>null</code> if not found
    121 	 */
    122 	public E readPopulatedId(Serializable id);
    123
    124     /***
    125      * Find persistent instances with properties matching those of the passed
    126      * <code>PersistableEntity</code>.
    127      *
    128      * <P>
    129      * Persistent instances are matched on the basis of query by example.
    130      * Properties whose value is <code>null</code>, empty
    131      * <code>String</code>s, and any <code>Collection</code>s are ignored in
    132      * the query by example evaluation.
    133      * </p>
    134      *
    135      * @param value parameters to filter on (the class of this object will
    136      * be added to the filter)
    137      * @param firstElement the first result (start at zero to obtain all
    138      *        results)
    139      * @param maxElements the maximum number of results desired for this page
    140      *        of the result set
    141      * @param orderByAsc the property name of the
    142      *        <code>PersistableEntity</code> that should be used to order the
    143      *        results
    144      *
    145      * @return the requested page of the result list (a properly formed
    146      *         <code>PaginatedList</code> is returned if no results match)
    147      */
    148     public PaginatedList<E> scroll(E value, int firstElement,
    149         int maxElements, String orderByAsc);
    150
    151     /***
    152      * Find persistent instances with properties matching those of the passed
    153      * <code>PersistableEntity</code>, with a guarantee the returned results
    154      * will have each of the <code>value</code> class' immediate properties
    155      * initialized.
    156      *
    157      * <P>
    158      * Persistent instances are matched on the basis of query by example.
    159      * Properties whose value is <code>null</code>, empty
    160      * <code>String</code>s, and any <code>Collection</code>s are ignored in
    161      * the query by example evaluation.
    162      * </p>
    163      *
    164      * @param value parameters to filter on (the class of this object will
    165      * be added to the filter)
    166      * @param firstElement the first result (start at zero to obtain all
    167      *        results)
    168      * @param maxElements the maximum number of results desired for this page
    169      *        of the result set
    170      * @param orderByAsc the property name of the
    171      *        <code>PersistableEntity</code> that should be used to order the
    172      *        results
    173      *
    174      * @return the requested page of the result list (a properly formed
    175      *         <code>PaginatedList</code> is returned if no results match)
    176      */
    177     public PaginatedList<E> scrollPopulated(E value, int firstElement,
    178         int maxElements, String orderByAsc);
    179
    180 	/***
    181      * Find persistent instances with properties matching those of the passed
    182      * <code>PersistableEntity</code>, ignoring the class of the passed
    183      * <code>PersistableEntity</code> (useful if you pass a superclass, as you
    184      * want to find all subclass instances which match).
    185 	 *
    186      * @param value parameters to filter on (the class of this object will
    187      * NOT be added to the filter)
    188      * @param firstElement the first result (start at zero to obtain all
    189      *        results)
    190      * @param maxElements the maximum number of results desired for this page
    191      *        of the result set
    192      * @param orderByAsc the property name of the
    193      *        <code>PersistableEntity</code> that should be used to order the
    194      *        results
    195      *
    196      * @return the requested page of the result list (a properly formed
    197      *         <code>PaginatedList</code> is returned if no results match)
    198 	 */
    199     public PaginatedList<E> scrollWithSubclasses(E value, int firstElement,
    200 	        int maxElements, String orderByAsc);
    201
    202 	/***
    203      * Find persistent instances with properties matching those of the passed
    204      * <code>PersistableEntity</code>, ignoring the class of the passed
    205      * <code>PersistableEntity</code> (useful if you pass a superclass, as you
    206      * want to find all subclass instances which match). Guarantees the returned
    207      * results will have each of the DAO's <code>supports</code> class' immediate
    208      * properties initialized.
    209 	 *
    210      * @param value parameters to filter on (the class of this object will
    211      * NOT be added to the filter)
    212      * @param firstElement the first result (start at zero to obtain all
    213      *        results)
    214      * @param maxElements the maximum number of results desired for this page
    215      *        of the result set
    216      * @param orderByAsc the property name of the
    217      *        <code>PersistableEntity</code> that should be used to order the
    218      *        results
    219      *
    220      * @return the requested page of the result list (a properly formed
    221      *         <code>PaginatedList</code> is returned if no results match)
    222 	 */
    223     public PaginatedList<E> scrollPopulatedWithSubclasses(E value, int firstElement,
    224 	        int maxElements, String orderByAsc);
    225
    226 	/***
    227      * Indicates whether the DAO instance provides persistence services for the
    228      * specified class.
    229      *
    230      * @param clazz to test, which should be an implementation of
    231      *        <code>PersistableEntity</code>
    232      *
    233      * @return <code>true</code> or <code>false</code>, indicating whether or
    234      *         not the passed class is supported by this DAO instance
    235      */
    236     public boolean supports(Class clazz);
    237
    238     /***
    239      * Update an object.
    240      *
    241      * @param value to update, with the <code>PersistableEntity</code> having a
    242      *        non-<code>null</code> identifier
    243      *
    244      * @return the updated value
    245      */
    246     public E update(E value);
    247 }