cdmlib-services/src/main/java/eu/etaxonomy/cdm/api/service/ICommonService.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 import java.util.Collection;
  14 import java.util.List;
  15 import java.util.Map;
  16 import java.util.Set;
  17 import java.util.UUID;
  18
  19 import org.hibernate.Session;
  20
  21 import eu.etaxonomy.cdm.model.common.CdmBase;
  22 import eu.etaxonomy.cdm.model.common.ISourceable;
  23 import eu.etaxonomy.cdm.model.metadata.CdmMetaData;
  24 import eu.etaxonomy.cdm.model.metadata.CdmMetaData.MetaDataPropertyName;
  25 import eu.etaxonomy.cdm.persistence.dao.common.ICdmGenericDao;
  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
  37 public interface ICommonService /*extends IService<OriginalSourceBase>*/{
  38
  39 //
  40 //      /** find cdmBase by UUID**/
  41 //      public abstract CdmBase getCdmBaseByUuid(UUID uuid);
  42 //
  43 //      /** save a reference and return its UUID**/
  44 //      public abstract UUID saveCdmBase(CdmBase cdmBase);
  45
  46         /**
  47          * Saves all meta data
  48          * @param metaData
  49          */
  50         public void saveAllMetaData(Collection<CdmMetaData> metaData);
  51
  52         /**
  53          * Returns all meta data.
  54          * @return
  55          */
  56         public Map<MetaDataPropertyName, CdmMetaData> getCdmMetaData();
  57
  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 Map<String, ? extends ISourceable> getSourcedObjectsByIdInSource(Class 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 ISourceable getSourcedObjectByIdInSource(Class 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
  92         /**
  93          * Tests if cdmBase2 can be merged into cdmBase1. This is usually the case when both
  94          * objects are of the same class.
  95          * If they are not they must have a common super class and all links to CdmBase2 must be
  96          * re-referenceable to cdmBase1.
  97          * This is not the case if cdmBase2 is linked by a property which does not support class of cdmBase1.
  98          * E.g. User.person requires a person so if user u1 exists with u1.person = person1 and we want to
  99          * merge person1 into team1 this is not possible because team1 is not a valid replacement for person1
 100          * within the user1.person context.
 101          * <BR>
 102          * This method is not expensive if classes are equal but may become more expensive if not, because
 103          * in this concrete references to cdmBases2 need to be evaluated.
 104          * @param cdmBase1
 105          * @param cdmBase2
 106          * @param mergeStrategy
 107          * @return
 108          * @throws MergeException
 109          */
 110         public <T extends CdmBase> boolean isMergeable(T cdmBase1, T cdmBase2, IMergeStrategy mergeStrategy) throws MergeException;
 111
 112
 113         /**
 114          * Merges mergeSecond into mergeFirst. All references to mergeSecond will be replaced by references
 115          * to merge first. If no merge strategy is defined (null), the DefaultMergeStrategy will be taken as default.
 116          * @param <T>
 117          * @param mergeFirst
 118          * @param mergeSecond
 119          * @param mergeStrategy
 120          * @throws MergeException
 121          */
 122         public <T extends IMergable> void   merge(T mergeFirst, T mergeSecond, IMergeStrategy mergeStrategy) throws MergeException;
 123
 124     /**
 125      * Merges mergeSecond into mergeFirst. All references to mergeSecond will be replaced by references
 126      * to merge first, using a merge strategy defined by the given class.
 127      *
 128      * @param mergeFirst
 129      * @param mergeSecond
 130      * @param clazz
 131      * @throws MergeException
 132      */
 133     public <T extends IMergable> void merge(T mergeFirst, T mergeSecond, Class<? extends CdmBase> clazz) throws MergeException;
 134
 135
 136     /**
 137      * Merges mergeSecond into mergeFirst. All references to mergeSecond will be replaced by references
 138      * to merge first, using a merge strategy defined by the mergeFirst type.
 139      * @param mergeFirst
 140      * @param mergeSecond
 141      * @throws MergeException
 142      */
 143     public <T extends IMergable> void merge(T mergeFirst, T mergeSecond) throws MergeException;
 144
 145
 146         /**
 147          * Returns all objects that match the object to match according to the given match strategy.
 148          * If no match strategy is defined the default match strategy is taken.
 149          * @param <T>
 150          * @param objectToMatch
 151          * @param matchStrategy
 152          * @return
 153          * @throws MatchException
 154          */
 155         public <T extends IMatchable> List<T> findMatching(T objectToMatch, IMatchStrategy matchStrategy) throws MatchException;
 156
 157
 158         public <T extends IMatchable> List<T> findMatching(T objectToMatch, MatchStrategyConfigurator.MatchStrategy strategy) throws MatchException;
 159
 160
 161     /**
 162      * @param clazz
 163      * @param id
 164      * @return
 165      */
 166     public CdmBase findWithUpdate(Class<? extends CdmBase> clazz, int id);
 167
 168         /**
 169          * A generic method to retrieve any CdmBase object by its id and class.<BR>
 170          * @see ICdmGenericDao#find(Class, int)
 171          * @see Session#get(Class, java.io.Serializable)
 172          * @param clazz the CdmBase class
 173          * @param id the cdmBase identifier
 174          * @return the CdmBase object defined by clazz and id
 175          */
 176         public CdmBase find(Class<? extends CdmBase> clazz, int id);
 177
 178     /**
 179      * @param clazz
 180      * @param id
 181      * @param propertyPaths
 182      * @return
 183      */
 184     public CdmBase find(Class<? extends CdmBase> clazz, int id, List<String> propertyPaths);
 185
 186
 187         public List getHqlResult(String hqlQuery);
 188
 189
 190     /**
 191      * Initializes a collection or map.
 192      *
 193      * @param ownerUuid uuid of owner cdm entity
 194      * @param fieldName field name of collection or map
 195      * @return initialised collection or map
 196      */
 197     public Object initializeCollection(UUID ownerUuid, String fieldName);
 198
 199     /**
 200      * @param ownerUuid
 201      * @param fieldName
 202      * @param propertyPaths
 203      * @return
 204      */
 205     public Object initializeCollection(UUID ownerUuid, String fieldName, List<String> propertyPaths);
 206
 207         /**
 208          * Checks if a collection or map is empty.
 209          *
 210      * @param ownerUuid uuid of owner cdm entity
 211      * @param fieldName field name of collection or map
 212          * @return true if the collection of map is empty, else false
 213          */
 214         public boolean isEmpty(UUID ownerUuid, String fieldName);
 215
 216         /**
 217          * Returns the size of requested collection or map.
 218          *
 219      * @param ownerUuid uuid of owner cdm entity
 220      * @param fieldName field name of collection or map
 221          * @return the size of the persistent collection
 222          */
 223         public int size(UUID ownerUuid, String fieldName);
 224
 225         /**
 226          * Returns the object contained in a collection or map at the given index.
 227          *
 228      * @param ownerUuid uuid of owner cdm entity
 229      * @param fieldName field name of collection or map
 230          * @param index the index of the requested element
 231          * @return the object at the requested index
 232          */
 233         public Object get(UUID ownerUuid, String fieldName, int index);
 234
 235         /**
 236          * Checks whether an object is contained within a persistent collection.
 237          *
 238      * @param ownerUuid uuid of owner cdm entity
 239      * @param fieldName field name of collection or map
 240          * @param element the element to check for
 241          * @return true if the element exists in the collection, false o/w
 242          */
 243         public boolean contains(UUID ownerUuid, String fieldName, Object element);
 244
 245         /**
 246          * Checks whether an index object exists within a persistent collection
 247          * (usually a map)
 248          *
 249      * @param ownerUuid uuid of owner cdm entity
 250      * @param fieldName field name of map
 251          * @param key the index object to look for.
 252          * @return true if the index object exists in the collection, false o/w
 253          */
 254         public boolean containsKey(UUID ownerUuid, String fieldName, Object key);
 255
 256         /**
 257          * checks whether an value object exists within a persistent collection
 258          * (usually a map)
 259          *
 260      * @param ownerUuid uuid of owner cdm entity
 261      * @param fieldName field name of map
 262          * @param key the value object to look for.
 263          * @return true if the value object exists in the collection, false o/w
 264          */
 265         public boolean containsValue(UUID ownerUuid, String fieldName, Object element);
 266
 267         public Set<CdmBase> getReferencingObjectsForDeletion(CdmBase referencedCdmBase);
 268
 269         /**
 270          * Preliminary, may be moved to test later
 271          */
 272         @Deprecated
 273         public void createFullSampleData();
 274
 275
 276     /**
 277      * Returns the number of objects that belong to a certain class.
 278      * @param type the CdmBase class
 279      * @return the number of objects in the database
 280      */
 281     public <S extends CdmBase> int count(Class<S> type);
 282
 283
 284     /**
 285      * Generic method to retrieve a list of objects. Use only if no specific service class
 286      * can be used.
 287      * @param type
 288      * @param limit
 289      * @param start
 290      * @param orderHints
 291      * @param propertyPaths
 292      * @see IService#list(Class, Integer, Integer, List, List)
 293      * @return
 294      */
 295     public <S extends CdmBase> List<S> list(Class<S> type, Integer limit, Integer start, List<OrderHint> orderHints, List<String> propertyPaths);
 296
 297     /**
 298      * Save a new entity (persists the entity)
 299      * @param newInstance the new entity to be persisted
 300      * @return A generated UUID for the new persistent entity
 301      */
 302     public CdmBase save(CdmBase newInstance);
 303
 304
 305     /**
 306      * Save a collection containing new entities (persists the entities)
 307      * @param newInstances the new entities to be persisted
 308      * @return A Map containing the new entities, keyed using the generated UUID's
 309      *         of those entities
 310      */
 311     public <T extends CdmBase> Map<UUID,T> save(Collection<T> newInstances);
 312
 313     /**
 314      * @param mergeFirstId
 315      * @param mergeSecondId
 316      * @param clazz
 317      * @throws MergeException
 318      * @Deprecated the preferred method is to use uuids {@link #merge(UUID, UUID, Class)}
 319      */
 320     @Deprecated
 321     public <T extends IMergable> void merge(int mergeFirstId, int mergeSecondId, Class<? extends CdmBase> clazz) throws MergeException;
 322
 323     /**
 324      * @param mergeFirstUuid uuid of the first object to merge
 325      * @param mergeSecondUuid UUID of the second object to merge
 326      * @param clazz
 327      * @throws MergeException
 328      */
 329     public <T extends IMergable> void merge(UUID mergeFirstUuid, UUID mergeSecondUuid, Class<? extends CdmBase> clazz) throws MergeException;
 330
 331 }