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