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.IMatchStrategy;
|
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, IMatchStrategy 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
|
}
|