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