X-Git-Url: https://dev.e-taxonomy.eu/gitweb/cdmlib.git/blobdiff_plain/7a1d87e348b2f6dd2d3e1f0d3f187cd28214439a..ec30105559cd77bd10e47568824a453e450195c6:/cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IService.java diff --git a/cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IService.java b/cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IService.java index 8efe095d8b..2555a0d101 100644 --- a/cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IService.java +++ b/cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IService.java @@ -1,3 +1,4 @@ +// $Id$ /** * Copyright (C) 2007 EDIT * European Distributed Institute of Taxonomy @@ -13,92 +14,183 @@ package eu.etaxonomy.cdm.api.service; import java.util.Collection; import java.util.List; import java.util.Map; +import java.util.Set; import java.util.UUID; -import org.springframework.transaction.annotation.Propagation; -import org.springframework.transaction.annotation.Transactional; +import org.hibernate.LockMode; +import org.hibernate.Session; +import org.springframework.security.core.Authentication; -import eu.etaxonomy.cdm.model.common.CdmBase; +import eu.etaxonomy.cdm.api.service.pager.Pager; +import eu.etaxonomy.cdm.model.common.ICdmBase; +import eu.etaxonomy.cdm.permission.CdmPermission; +import eu.etaxonomy.cdm.persistence.dao.BeanInitializer; +import eu.etaxonomy.cdm.persistence.query.Grouping; +import eu.etaxonomy.cdm.persistence.query.OrderHint; /** * @author a.mueller * */ -@Transactional(propagation=Propagation.SUPPORTS) -public interface IService{ +/** + * @author a.kohlbecker + * @date 23.03.2009 + * + * @param + */ +public interface IService{ + // FIXME what does this method do? + public void clear(); + /** - * Returns a count of all entities of type - * @return a count of all entities + * Obtain the specified lock mode on the given object t */ - public int count(); - + public void lock(T t, LockMode lockMode); + + /** + * Refreshes a given object t using the specified lockmode + * + * All bean properties given in the propertyPaths parameter are recursively initialized. + *

+ * For detailed description and examples please refer to: + * {@link BeanInitializer#initialize(Object, List)} + * + * NOTE: in the case of lockmodes that hit the database (e.g. LockMode.READ), you will need to re-initialize + * child propertiesto avoid a HibernateLazyInitializationException (even if the properties of the child + * were initialized prior to the refresh). + * + * @param t + * @param lockMode + */ + public void refresh(T t, LockMode lockMode, List propertyPaths); + /** - * Returns a count of all entities of type that extend - * @param clazz the class of entities to be counted + * Returns a count of all entities of type optionally restricted + * to objects belonging to a class that that extends + * + * @param clazz the class of entities to be counted (can be null to count all entities of type ) * @return a count of entities */ - public int count(Class clazz); + public int count(Class clazz); /** - * Returns a List of entities of type - * TODO would like to substitute List with Pager, but we need - * to agree on how to implement paging first + * Delete an existing persistent object * - * @param limit The maximum number of entities returned - * @param start The offset from the start of the dataset - * @return a List of entities + * @param persistentObject the object to be deleted + * @return the unique identifier of the deleted entity + */ + public UUID delete(T persistentObject); + + /** + * Returns true if an entity of type with a unique identifier matching the + * identifier supplied exists in the database, or false if no such entity can be + * found. + * @param uuid the unique identifier of the entity required + * @return an entity of type matching the uuid, or null if that entity does not exist */ - public List list(int limit, int start); + public boolean exists(UUID uuid); /** - * Returns a List of entities of type which must extend - * - * TODO would like to substitute List with Pager, but we need - * to agree on how to implement paging first + * Return a list of persisted entities that match the unique identifier + * set supplied as an argument * - * @param type The type of entities to return - * @param limit The maximum number of entities returned - * @param start The offset from the start of the dataset - * @return a List of entities + * @param uuidSet the set of unique identifiers of the entities required + * @return a list of entities of type */ - public List list(Class type, int limit, int start); + public List find(Set uuidSet); - public List rows(String tableName, int limit, int start); + /** + * Return a persisted entity that matches the unique identifier + * supplied as an argument, or null if the entity does not exist + * + * @param uuid the unique identifier of the entity required + * @return an entity of type , or null if the entity does not exist + */ + public T find(UUID uuid); + + // FIXME should we expose this method? + public Session getSession(); /** - * Save a new entity (persists the entity) - * @param newInstance the new entity to be persisted - * @return A generated UUID for the new persistent entity + * Returns a sublist of objects matching the grouping projections supplied using the groups parameter + * + * It would be nice to be able to return a pager, but for the moment hibernate doesn't + * seem to support this (HHH-3238 - impossible to get the rowcount for a criteria that has projections) + * + * @param clazz Restrict the query to objects of a certain class, or null for all objects of type T or subclasses + * @param limit the maximum number of entities returned (can be null to return + * all entities) + * @param start The (0-based) offset from the start of the recordset (can be null, equivalent of starting at the beginning of the recordset) + * @param groups The grouping objects representing a projection, plus an optional ordering on that projected property + * @param propertyPaths paths initialized on the returned objects - only applied to the objects returned from the first grouping + * @return a list of arrays of objects, each matching the grouping objects supplied in the parameters. + */ + public List group(Class clazz,Integer limit, Integer start, List groups, List propertyPaths); + + /** + * Returns a list of entities of type optionally restricted + * to objects belonging to a class that that extends + * + * @param type The type of entities to return (can be null to count all entities of type ) + * @param limit The maximum number of objects returned (can be null for all matching objects) + * @param start The offset from the start of the result set (0 - based, can be null - equivalent of starting at the beginning of the recordset) + * @param orderHints + * Supports path like orderHints.propertyNames which + * include *-to-one properties like createdBy.username or + * authorTeam.persistentTitleCache + * @param propertyPaths properties to be initialized + * @return */ - public UUID save(T newInstance); + public List list(Class type, Integer limit, Integer start, List orderHints, List propertyPaths); /** - * Save a new entity or update the persistent state of an existing - * transient entity that has been persisted previously + * Finds the cdm entity specified by the uuid parameter and + * initializes all its *ToOne relations. * - * @param transientObject the entity to be persisted - * @return The unique identifier of the persisted entity + * @param uuid + * @return */ - public UUID saveOrUpdate(T transientObject); + public T load(UUID uuid); /** - * Update the persistent state of an existing transient entity - * that has been persisted previously + * Finds the cdm entity specified by the uuid parameter and + * recursively initializes all bean properties given in the + * propertyPaths parameter. + *

+ * For detailed description and examples please refer to: + * {@link BeanInitializer#initialize(Object, List)} * - * @param transientObject the entity to be persisted + * @param uuid + * @return + */ + public T load(UUID uuid, List propertyPaths); + + /** + * Copy the state of the given object onto the persistent object with the same identifier. + * + * @param transientObject the entity to be merged * @return The unique identifier of the persisted entity */ - public UUID update(T transientObject); + public UUID merge(T transientObject); /** - * Save a collection containing new entities (persists the entities) - * @param newInstances the new entities to be persisted - * @return A Map containing the new entities, keyed using the generated UUID's - * of those entities + * Returns a paged list of entities of type optionally restricted + * to objects belonging to a class that that extends + * + * @param type The type of entities to return (can be null to count all entities of type ) + * @param pageSize The maximum number of objects returned (can be null for all matching objects) + * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based, + * can be null, equivalent of starting at the beginning of the recordset) + * @param orderHints + * Supports path like orderHints.propertyNames which + * include *-to-one properties like createdBy.username or + * authorTeam.persistentTitleCache + * @param propertyPaths properties to be initialized + * @return a pager of objects of type */ - public Map saveAll(Collection newInstances); + public Pager page(Class type, Integer pageSize, Integer pageNumber, List orderHints, List propertyPaths); /** * Re-read the state of the given instance from the underlying database. @@ -114,29 +206,82 @@ public interface IService{ */ public UUID refresh(T persistentObject); + public List rows(String tableName, int limit, int start); + /** - * Delete an existing persistent object + * Save a collection containing new entities (persists the entities) + * @param newInstances the new entities to be persisted + * @return A Map containing the new entities, keyed using the generated UUID's + * of those entities + */ + public Map save(Collection newInstances); + + /** + * Save a new entity (persists the entity) + * @param newInstance the new entity to be persisted + * @return A generated UUID for the new persistent entity + */ + public UUID save(T newInstance); + + /** + * Save a new entity or update the persistent state of an existing + * transient entity that has been persisted previously * - * @param persistentObject the object to be deleted - * @return the unique identifier of the deleted entity + * @param transientObject the entity to be persisted + * @return The unique identifier of the persisted entity */ - public UUID delete(T persistentObject); + public UUID saveOrUpdate(T transientObject); /** - * Return a persisted entity that matches the unique identifier - * supplied as an argument, or null if the entity does not exist + * Save new entities or update the persistent state of existing + * transient entities that have been persisted previously * - * @param uuid the unique identifier of the entity required - * @return an entity of type , or null if the entity does not exist + * @param transientObjects the entities to be persisted + * @return The unique identifier of the persisted entity */ - public T findByUuid(UUID uuid); + public Map saveOrUpdate(Collection transientObjects); + + /** + * Update the persistent state of an existing transient entity + * that has been persisted previously + * + * @param transientObject the entity to be persisted + * @return The unique identifier of the persisted entity + */ + public UUID update(T transientObject); /** - * Returns true if an entity of type with a unique identifier matching the - * identifier supplied exists in the database, or false if no such entity can be - * found. - * @param uuid the unique identifier of the entity required - * @return an entity of type matching the uuid, or null if that entity does not exist + * Method that lists the objects matching the example provided. + * The includeProperties property is used to specify which properties of the example are used. + * + * If includeProperties is null or empty, then all literal properties are used (restrictions are + * applied as in the Hibernate Query-By-Example API call Example.create(object)). + * + * If includeProperties is not empty then only literal properties that are named in the set are used to + * create restrictions, *PLUS* any *ToOne related entities. Related entities are matched on ID, not by + * their internal literal values (e.g. the call is criteria.add(Restrictions.eq(property,relatedObject)), not + * criteria.createCriteria(property).add(Example.create(relatedObject))) + * + * @param example + * @param includeProperties + * @param limit the maximum number of entities returned (can be null to return + * all entities) + * @param start The (0-based) offset from the start of the recordset + * @param orderHints + * Supports path like orderHints.propertyNames which + * include *-to-one properties like createdBy.username or + * @param propertyPaths paths initialized on the returned objects - only applied to the objects returned from the first grouping + * @return a list of matching objects */ - public boolean exists(UUID uuid); + public List list(T example, Set includeProperties, Integer limit, Integer start, List orderHints, List propertyPaths); + + /** + * Evaluates whether the authenticated user has the rights to perform an specific action on the target object + * @param authentication + * @param target + * @param permission + * @return + */ + public boolean hasPermission(Authentication authentication, T target, CdmPermission permission); + } \ No newline at end of file