cdmlib-persistence/src/main/java/eu/etaxonomy/cdm/persistence/dao/common/ICdmGenericDao.java

   1 /**
   2 * Copyright (C) 2007 EDIT
   3 * European Distributed Institute of Taxonomy
   4 * http://www.e-taxonomy.eu
   5 *
   6 * The contents of this file are subject to the Mozilla Public License Version 1.1
   7 * See LICENSE.TXT at the top of this package for the full license terms.
   8 */
   9
  10 package eu.etaxonomy.cdm.persistence.dao.common;
  11
  12 import java.util.List;
  13 import java.util.Set;
  14 import java.util.UUID;
  15
  16 import org.hibernate.Query;
  17 import org.hibernate.Session;
  18 import org.springframework.dao.DataAccessException;
  19
  20 import eu.etaxonomy.cdm.model.common.CdmBase;
  21 import eu.etaxonomy.cdm.model.metadata.CdmMetaData;
  22 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  23 import eu.etaxonomy.cdm.strategy.match.IMatchStrategy;
  24 import eu.etaxonomy.cdm.strategy.match.IMatchable;
  25 import eu.etaxonomy.cdm.strategy.match.MatchException;
  26 import eu.etaxonomy.cdm.strategy.merge.IMergeStrategy;
  27 import eu.etaxonomy.cdm.strategy.merge.MergeException;
  28
  29 public interface ICdmGenericDao {
  30
  31         public UUID saveOrUpdate(CdmBase transientObject) throws DataAccessException;
  32
  33         public CdmBase save(CdmBase newOrManagedObject) throws DataAccessException;
  34
  35         public UUID update(CdmBase transientObject) throws DataAccessException;
  36
  37         public UUID delete(CdmBase persistentObject) throws DataAccessException;
  38
  39         public void saveMetaData(CdmMetaData cdmMetaData);
  40
  41         public List<CdmMetaData> getMetaData();
  42
  43         /**
  44          * Returns a CdmBase object of class <code>clazz</code> that has a property with name
  45          * <code>propertyName</code> that references the CdmBase object <code>referencedCdmBase</code>.
  46          * @param clazz
  47          * @param propertyName
  48          * @param value
  49          * @return
  50          */
  51         public List<CdmBase> getCdmBasesByFieldAndClass(Class clazz, String propertyName, CdmBase referencedCdmBase, Integer limit);
  52
  53         /**
  54          * Returns ...
  55          * @param thisClass
  56          * @param otherClazz
  57          * @param propertyName
  58          * @param referencedCdmBase
  59          * @return
  60          */
  61         public List<CdmBase> getCdmBasesWithItemInCollection(Class itemClass, Class clazz, String propertyName, CdmBase item, Integer limit);
  62
  63         /**
  64          * Returns all classes that are persisted via the persisting framework.
  65          * E.g. in hibernate these are all classes registered in the session factory
  66          * (via e.g. hibernate.cfg.xml)
  67          * <BR>
  68          * @param includeAbstractClasses if <code>false</code> the abstract classes
  69          * will not be in the result set.
  70          * @return
  71          */
  72         public Set<Class<? extends CdmBase>> getAllPersistedClasses(boolean includeAbstractClasses);
  73
  74         /**
  75          * Returns all CdmBase objects that reference the referencedCdmBase.
  76          * For example, if referencedCdmBase is an agent it may return all taxon names
  77          * that have this person as an author but also all books, articles, etc. that have
  78          * this person as an author
  79          * @param referencedCdmBase
  80          * @return
  81          */
  82         public Set<CdmBase> getReferencingObjects(CdmBase referencedCdmBase);
  83
  84         /**
  85          * Merges cdmBase2 into cdmBase1 and rearranges all reference to cdmBase2 by letting them point to
  86          * cdmBase1. If the merge strategy is not defined (<code>null</code>) the default merge strategy is taken instead.
  87          *
  88          * @param cdmBase1
  89          * @param cdmBase2
  90          * @param mergeStrategy
  91          * @throws IllegalArgumentException
  92          * @throws NullPointerException
  93          * @throws MergeException
  94          */
  95         public <T extends CdmBase> void   merge(T cdmBase1, T cdmBase2, IMergeStrategy mergeStrategy) throws MergeException;
  96
  97         /**
  98          * Computes if cdmBase2 can be merged into cdmBase1. This is usually the case when both
  99          * objects are of the same class.
 100          * If they are not they must have a common super class and all links to CdmBase2 must be
 101          * re-referenceable to cdmBase1.
 102          * This is not the case if cdmBase2 is linked by a property which does not support class of cdmBase1.
 103          * E.g. User.person requires a person so if user u1 exists with u1.person = person1 and we want to
 104          * merge person1 into team1 this is not possible because team1 is not a valid replacement for person1
 105          * within the user1.person context.
 106          * @param cdmBase1
 107          * @param cdmBase2
 108          * @param mergeStrategy
 109          * @return true if objects are mergeable
 110          * @throws IllegalArgumentException
 111          * @throws NullPointerException
 112          * @throws MergeException
 113          */
 114         public <T extends CdmBase> boolean  isMergeable(T cdmBase1, T cdmBase2, IMergeStrategy mergeStrategy) throws MergeException;
 115
 116
 117         /**
 118          * Returns a List of matching persistent objects according to the match strategy
 119          * @param <T>
 120          * @param objectToMatch
 121          * @param matchStrategy
 122          * @return
 123          * @throws MatchException
 124          */
 125         public <T extends IMatchable> List<T> findMatching(T objectToMatch, IMatchStrategy matchStrategy) throws MatchException;
 126
 127
 128         /**
 129          * A generic method to retrieve any CdmBase object by its id and class.<BR>
 130          * Return the persistent instance of the given entity class with the given identifier,
 131          * or null if there is no such persistent instance. (If the instance is already
 132          * associated with the session, return that instance. This method never returns
 133          * an uninitialized instance.)<BR>
 134          * TODO: the behaviour for abstract high level classes (such as CdmBase itself)
 135          * is not yet tested.
 136          * @see Session#get(Class, java.io.Serializable)
 137          * @param clazz the CdmBase class
 138          * @param id the identifier
 139          * @return the CdmBase instance
 140          * @see #find(Class, UUID)
 141      * @see #find(Class, int, List)
 142          */
 143         public <T extends CdmBase> T find(Class<T> clazz, int id);
 144
 145         /**
 146      * A generic method to retrieve any CdmBase object by its id and class.<BR>
 147      * Return the persistent instance of the given entity class with the given identifier,
 148      * or <code>null</code> if there is no such persistent instance. (If the instance is already
 149      * associated with the session, return that instance. This method never returns
 150      * an uninitialized instance.)
 151      * @see Session#get(Class, java.io.Serializable)
 152      * @param clazz the CdmBase class
 153      * @param uuid the identifier
 154      * @return the CdmBase instance
 155      * @see #find(Class, int)
 156      * @see #find(Class, UUID, List)
 157      */
 158     public <T extends CdmBase> T find(Class<T> clazz, UUID uuid);
 159
 160         /**
 161      * Does the same as {@link #find(Class, int)} but also initializes the returned
 162      * object according to the property path.
 163      *
 164      * @param clazz class of the object to be loaded and initialized
 165      * @param id the identifier
 166      * @param propertyPaths the property path for initialization
 167      * @return The initialized object
 168      * @see #find(Class, UUID)
 169      */
 170     public <T extends CdmBase> T find(Class<T> clazz, int id, List<String> propertyPaths);
 171
 172     /**
 173      * Does the same as {@link #find(Class, UUID)} but also initializes the returned
 174      * object according to the property path.
 175      * @param clazz
 176      * @param uuid
 177      * @param propertyPaths
 178      * @return
 179      * @see #find(Class, UUID)
 180      */
 181     public <T extends CdmBase> T find(Class<T> clazz, UUID uuid, List<String> propertyPaths);
 182
 183         /**
 184          * Returns the result of an hql query
 185          * TODO implement parameters
 186          * @deprecated this is not clean implementation as it is hibernate related.
 187          * @param hqlQuery
 188          * @return
 189          */
 190         @Deprecated
 191         public List getHqlResult(String hqlQuery) throws UnsupportedOperationException;
 192
 193         /**
 194          * TODO remove as this is Hibernate specific.
 195          * Returns a Query
 196          * @deprecated this is not clean implemantation as it is hibernate related.
 197          * Will be replaced in future
 198          * @param hqlQuery
 199          * @return
 200          */
 201         @Deprecated
 202         public Query getHqlQuery(String hqlQuery) throws UnsupportedOperationException;
 203
 204
 205         public Set<CdmBase> getReferencingObjectsForDeletion(CdmBase referencedCdmBase);
 206
 207         public void createFullSampleData();
 208
 209
 210     /**
 211      * Returns the number of objects belonging to a certain class being stored
 212      * in the database
 213      * @param type
 214      * @return
 215      */
 216     public long count(Class<? extends CdmBase> type);
 217
 218
 219            /**
 220      * Returns a sublist of CdmBase instances stored in the database. A maximum
 221      * of 'limit' objects are returned, starting at object with index 'start'.
 222      *
 223      * @param type
 224      * @param limit
 225      *            the maximum number of entities returned (can be null to return
 226      *            all entities)
 227      * @param start
 228      * @param orderHints
 229      *            Supports path like <code>orderHints.propertyNames</code> which
 230      *            include *-to-one properties like createdBy.username or
 231      *            authorTeam.persistentTitleCache
 232      * @return
 233      * @throws DataAccessException
 234      */
 235     public <S extends CdmBase> List<S> list(Class<S> type, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 236
 237
 238     /**
 239      * @param ownerUuid
 240      * @param fieldName
 241      * @param appendedPropertyPaths
 242      * @return
 243      */
 244     public Object initializeCollection(UUID ownerUuid, String fieldName, List<String> appendedPropertyPaths);
 245
 246     /**
 247      * Initializes a collection or map.
 248      *
 249      * @param ownerUuid uuid of owner cdm entity
 250      * @param fieldName field name of collection or map
 251      * @return initialised collection or map
 252      */
 253     public Object initializeCollection(UUID ownerUuid, String fieldName);
 254
 255     /**
 256      * Checks if a collection or map is empty.
 257      *
 258      * @param ownerUuid uuid of owner cdm entity
 259      * @param fieldName field name of collection or map
 260      * @return true if the collection of map is empty, else false
 261      */
 262     public boolean isEmpty(UUID ownerUuid, String fieldName);
 263
 264     /**
 265      * Returns the size of requested collection or map.
 266      *
 267      * @param ownerUuid uuid of owner cdm entity
 268      * @param fieldName field name of collection or map
 269      * @return the size of the persistent collection
 270      */
 271     public int size(UUID ownerUuid, String fieldName);
 272
 273     /**
 274      * Returns the object contained in a collection or map at the given index.
 275      *
 276      * @param ownerUuid uuid of owner cdm entity
 277      * @param fieldName field name of collection or map
 278      * @param index the index of the requested element
 279      * @return the object at the requested index
 280      */
 281     public Object get(UUID ownerUuid, String fieldName, int index);
 282
 283     /**
 284      * Checks whether an object is contained within a persistent collection.
 285      *
 286      * @param ownerUuid uuid of owner cdm entity
 287      * @param fieldName field name of collection or map
 288      * @param element the element to check for
 289      * @return true if the element exists in the collection, false o/w
 290      */
 291     public boolean contains(UUID ownerUuid, String fieldName, Object element);
 292
 293     /**
 294      * Checks whether an index object exists within a persistent collection
 295      * (usually a map)
 296      *
 297      * @param ownerUuid uuid of owner cdm entity
 298      * @param fieldName field name of map
 299      * @param key the index object to look for.
 300      * @return true if the index object exists in the collection, false o/w
 301      */
 302     public boolean containsKey(UUID ownerUuid, String fieldName, Object key);
 303
 304     /**
 305      * checks whether an value object exists within a persistent collection
 306      * (usually a map)
 307      *
 308      * @param ownerUuid uuid of owner cdm entity
 309      * @param fieldName field name of map
 310      * @param key the value object to look for.
 311      * @return true if the value object exists in the collection, false o/w
 312      */
 313     public boolean containsValue(UUID ownerUuid, String fieldName, Object element);
 314
 315     /**
 316      * @param itemClass
 317      * @param clazz
 318      * @param propertyName
 319      * @param item
 320      * @return
 321      */
 322     public long getCountWithItemInCollection(Class itemClass, Class clazz, String propertyName, CdmBase item);
 323
 324     /**
 325      * @param clazz
 326      * @param propertyName
 327      * @param referencedCdmBase
 328      * @return
 329      */
 330     public long getCountByFieldAndClass(Class clazz, String propertyName, CdmBase referencedCdmBase);
 331
 332     /**
 333      * @param referencedCdmBase
 334      * @return
 335      */
 336     public Long getReferencingObjectsCount(CdmBase referencedCdmBase);
 337
 338
 339
 340
 341
 342 }