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.service;
    17
    18  import org.acegisecurity.domain.PersistableEntity;
    19  import org.acegisecurity.domain.dao.PaginatedList;
    20
    21  import java.io.Serializable;
    22
    23  import java.util.Collection;
    24  import java.util.List;
    25
    26  /***
    27   * Provides fundamental services layer capabilities for a single concrete {@link
    28   * PersistableEntity}, using JDK 1.5 generics.
    29   *
    30   * <P>
    31   * This interface provides a remoting protocol compliant approach to accessing
    32   * services layer logic for a given application. A generics-based services
    33   * layer interface decreases development time because the basic CRUD and finder
    34   * operations can be specified in a typesafe fashion that reuses superclass
    35   * code.
    36   * </p>
    37   *
    38   * <p>
    39   * It is not envisioned that this interface will provide <b>all</b> services layer
    40   * functions. The significant value of a services layer is the value-add beyond
    41   * simply fronting the DAO or applying validation/binding logic that is better
    42   * situated in the domain object or its validator. The type of value-adds
    43   * expected to be provided by a services layer include incrementing business
    44   * identifiers (eg an invoice number); generating messages for logging/audit
    45   * purposes (thus such messages are at a business transaction level of granularity,
    46   * instead of DAO/persistence granularity where the overall context of the
    47   * the message becomes unclear); updating related domain objects via
    48   * their respective services layer beans (eg an invoice services layer bean
    49   * would call the general journal services layer bean to create the accrual
    50   * accounting entries); making changes to a domain object that requires
    51   * logic that is unsuitable to put into a validator because it extends
    52   * beyond a single domain object instance or requires access to other persistent
    53   * entities (eg computing taxation appliable to an invoice based on a break-down
    54   * of each item on the order, its delivery destination, and the customer);
    55   * producing messages (eg notify another system the invoice was created or
    56   * email the customer via SMTP); provide a layer to locate transaction and
    57   * security configuration; expose a reasonably protocol-independent interface
    58   * to the application that can be used by a variety of web services and
    59   * client types; ensure any returned objects are eagerly loaded to a well-defined
    60   * interface contract etc.
    61   * </p>
    62   *
    63   * <P>
    64   * A single <code>ImmutableManager</code> implementation will typically exist for each
    65   * {@link org.acegisecurity.domain.PersistableEntity}, particularly given
    66   * a <code>PersistableEntity</code> is allowed to manage multiple
    67   * {@link org.acegisecurity.domain.impl.PersistableValue}s.
    68   * The particular <code>PersistableEntity</code> an implementation supports
    69   * will be expressed by the {@link #supports(Class)} method.
    70   * </p>
    71   *
    72   * <p>No other part of the Domain subproject relies on this interface. If
    73   * you would prefer to write your own services layer interfaces from scratch,
    74   * this is not a problem at all.
    75   *
    76   * @author Ben Alex
    77   * @version $Id: ImmutableManager.java,v 1.2 2005/11/17 00:55:51 benalex Exp $
    78   */
    79  public interface ImmutableManager<E extends PersistableEntity> {
    80      //~ Methods ================================================================
    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      *
    142      * @return the requested page of the result list (a properly formed
    143      *         <code>PaginatedList</code> is returned if no results match)
    144      */
    145     public PaginatedList<E> scroll(E value, int firstElement,
    146         int maxElements);
    147
    148     /***
    149      * Find persistent instances with properties matching those of the passed
    150      * <code>PersistableEntity</code>, with a guarantee the returned results
    151      * will have each of the <code>value</code> class' immediate properties
    152      * initialized.
    153      *
    154      * <P>
    155      * Persistent instances are matched on the basis of query by example.
    156      * Properties whose value is <code>null</code>, empty
    157      * <code>String</code>s, and any <code>Collection</code>s are ignored in
    158      * the query by example evaluation.
    159      * </p>
    160      *
    161      * @param value parameters to filter on (the class of this object will
    162      * be added to the filter)
    163      * @param firstElement the first result (start at zero to obtain all
    164      *        results)
    165      * @param maxElements the maximum number of results desired for this page
    166      *        of the result set
    167      *
    168      * @return the requested page of the result list (a properly formed
    169      *         <code>PaginatedList</code> is returned if no results match)
    170      */
    171     public PaginatedList<E> scrollPopulated(E value, int firstElement,
    172         int maxElements);
    173
    174 	/***
    175      * Find persistent instances with properties matching those of the passed
    176      * <code>PersistableEntity</code>, ignoring the class of the passed
    177      * <code>PersistableEntity</code> (useful if you pass a superclass, as you
    178      * want to find all subclass instances which match).
    179 	 *
    180      * @param value parameters to filter on (the class of this object will
    181      * NOT be added to the filter)
    182      * @param firstElement the first result (start at zero to obtain all
    183      *        results)
    184      * @param maxElements the maximum number of results desired for this page
    185      *        of the result set
    186      *
    187      * @return the requested page of the result list (a properly formed
    188      *         <code>PaginatedList</code> is returned if no results match)
    189 	 */
    190     public PaginatedList<E> scrollWithSubclasses(E value, int firstElement,
    191 	        int maxElements);
    192
    193 	/***
    194      * Find persistent instances with properties matching those of the passed
    195      * <code>PersistableEntity</code>, ignoring the class of the passed
    196      * <code>PersistableEntity</code> (useful if you pass a superclass, as you
    197      * want to find all subclass instances which match). Guarantees the returned
    198      * results will have each of the DAO's <code>supports</code> class' immediate
    199      * properties initialized.
    200 	 *
    201      * @param value parameters to filter on (the class of this object will
    202      * NOT be added to the filter)
    203      * @param firstElement the first result (start at zero to obtain all
    204      *        results)
    205      * @param maxElements the maximum number of results desired for this page
    206      *        of the result set
    207      *
    208      * @return the requested page of the result list (a properly formed
    209      *         <code>PaginatedList</code> is returned if no results match)
    210 	 */
    211     public PaginatedList<E> scrollPopulatedWithSubclasses(E value, int firstElement,
    212 	        int maxElements);
    213
    214 	/***
    215      * Indicates whether the DAO instance provides persistence services for the
    216      * specified class.
    217      *
    218      * @param clazz to test, which should be an implementation of
    219      *        <code>PersistableEntity</code>
    220      *
    221      * @return <code>true</code> or <code>false</code>, indicating whether or
    222      *         not the passed class is supported by this DAO instance
    223      */
    224     public boolean supports(Class clazz);
    225
    226 }