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