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