+// $Id$\r
/**\r
* Copyright (C) 2007 EDIT\r
* European Distributed Institute of Taxonomy \r
import java.util.Collection;\r
import java.util.List;\r
import java.util.Map;\r
+import java.util.Set;\r
import java.util.UUID;\r
\r
-import org.springframework.transaction.annotation.Propagation;\r
-import org.springframework.transaction.annotation.Transactional;\r
+import org.hibernate.LockMode;\r
+import org.hibernate.Session;\r
+import org.springframework.security.core.Authentication;\r
\r
-import eu.etaxonomy.cdm.model.common.CdmBase;\r
+import eu.etaxonomy.cdm.api.service.pager.Pager;\r
+import eu.etaxonomy.cdm.model.common.ICdmBase;\r
+import eu.etaxonomy.cdm.permission.CdmPermission;\r
+import eu.etaxonomy.cdm.persistence.dao.BeanInitializer;\r
+import eu.etaxonomy.cdm.persistence.query.Grouping;\r
+import eu.etaxonomy.cdm.persistence.query.OrderHint;\r
\r
\r
/**\r
* @author a.mueller\r
*\r
*/\r
-@Transactional(propagation=Propagation.SUPPORTS)\r
-public interface IService<T extends CdmBase>{\r
+/**\r
+ * @author a.kohlbecker\r
+ * @date 23.03.2009\r
+ *\r
+ * @param <T>\r
+ */\r
+public interface IService<T extends ICdmBase>{\r
\r
+ // FIXME what does this method do?\r
+ public void clear();\r
+ \r
/**\r
- * Returns a count of all entities of type <T>\r
- * @return a count of all entities\r
+ * Obtain the specified lock mode on the given object t\r
*/\r
- public int count();\r
-\r
+ public void lock(T t, LockMode lockMode);\r
+ \r
+ /**\r
+ * Refreshes a given object t using the specified lockmode\r
+ * \r
+ * All bean properties given in the <code>propertyPaths</code> parameter are recursively initialized.\r
+ * <p>\r
+ * For detailed description and examples <b>please refer to:</b> \r
+ * {@link BeanInitializer#initialize(Object, List)}\r
+ * \r
+ * NOTE: in the case of lockmodes that hit the database (e.g. LockMode.READ), you will need to re-initialize\r
+ * child propertiesto avoid a HibernateLazyInitializationException (even if the properties of the child \r
+ * were initialized prior to the refresh).\r
+ * \r
+ * @param t\r
+ * @param lockMode\r
+ */\r
+ public void refresh(T t, LockMode lockMode, List<String> propertyPaths);\r
+ \r
/**\r
- * Returns a count of all entities of type <TYPE> that extend <T>\r
- * @param clazz the class of entities to be counted\r
+ * Returns a count of all entities of type <T> optionally restricted\r
+ * to objects belonging to a class that that extends <T>\r
+ * \r
+ * @param clazz the class of entities to be counted (can be null to count all entities of type <T>)\r
* @return a count of entities\r
*/\r
- public <TYPE extends T> int count(Class<TYPE> clazz);\r
+ public int count(Class<? extends T> clazz);\r
\r
/**\r
- * Returns a List of entities of type <T>\r
- * TODO would like to substitute List with Pager, but we need\r
- * to agree on how to implement paging first\r
+ * Delete an existing persistent object\r
* \r
- * @param limit The maximum number of entities returned\r
- * @param start The offset from the start of the dataset\r
- * @return a List of entities\r
+ * @param persistentObject the object to be deleted\r
+ * @return the unique identifier of the deleted entity\r
+ */\r
+ public UUID delete(T persistentObject);\r
+ \r
+ /**\r
+ * Returns true if an entity of type <T> with a unique identifier matching the \r
+ * identifier supplied exists in the database, or false if no such entity can be \r
+ * found. \r
+ * @param uuid the unique identifier of the entity required\r
+ * @return an entity of type <T> matching the uuid, or null if that entity does not exist\r
*/\r
- public List<T> list(int limit, int start);\r
+ public boolean exists(UUID uuid);\r
\r
/**\r
- * Returns a List of entities of type <TYPE> which must extend \r
- * <T>\r
- * TODO would like to substitute List with Pager, but we need\r
- * to agree on how to implement paging first\r
+ * Return a list of persisted entities that match the unique identifier\r
+ * set supplied as an argument\r
* \r
- * @param type The type of entities to return\r
- * @param limit The maximum number of entities returned\r
- * @param start The offset from the start of the dataset\r
- * @return a List of entities\r
+ * @param uuidSet the set of unique identifiers of the entities required\r
+ * @return a list of entities of type <T>\r
*/\r
- public <TYPE extends T> List<TYPE> list(Class<TYPE> type, int limit, int start);\r
+ public List<T> find(Set<UUID> uuidSet);\r
\r
- public List<T> rows(String tableName, int limit, int start);\r
+ /**\r
+ * Return a persisted entity that matches the unique identifier\r
+ * supplied as an argument, or null if the entity does not exist\r
+ * \r
+ * @param uuid the unique identifier of the entity required\r
+ * @return an entity of type <T>, or null if the entity does not exist\r
+ */\r
+ public T find(UUID uuid);\r
+ \r
+ // FIXME should we expose this method?\r
+ public Session getSession();\r
\r
/**\r
- * Save a new entity (persists the entity)\r
- * @param newInstance the new entity to be persisted\r
- * @return A generated UUID for the new persistent entity\r
+ * Returns a sublist of objects matching the grouping projections supplied using the groups parameter\r
+ * \r
+ * It would be nice to be able to return a pager, but for the moment hibernate doesn't\r
+ * seem to support this (HHH-3238 - impossible to get the rowcount for a criteria that has projections)\r
+ * \r
+ * @param clazz Restrict the query to objects of a certain class, or null for all objects of type T or subclasses\r
+ * @param limit the maximum number of entities returned (can be null to return\r
+ * all entities)\r
+ * @param start The (0-based) offset from the start of the recordset (can be null, equivalent of starting at the beginning of the recordset)\r
+ * @param groups The grouping objects representing a projection, plus an optional ordering on that projected property\r
+ * @param propertyPaths paths initialized on the returned objects - only applied to the objects returned from the first grouping\r
+ * @return a list of arrays of objects, each matching the grouping objects supplied in the parameters.\r
+ */\r
+ public List<Object[]> group(Class<? extends T> clazz,Integer limit, Integer start, List<Grouping> groups, List<String> propertyPaths);\r
+ \r
+ /**\r
+ * Returns a list of entities of type <T> optionally restricted\r
+ * to objects belonging to a class that that extends <T>\r
+ * \r
+ * @param type The type of entities to return (can be null to count all entities of type <T>)\r
+ * @param limit The maximum number of objects returned (can be null for all matching objects)\r
+ * @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)\r
+ * @param orderHints\r
+ * Supports path like <code>orderHints.propertyNames</code> which\r
+ * include *-to-one properties like createdBy.username or\r
+ * authorTeam.persistentTitleCache\r
+ * @param propertyPaths properties to be initialized\r
+ * @return\r
*/\r
- public UUID save(T newInstance);\r
+ public List<T> list(Class<? extends T> type, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);\r
\r
/**\r
- * Save a new entity or update the persistent state of an existing \r
- * transient entity that has been persisted previously\r
+ * Finds the cdm entity specified by the <code>uuid</code> parameter and\r
+ * initializes all its *ToOne relations.\r
* \r
- * @param transientObject the entity to be persisted\r
- * @return The unique identifier of the persisted entity\r
+ * @param uuid\r
+ * @return\r
*/\r
- public UUID saveOrUpdate(T transientObject);\r
+ public T load(UUID uuid);\r
\r
/**\r
- * Update the persistent state of an existing transient entity \r
- * that has been persisted previously\r
+ * Finds the cdm entity specified by the <code>uuid</code> parameter and\r
+ * recursively initializes all bean properties given in the\r
+ * <code>propertyPaths</code> parameter.\r
+ * <p>\r
+ * For detailed description and examples <b>please refer to:</b> \r
+ * {@link BeanInitializer#initialize(Object, List)}\r
* \r
- * @param transientObject the entity to be persisted\r
+ * @param uuid\r
+ * @return\r
+ */\r
+ public T load(UUID uuid, List<String> propertyPaths);\r
+ \r
+ /**\r
+ * Copy the state of the given object onto the persistent object with the same identifier.\r
+ * \r
+ * @param transientObject the entity to be merged\r
* @return The unique identifier of the persisted entity\r
*/\r
- public UUID update(T transientObject);\r
+ public UUID merge(T transientObject);\r
\r
/**\r
- * Save a collection containing new entities (persists the entities)\r
- * @param newInstances the new entities to be persisted\r
- * @return A Map containing the new entities, keyed using the generated UUID's\r
- * of those entities\r
+ * Returns a paged list of entities of type <T> optionally restricted\r
+ * to objects belonging to a class that that extends <T>\r
+ * \r
+ * @param type The type of entities to return (can be null to count all entities of type <T>)\r
+ * @param pageSize The maximum number of objects returned (can be null for all matching objects)\r
+ * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based, \r
+ * can be null, equivalent of starting at the beginning of the recordset)\r
+ * @param orderHints\r
+ * Supports path like <code>orderHints.propertyNames</code> which\r
+ * include *-to-one properties like createdBy.username or\r
+ * authorTeam.persistentTitleCache\r
+ * @param propertyPaths properties to be initialized\r
+ * @return a pager of objects of type <T>\r
*/\r
- public Map<UUID,T> saveAll(Collection<T> newInstances);\r
+ public Pager<T> page(Class<? extends T> type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);\r
\r
/**\r
* Re-read the state of the given instance from the underlying database.\r
*/\r
public UUID refresh(T persistentObject);\r
\r
+ public List<T> rows(String tableName, int limit, int start);\r
+\r
/**\r
- * Delete an existing persistent object\r
+ * Save a collection containing new entities (persists the entities)\r
+ * @param newInstances the new entities to be persisted\r
+ * @return A Map containing the new entities, keyed using the generated UUID's\r
+ * of those entities\r
+ */\r
+ public Map<UUID,T> save(Collection<T> newInstances); \r
+ \r
+ /**\r
+ * Save a new entity (persists the entity)\r
+ * @param newInstance the new entity to be persisted\r
+ * @return A generated UUID for the new persistent entity\r
+ */\r
+ public UUID save(T newInstance);\r
+ \r
+ /**\r
+ * Save a new entity or update the persistent state of an existing \r
+ * transient entity that has been persisted previously\r
* \r
- * @param persistentObject the object to be deleted\r
- * @return the unique identifier of the deleted entity\r
+ * @param transientObject the entity to be persisted\r
+ * @return The unique identifier of the persisted entity\r
*/\r
- public UUID delete(T persistentObject);\r
+ public UUID saveOrUpdate(T transientObject);\r
\r
/**\r
- * Return a persisted entity that matches the unique identifier\r
- * supplied as an argument, or null if the entity does not exist\r
+ * Save new entities or update the persistent state of existing \r
+ * transient entities that have been persisted previously\r
* \r
- * @param uuid the unique identifier of the entity required\r
- * @return an entity of type <T>, or null if the entity does not exist\r
+ * @param transientObjects the entities to be persisted\r
+ * @return The unique identifier of the persisted entity\r
*/\r
- public T findByUuid(UUID uuid);\r
+ public Map<UUID,T> saveOrUpdate(Collection<T> transientObjects);\r
+ \r
+ /**\r
+ * Update the persistent state of an existing transient entity \r
+ * that has been persisted previously\r
+ * \r
+ * @param transientObject the entity to be persisted\r
+ * @return The unique identifier of the persisted entity\r
+ */\r
+ public UUID update(T transientObject);\r
\r
/**\r
- * Returns true if an entity of type <T> with a unique identifier matching the \r
- * identifier supplied exists in the database, or false if no such entity can be \r
- * found. \r
- * @param uuid the unique identifier of the entity required\r
- * @return an entity of type <T> matching the uuid, or null if that entity does not exist\r
+ * Method that lists the objects matching the example provided. \r
+ * The includeProperties property is used to specify which properties of the example are used.\r
+ * \r
+ * If includeProperties is null or empty, then all literal properties are used (restrictions are\r
+ * applied as in the Hibernate Query-By-Example API call Example.create(object)).\r
+ * \r
+ * If includeProperties is not empty then only literal properties that are named in the set are used to \r
+ * create restrictions, *PLUS* any *ToOne related entities. Related entities are matched on ID, not by \r
+ * their internal literal values (e.g. the call is criteria.add(Restrictions.eq(property,relatedObject)), not \r
+ * criteria.createCriteria(property).add(Example.create(relatedObject)))\r
+ * \r
+ * @param example\r
+ * @param includeProperties\r
+ * @param limit the maximum number of entities returned (can be null to return\r
+ * all entities)\r
+ * @param start The (0-based) offset from the start of the recordset\r
+ * @param orderHints\r
+ * Supports path like <code>orderHints.propertyNames</code> which\r
+ * include *-to-one properties like createdBy.username or\r
+ * @param propertyPaths paths initialized on the returned objects - only applied to the objects returned from the first grouping\r
+ * @return a list of matching objects\r
*/\r
- public boolean exists(UUID uuid);\r
+ public List<T> list(T example, Set<String> includeProperties, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);\r
+ \r
+ /**\r
+ * Evaluates whether the authenticated user has the rights to perform an specific action on the target object\r
+ * @param authentication\r
+ * @param target\r
+ * @param permission\r
+ * @return\r
+ */\r
+ public boolean hasPermission(Authentication authentication, T target, CdmPermission permission);\r
+\r
}
\ No newline at end of file
BGBM BDI Projects / cdmlib.git / blobdiff