org.acegisecurity.domain.service.ImmutableManager Maven / Gradle / Ivy
/* Copyright 2004, 2005, 2006 Acegi Technology Pty Limited
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.acegisecurity.domain.service;
import org.acegisecurity.domain.PersistableEntity;
import org.acegisecurity.domain.dao.PaginatedList;
import org.springframework.dao.DataAccessException;
import java.io.Serializable;
import java.util.Collection;
import java.util.List;
/**
* Provides fundamental services layer capabilities for a single concrete {@link
* PersistableEntity}, using JDK 1.5 generics.
*
*
* A design decision was to rely on by-reference calling semantics typical of
* recommended same-JVM (colocated) deployment environments. If you are using
* remoting you may need to provide a remoting facade that returns the updated
* object to the client.
*
*
*
* It is not envisioned that this interface will provide all services layer
* functions. The significant value of a services layer is the value-add beyond
* simply fronting the DAO. The type of value-adds
* expected to be provided by a services layer include incrementing business
* identifiers (eg an invoice number); generating messages for logging/audit
* purposes (thus such messages are at a business transaction level of granularity,
* instead of DAO/persistence granularity where the overall context of the
* the message becomes unclear); updating related domain objects via
* their respective services layer beans (eg an invoice services layer bean
* would call the general journal services layer bean to create the accrual
* accounting entries); producing messages (eg notify another system the invoice
* was created or email the customer via SMTP); provide a layer to locate transaction
* and security configuration etc.
*
*
*
* A single ImmutableManager implementation will typically exist for each
* {@link org.acegisecurity.domain.PersistableEntity}, particularly given
* a PersistableEntity is allowed to manage multiple
* {@link org.acegisecurity.domain.impl.PersistableValue}s.
* The particular PersistableEntity an implementation supports
* will be expressed by the {@link #supports(Class)} method.
*
*
* No other part of the Domain subproject relies on this interface. If
* you would prefer to write your own services layer interfaces from scratch,
* this is not a problem at all.
*
* @author Ben Alex
* @version $Id: ImmutableManager.java 1496 2006-05-23 13:38:33Z benalex $
*/
public interface ImmutableManager {
//~ Methods ========================================================================================================
/**
* Return all persistent instances, including subclasses.
*
* @return all persistence instances (an empty List will be returned if no matches are found)
*
* @throws DataAccessException DOCUMENT ME!
*/
public List findAll() throws DataAccessException;
/**
* Find a List of PersistableEntitys, searched by their identifiers.
*
* @param ids collection of identifiers to locate
*
* @return the values with those identifiers (an empty List will be returned if no matches are found)
*
* @throws DataAccessException DOCUMENT ME!
*/
public List findId(Collection ids)
throws DataAccessException;
/**
* Load a persistent instance by its identifier, although some properties may be lazy loaded depending on
* the underlying DAO implementation and/or persistence engine mapping document.
*
* @param id the identifier of the persistent instance desired to be retrieved
*
* @return the request item, or null if not found
*
* @throws DataAccessException DOCUMENT ME!
*/
public E readId(Serializable id) throws DataAccessException;
/**
* Find persistent instances with properties matching those of the passed PersistableEntity.Persistent
* instances are matched on the basis of query by example. Properties whose value is null, empty
* Strings, and any Collections are ignored in the query by example evaluation.
*
* @param value parameters to filter on (the class of this object will be added to the filter)
* @param firstElement the first result (start at zero to obtain all results)
* @param maxElements the maximum number of results desired for this page of the result set
*
* @return the requested page of the result list (a properly formed PaginatedList is returned if no
* results match)
*
* @throws DataAccessException DOCUMENT ME!
*/
public PaginatedList scroll(E value, int firstElement, int maxElements)
throws DataAccessException;
/**
* Find persistent instances with properties matching those of the passed PersistableEntity,
* ignoring the class of the passed PersistableEntity (useful if you pass a superclass, as you want
* to find all subclass instances which match).
*
* @param value parameters to filter on (the class of this object will NOT be added to the filter)
* @param firstElement the first result (start at zero to obtain all results)
* @param maxElements the maximum number of results desired for this page of the result set
*
* @return the requested page of the result list (a properly formed PaginatedList is returned if no
* results match)
*
* @throws DataAccessException DOCUMENT ME!
*/
public PaginatedList scrollWithSubclasses(E value, int firstElement, int maxElements)
throws DataAccessException;
/**
* Indicates whether the DAO instance provides persistence services for the specified class.
*
* @param clazz to test, which should be an implementation of PersistableEntity
*
* @return true or false, indicating whether or not the passed class is supported by this
* DAO instance
*/
public boolean supports(Class clazz);
}