cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/ICommonService.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.api.service;
  11
  12 import java.util.Collection;
  13 import java.util.List;
  14 import java.util.Map;
  15 import java.util.Set;
  16 import java.util.UUID;
  17
  18 import org.hibernate.Session;
  19
  20 import eu.etaxonomy.cdm.model.common.CdmBase;
  21 import eu.etaxonomy.cdm.model.common.Language;
  22 import eu.etaxonomy.cdm.model.metadata.CdmMetaData;
  23 import eu.etaxonomy.cdm.model.metadata.CdmMetaDataPropertyName;
  24 import eu.etaxonomy.cdm.model.reference.ISourceable;
  25 import eu.etaxonomy.cdm.persistence.dao.common.ICdmGenericDao;
  26 import eu.etaxonomy.cdm.persistence.dto.ReferencingObjectDto;
  27 import eu.etaxonomy.cdm.persistence.query.OrderHint;
  28 import eu.etaxonomy.cdm.strategy.match.IMatchStrategy;
  29 import eu.etaxonomy.cdm.strategy.match.IMatchable;
  30 import eu.etaxonomy.cdm.strategy.match.MatchException;
  31 import eu.etaxonomy.cdm.strategy.match.MatchStrategyConfigurator;
  32 import eu.etaxonomy.cdm.strategy.merge.IMergable;
  33 import eu.etaxonomy.cdm.strategy.merge.IMergeStrategy;
  34 import eu.etaxonomy.cdm.strategy.merge.MergeException;
  35
  36
  37
  38 public interface ICommonService /*extends IService<OriginalSourceBase>*/{
  39
  40 //
  41 //      /** find cdmBase by UUID**/
  42 //      public abstract CdmBase getCdmBaseByUuid(UUID uuid);
  43 //
  44 //      /** save a reference and return its UUID**/
  45 //      public abstract UUID saveCdmBase(CdmBase cdmBase);
  46
  47         /**
  48          * Saves all meta data
  49          * @param metaData
  50          */
  51         public void saveAllMetaData(Collection<CdmMetaData> metaData);
  52
  53         /**
  54          * Returns all meta data.
  55          * @return
  56          */
  57         public Map<CdmMetaDataPropertyName, CdmMetaData> getCdmMetaData();
  58
  59          /**
  60      * Returns a map of identifiable entities of class <code>clazz</code> which have an original source of
  61      * with namespace <code>idNamespace</code> and with an idInSource in <code>idInSourceSet</code> <BR>
  62      * The key of the map is the idInSource. If there are multiple objects that have the same id an arbitrary one is chosen.
  63      * @param clazz
  64      * @param idInSourceSet
  65      * @param idNamespace
  66      * @return
  67      */
  68         public <S extends ISourceable> Map<String, S> getSourcedObjectsByIdInSourceC(Class<S> clazz, Set<String> idInSourceSet, String idNamespace);
  69
  70         /**
  71          * Returns a list of identifiable entities according to their class, idInSource and idNamespace
  72          * @param clazz
  73          * @param idInSource
  74          * @param idNamespace
  75          * @return
  76          */
  77         public <S extends ISourceable> S getSourcedObjectByIdInSource(Class<S> clazz, String idInSource, String idNamespace);
  78
  79
  80         /**
  81          * Returns all CdmBase objects that reference the referencedCdmBase.
  82          * For example, if referencedCdmBase is an agent it may return all taxon names
  83          * that have this person as an author but also all books, articles, etc. that have
  84          * this person as an author
  85          * @param referencedCdmBase
  86          * @return
  87          */
  88         public Set<CdmBase> getReferencingObjects(CdmBase referencedCdmBase);
  89
  90     /**
  91      * @see #getReferencingObjects(CdmBase)
  92      */
  93     public Set<ReferencingObjectDto> getReferencingObjectDtos(CdmBase referencedCdmBase);
  94
  95
  96     public Set<ReferencingObjectDto> initializeReferencingObjectDtos(Set<ReferencingObjectDto> dtos,
  97             boolean doReferencingEntity, boolean doTargetEntity, boolean doDescription, Language language);
  98
  99
 100         /**
 101          * Tests if cdmBase2 can be merged into cdmBase1. This is usually the case when both
 102          * objects are of the same class.
 103          * If they are not they must have a common super class and all links to CdmBase2 must be
 104          * re-referenceable to cdmBase1.
 105          * This is not the case if cdmBase2 is linked by a property which does not support class of cdmBase1.
 106          * E.g. User.person requires a person so if user u1 exists with u1.person = person1 and we want to
 107          * merge person1 into team1 this is not possible because team1 is not a valid replacement for person1
 108          * within the user1.person context.
 109          * <BR>
 110          * This method is not expensive if classes are equal but may become more expensive if not, because
 111          * in this concrete references to cdmBases2 need to be evaluated.
 112          * @param cdmBase1
 113          * @param cdmBase2
 114          * @param mergeStrategy
 115          * @return
 116          * @throws MergeException
 117          */
 118         public <T extends CdmBase> boolean isMergeable(T cdmBase1, T cdmBase2, IMergeStrategy mergeStrategy) throws MergeException;
 119
 120
 121         /**
 122          * Merges mergeSecond into mergeFirst. All references to mergeSecond will be replaced by references
 123          * to merge first. If no merge strategy is defined (null), the DefaultMergeStrategy will be taken as default.
 124          * @param <T>
 125          * @param mergeFirst
 126          * @param mergeSecond
 127          * @param mergeStrategy
 128          * @throws MergeException
 129          */
 130         public <T extends IMergable> void merge(T mergeFirst, T mergeSecond, IMergeStrategy mergeStrategy) throws MergeException;
 131
 132     /**
 133      * Merges mergeSecond into mergeFirst. All references to mergeSecond will be replaced by references
 134      * to merge first, using a merge strategy defined by the given class.
 135      *
 136      * @param mergeFirst
 137      * @param mergeSecond
 138      * @param clazz
 139      * @throws MergeException
 140      */
 141     public <T extends IMergable> void merge(T mergeFirst, T mergeSecond, Class<? extends CdmBase> clazz) throws MergeException;
 142
 143
 144     /**
 145      * Merges mergeSecond into mergeFirst. All references to mergeSecond will be replaced by references
 146      * to merge first, using a merge strategy defined by the mergeFirst type.
 147      * @param mergeFirst
 148      * @param mergeSecond
 149      * @throws MergeException
 150      */
 151     public <T extends IMergable> void merge(T mergeFirst, T mergeSecond) throws MergeException;
 152
 153
 154         /**
 155          * Returns all objects that match the object to match according to the given match strategy.
 156          * If no match strategy is defined the default match strategy is taken.
 157          * @param <T>
 158          * @param objectToMatch
 159          * @param matchStrategy
 160          * @return
 161          * @throws MatchException
 162          */
 163         public <T extends IMatchable> List<T> findMatching(T objectToMatch, IMatchStrategy matchStrategy) throws MatchException;
 164
 165
 166         public <T extends IMatchable> List<T> findMatching(T objectToMatch, MatchStrategyConfigurator.MatchStrategy strategy) throws MatchException;
 167
 168         public <T extends CdmBase> T findWithUpdate(Class<T> clazz, int id);
 169
 170
 171         /**
 172          * A generic method to retrieve any CdmBase object by its id and class.<BR>
 173          * @see ICdmGenericDao#find(Class, int)
 174          * @see Session#get(Class, java.io.Serializable)
 175          * @param clazz the CdmBase class
 176          * @param id the cdmBase identifier
 177          * @return the CdmBase object defined by clazz and id
 178          * @see #find(Class, int, List)
 179          */
 180         public <T extends CdmBase> T find(Class<T> clazz, int id);
 181
 182     /**
 183      * @param clazz the Class of the obejct to find
 184      * @param id
 185      * @param propertyPaths the property path for bean initialization
 186      * @return
 187      * @see #find(Class, int)
 188      */
 189     public <T extends CdmBase> T find(Class<T> clazz, int id, List<String> propertyPaths);
 190
 191     /**
 192      * A generic method to retrieve any CdmBase object by its uuid and class.<BR>
 193      * @param clazz the Class of the obejct to find
 194      * @param uuid the UUID of the object to find
 195      * @return
 196      */
 197     public <T extends CdmBase> T find(Class<T> clazz, UUID uuid);
 198
 199     /**
 200      * A generic method to retrieve any CdmBase object by its UUID and class,
 201      * including initialization via property path.<BR>
 202      * @param clazz the Class of the obejct to find
 203      * @param uuid the UUID of the object to find
 204      * @param propertyPaths the property path for bean initialization
 205      * @return
 206      */
 207     public <T extends CdmBase> T find(Class<T> clazz, UUID uuid, List<String> propertyPaths);
 208
 209         /**
 210          * Returns the result of an HQL Query which does
 211          * not inlcude parameters
 212          * @see #getHqlResult(String, Object[])
 213          */
 214         @SuppressWarnings("rawtypes")
 215     public List getHqlResult(String hqlQuery);
 216
 217         /**
 218          * Returns the result of an HQL Query which inlcudes parameters as
 219          * ordinal parameters (e.g. a = ?0).
 220          *
 221          * @param hqlQuery the HQL query
 222          * @param params the parameter values
 223          * @return  the result of the HQL query
 224      * @see #getHqlResult(String)
 225          */
 226         @SuppressWarnings("rawtypes")
 227     public List getHqlResult(String hqlQuery, Object[] params);
 228
 229
 230     /**
 231      * Initializes a collection or map.
 232      *
 233      * @param ownerUuid uuid of owner cdm entity
 234      * @param fieldName field name of collection or map
 235      * @return initialised collection or map
 236      */
 237     public Object initializeCollection(UUID ownerUuid, String fieldName);
 238
 239     /**
 240      * @param ownerUuid
 241      * @param fieldName
 242      * @param propertyPaths
 243      * @return
 244      */
 245     public Object initializeCollection(UUID ownerUuid, String fieldName, List<String> propertyPaths);
 246
 247         /**
 248          * Checks if a collection or map is empty.
 249          *
 250      * @param ownerUuid uuid of owner cdm entity
 251      * @param fieldName field name of collection or map
 252          * @return true if the collection of map is empty, else false
 253          */
 254         public boolean isEmpty(UUID ownerUuid, String fieldName);
 255
 256         /**
 257          * Returns the size of requested collection or map.
 258          *
 259      * @param ownerUuid uuid of owner cdm entity
 260      * @param fieldName field name of collection or map
 261          * @return the size of the persistent collection
 262          */
 263         public int size(UUID ownerUuid, String fieldName);
 264
 265         /**
 266          * Returns the object contained in a collection or map at the given index.
 267          *
 268      * @param ownerUuid uuid of owner cdm entity
 269      * @param fieldName field name of collection or map
 270          * @param index the index of the requested element
 271          * @return the object at the requested index
 272          */
 273         public Object get(UUID ownerUuid, String fieldName, int index);
 274
 275         /**
 276          * Checks whether an object is contained within a persistent collection.
 277          *
 278      * @param ownerUuid uuid of owner cdm entity
 279      * @param fieldName field name of collection or map
 280          * @param element the element to check for
 281          * @return true if the element exists in the collection, false o/w
 282          */
 283         public boolean contains(UUID ownerUuid, String fieldName, Object element);
 284
 285         /**
 286          * Checks whether an index object exists within a persistent collection
 287          * (usually a map)
 288          *
 289      * @param ownerUuid uuid of owner cdm entity
 290      * @param fieldName field name of map
 291          * @param key the index object to look for.
 292          * @return true if the index object exists in the collection, false o/w
 293          */
 294         public boolean containsKey(UUID ownerUuid, String fieldName, Object key);
 295
 296         /**
 297          * checks whether an value object exists within a persistent collection
 298          * (usually a map)
 299          *
 300      * @param ownerUuid uuid of owner cdm entity
 301      * @param fieldName field name of map
 302          * @param key the value object to look for.
 303          * @return true if the value object exists in the collection, false o/w
 304          */
 305         public boolean containsValue(UUID ownerUuid, String fieldName, Object element);
 306
 307         public Set<CdmBase> getReferencingObjectsForDeletion(CdmBase referencedCdmBase);
 308
 309         /**
 310          * Creates a database that more or less has all tables filled.
 311          * Preliminary, may be moved to test later
 312          */
 313         @Deprecated
 314         public void createFullSampleData();
 315
 316
 317     /**
 318      * Returns the number of objects that belong to a certain class.
 319      * @param type the CdmBase class
 320      * @return the number of objects in the database
 321      */
 322     public <S extends CdmBase> long count(Class<S> type);
 323
 324
 325     /**
 326      * Generic method to retrieve a list of objects. Use only if no specific service class
 327      * can be used.
 328      * @param type
 329      * @param limit
 330      * @param start
 331      * @param orderHints
 332      * @param propertyPaths
 333      * @see IService#list(Class, Integer, Integer, List, List)
 334      * @return
 335      */
 336     public <S extends CdmBase> List<S> list(Class<S> type, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 337
 338     /**
 339      * Save a new entity (persists the entity)
 340      * @param newInstance the new entity to be persisted
 341      * @return A generated UUID for the new persistent entity
 342      */
 343     public CdmBase save(CdmBase newInstance);
 344
 345     /**
 346      * Save or update a new entity
 347      * @param entity the entity to be persisted
 348      * @return The UUID of the persistent entity
 349      */
 350     public UUID saveOrUpdate(CdmBase entity);
 351
 352     /**
 353      * Save a collection containing new entities (persists the entities)
 354      * @param newInstances the new entities to be persisted
 355      * @return A Map containing the new entities, keyed using the generated UUID's
 356      *         of those entities
 357      */
 358     public <T extends CdmBase> Map<UUID,T> save(Collection<T> newInstances);
 359
 360     /**
 361      * Save or update a collection containing entities
 362      * @param entities the entities to be persisted
 363      * @return A Map containing the new entities, keyed using the UUID's
 364      *         of those entities
 365      */
 366     public <T extends CdmBase> Map<UUID,T> saveOrUpdate(Collection<T> entities);
 367
 368     /**
 369      * @param instance
 370      * @return
 371      */
 372     public UUID delete(CdmBase instance);
 373
 374     /**
 375      * @param mergeFirstId
 376      * @param mergeSecondId
 377      * @param clazz
 378      * @throws MergeException
 379      * @Deprecated the preferred method is to use uuids {@link #merge(UUID, UUID, Class)}
 380      */
 381     @Deprecated
 382     public <T extends IMergable> void merge(int mergeFirstId, int mergeSecondId, Class<? extends CdmBase> clazz) throws MergeException;
 383
 384     /**
 385      * @param mergeFirstUuid uuid of the first object to merge
 386      * @param mergeSecondUuid UUID of the second object to merge
 387      * @param clazz
 388      * @throws MergeException
 389      */
 390     public <T extends IMergable> void merge(UUID mergeFirstUuid, UUID mergeSecondUuid, Class<? extends CdmBase> clazz) throws MergeException;
 391
 392     public long getReferencingObjectsCount(CdmBase referencedCdmBase);
 393
 394     public List<UUID> listUuid(Class<? extends CdmBase> clazz);
 395
 396     public UUID refresh(CdmBase persistentObject);
 397
 398 }