cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/IService.java

   1 // $Id$
   2 /**
   3 * Copyright (C) 2007 EDIT
   4 * European Distributed Institute of Taxonomy
   5 * http://www.e-taxonomy.eu
   6 *
   7 * The contents of this file are subject to the Mozilla Public License Version 1.1
   8 * See LICENSE.TXT at the top of this package for the full license terms.
   9 */
  10
  11 package eu.etaxonomy.cdm.api.service;
  12
  13
  14 import java.util.Collection;
  15 import java.util.EnumSet;
  16 import java.util.List;
  17 import java.util.Map;
  18 import java.util.Set;
  19 import java.util.UUID;
  20
  21 import org.hibernate.LockMode;
  22 import org.hibernate.Session;
  23 import org.springframework.security.core.Authentication;
  24
  25 import eu.etaxonomy.cdm.api.service.pager.Pager;
  26 import eu.etaxonomy.cdm.model.common.ICdmBase;
  27 import eu.etaxonomy.cdm.persistence.dao.initializer.IBeanInitializer;
  28 import eu.etaxonomy.cdm.persistence.hibernate.permission.CRUD;
  29 import eu.etaxonomy.cdm.persistence.hibernate.permission.Operation;
  30 import eu.etaxonomy.cdm.persistence.query.Grouping;
  31 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  32
  33
  34 /**
  35  * @author a.mueller
  36  *
  37  */
  38 /**
  39  * @author a.kohlbecker
  40  * @date 23.03.2009
  41  *
  42  * @param <T>
  43  */
  44 public interface IService<T extends ICdmBase>{
  45
  46     // FIXME what does this method do?
  47     public void clear();
  48
  49     /**
  50      * Obtain the specified lock mode on the given object t
  51      */
  52     public void lock(T t, LockMode lockMode);
  53
  54     /**
  55      * Refreshes a given object t using the specified lockmode
  56      *
  57      * All bean properties given in the <code>propertyPaths</code> parameter are recursively initialized.
  58      * <p>
  59      * For detailed description and examples <b>please refer to:</b>
  60      * {@link IBeanInitializer#initialize(Object, List)}
  61      *
  62      * NOTE: in the case of lockmodes that hit the database (e.g. LockMode.READ), you will need to re-initialize
  63      * child propertiesto avoid a HibernateLazyInitializationException (even if the properties of the child
  64      * were initialized prior to the refresh).
  65      *
  66      * @param t
  67      * @param lockMode
  68      */
  69     public void refresh(T t, LockMode lockMode, List<String> propertyPaths);
  70
  71     /**
  72      * Returns a count of all entities of type <T>  optionally restricted
  73      * to objects belonging to a class that that extends <T>
  74      *
  75      * @param clazz the class of entities to be counted (can be null to count all entities of type <T>)
  76      * @return a count of entities
  77      */
  78     public int count(Class<? extends T> clazz);
  79
  80     /**
  81      * Delete an existing persistent object
  82      *
  83      * @param persistentObject the object to be deleted
  84      * @return the unique identifier of the deleted entity
  85      */
  86     public UUID delete(T persistentObject);
  87
  88     /**
  89      * Returns true if an entity of type <T> with a unique identifier matching the
  90      * identifier supplied exists in the database, or false if no such entity can be
  91      * found.
  92      * @param uuid the unique identifier of the entity required
  93      * @return an entity of type <T> matching the uuid, or null if that entity does not exist
  94      */
  95     public boolean exists(UUID uuid);
  96
  97     /**
  98      * Return a list of persisted entities that match the unique identifier
  99      * set supplied as an argument
 100      *
 101      * @param uuidSet the set of unique identifiers of the entities required
 102      * @return a list of entities of type <T>
 103      */
 104     public List<T> find(Set<UUID> uuidSet);
 105
 106     /**
 107      * Return a persisted entity that matches the unique identifier
 108      * supplied as an argument, or null if the entity does not exist
 109      *
 110      * @param uuid the unique identifier of the entity required
 111      * @return an entity of type <T>, or null if the entity does not exist
 112      */
 113     public T find(UUID uuid);
 114
 115     /**
 116      * Return a persisted entity that matches the database identifier
 117      * supplied as an argument, or null if the entity does not exist
 118      *
 119      * @param id the database identifier of the entity required
 120      * @return an entity of type <T>, or null if the entity does not exist
 121      */
 122     public T find(int id);
 123
 124     /**
 125      * Returns a <code>List</code> of persisted entities that match the database identifiers.
 126      * Returns an empty list if no identifier matches.
 127      *
 128      * @param idSet
 129      * @return
 130      */
 131     public List<T> findById(Set<Integer> idSet);  //can't be called find(Set<Integer>) as this conflicts with find(Set<UUID)
 132
 133
 134     // FIXME should we expose this method?
 135     public Session getSession();
 136
 137     /**
 138      * Returns a sublist of objects matching the grouping projections supplied using the groups parameter
 139      *
 140      * It would be nice to be able to return a pager, but for the moment hibernate doesn't
 141      * seem to support this (HHH-3238 - impossible to get the rowcount for a criteria that has projections)
 142      *
 143      * @param clazz Restrict the query to objects of a certain class, or null for all objects of type T or subclasses
 144      * @param limit the maximum number of entities returned (can be null to return
 145      *            all entities)
 146      * @param start The (0-based) offset from the start of the recordset (can be null, equivalent of starting at the beginning of the recordset)
 147      * @param groups The grouping objects representing a projection, plus an optional ordering on that projected property
 148      * @param propertyPaths paths initialized on the returned objects - only applied to the objects returned from the first grouping
 149      * @return a list of arrays of objects, each matching the grouping objects supplied in the parameters.
 150      */
 151     public List<Object[]> group(Class<? extends T> clazz,Integer limit, Integer start, List<Grouping> groups, List<String> propertyPaths);
 152
 153     /**
 154      * Returns a list of entities of type <T> optionally restricted
 155      * to objects belonging to a class that that extends <T>
 156      *
 157      * @param type  The type of entities to return (can be null to count all entities of type <T>)
 158      * @param limit The maximum number of objects returned (can be null for all matching objects)
 159      * @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)
 160      * @param orderHints
 161      *            Supports path like <code>orderHints.propertyNames</code> which
 162      *            include *-to-one properties like createdBy.username or
 163      *            authorTeam.persistentTitleCache
 164      * @param propertyPaths properties to be initialized
 165      * @return
 166      */
 167     public List<T> list(Class<? extends T> type, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 168
 169     /**
 170      * Finds the cdm entity specified by the <code>uuid</code> parameter and
 171      * initializes all its *ToOne relations.
 172      *
 173      * @param uuid
 174      * @return
 175      */
 176     public T load(UUID uuid);
 177
 178     /**
 179      * Finds the cdm entity specified by the <code>uuid</code> parameter and
 180      * recursively initializes all bean properties given in the
 181      * <code>propertyPaths</code> parameter.
 182      * <p>
 183      * For detailed description and examples <b>please refer to:</b>
 184      * {@link IBeanInitializer#initialize(Object, List)}
 185      *
 186      * @param uuid
 187      * @return
 188      */
 189     public T load(UUID uuid, List<String> propertyPaths);
 190
 191     /**
 192      * Copy the state of the given object onto the persistent object with the same identifier.
 193      *
 194      * @param transientObject the entity to be merged
 195      * @return The unique identifier of the persisted entity
 196      */
 197     public T merge(T transientObject);
 198
 199     /**
 200      * Returns a paged list of entities of type <T> optionally restricted
 201      * to objects belonging to a class that that extends <T>
 202      *
 203      * @param type  The type of entities to return (can be null to count all entities of type <T>)
 204      * @param pageSize The maximum number of objects returned (can be null for all matching objects)
 205      * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based,
 206      *                   can be null, equivalent of starting at the beginning of the recordset)
 207      * @param orderHints
 208      *            Supports path like <code>orderHints.propertyNames</code> which
 209      *            include *-to-one properties like createdBy.username or
 210      *            authorTeam.persistentTitleCache
 211      * @param propertyPaths properties to be initialized
 212      * @return a pager of objects of type <T>
 213      */
 214     public Pager<T> page(Class<? extends T> type, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);
 215
 216     /**
 217      * Re-read the state of the given instance from the underlying database.
 218      *
 219      * Hibernate claims that it is inadvisable to use refresh in long-running-sessions.
 220      * I don't really see where we would get into a situation where problems as discussed
 221      * this forum thread would apply for our scenario
 222      *
 223      * http://forum.hibernate.org/viewtopic.php?t=974544
 224      *
 225      * @param persistentObject the object to be refreshed
 226      * @return the unique identifier
 227      */
 228     public UUID refresh(T persistentObject);
 229
 230     public List<T> rows(String tableName, int limit, int start);
 231
 232     /**
 233      * Save a collection containing new entities (persists the entities)
 234      * @param newInstances the new entities to be persisted
 235      * @return A Map containing the new entities, keyed using the generated UUID's
 236      *         of those entities
 237      */
 238     public Map<UUID,T> save(Collection<T> newInstances);
 239
 240     /**
 241      * Save a new entity (persists the entity)
 242      * @param newInstance the new entity to be persisted
 243      * @return A generated UUID for the new persistent entity
 244      */
 245     public UUID save(T newInstance);
 246
 247     /**
 248      * Save a new entity or update the persistent state of an existing
 249      * transient entity that has been persisted previously
 250      *
 251      * @param transientObject the entity to be persisted
 252      * @return The unique identifier of the persisted entity
 253      */
 254     public UUID saveOrUpdate(T transientObject);
 255
 256     /**
 257      * Save new entities or update the persistent state of existing
 258      * transient entities that have been persisted previously
 259      *
 260      * @param transientObjects the entities to be persisted
 261      * @return The unique identifier of the persisted entity
 262      */
 263     public Map<UUID,T> saveOrUpdate(Collection<T> transientObjects);
 264
 265     /**
 266      * Update the persistent state of an existing transient entity
 267      * that has been persisted previously
 268      *
 269      * @param transientObject the entity to be persisted
 270      * @return The unique identifier of the persisted entity
 271      */
 272     public UUID update(T transientObject);
 273
 274     /**
 275      * Method that lists the objects matching the example provided.
 276      * The includeProperties property is used to specify which properties of the example are used.
 277      *
 278      * If includeProperties is null or empty, then all literal properties are used (restrictions are
 279      * applied as in the Hibernate Query-By-Example API call Example.create(object)).
 280      *
 281      * If includeProperties is not empty then only literal properties that are named in the set are used to
 282      * create restrictions, *PLUS* any *ToOne related entities. Related entities are matched on ID, not by
 283      * their internal literal values (e.g. the call is criteria.add(Restrictions.eq(property,relatedObject)), not
 284      * criteria.createCriteria(property).add(Example.create(relatedObject)))
 285      *
 286      * @param example
 287      * @param includeProperties
 288      * @param limit the maximum number of entities returned (can be null to return
 289      *            all entities)
 290      * @param start The (0-based) offset from the start of the recordset
 291      * @param orderHints
 292      *            Supports path like <code>orderHints.propertyNames</code> which
 293      *            include *-to-one properties like createdBy.username or
 294      * @param propertyPaths paths initialized on the returned objects - only applied to the objects returned from the first grouping
 295      * @return a list of matching objects
 296      */
 297     public List<T> list(T example, Set<String> includeProperties, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 298
 299 }