2 * Copyright (C) 2007 EDIT
3 * European Distributed Institute of Taxonomy
4 * http://www.e-taxonomy.eu
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.
9 package eu
.etaxonomy
.cdm
.api
.service
;
11 import java
.util
.Collection
;
12 import java
.util
.Enumeration
;
13 import java
.util
.List
;
14 import java
.util
.Locale
;
17 import java
.util
.UUID
;
19 import eu
.etaxonomy
.cdm
.api
.service
.TermServiceImpl
.TermMovePosition
;
20 import eu
.etaxonomy
.cdm
.api
.service
.config
.TermDeletionConfigurator
;
21 import eu
.etaxonomy
.cdm
.api
.service
.pager
.Pager
;
22 import eu
.etaxonomy
.cdm
.common
.URI
;
23 import eu
.etaxonomy
.cdm
.model
.common
.Language
;
24 import eu
.etaxonomy
.cdm
.model
.common
.LanguageString
;
25 import eu
.etaxonomy
.cdm
.model
.common
.LanguageStringBase
;
26 import eu
.etaxonomy
.cdm
.model
.location
.Country
;
27 import eu
.etaxonomy
.cdm
.model
.location
.NamedArea
;
28 import eu
.etaxonomy
.cdm
.model
.location
.NamedAreaLevel
;
29 import eu
.etaxonomy
.cdm
.model
.location
.NamedAreaType
;
30 import eu
.etaxonomy
.cdm
.model
.media
.Media
;
31 import eu
.etaxonomy
.cdm
.model
.metadata
.TermSearchField
;
32 import eu
.etaxonomy
.cdm
.model
.term
.DefinedTermBase
;
33 import eu
.etaxonomy
.cdm
.model
.term
.OrderedTermVocabulary
;
34 import eu
.etaxonomy
.cdm
.model
.term
.Representation
;
35 import eu
.etaxonomy
.cdm
.model
.term
.TermCollection
;
36 import eu
.etaxonomy
.cdm
.model
.term
.TermType
;
37 import eu
.etaxonomy
.cdm
.persistence
.dao
.initializer
.IBeanInitializer
;
38 import eu
.etaxonomy
.cdm
.persistence
.dto
.TermDto
;
39 import eu
.etaxonomy
.cdm
.persistence
.dto
.UuidAndTitleCache
;
40 import eu
.etaxonomy
.cdm
.persistence
.query
.OrderHint
;
42 public interface ITermService
extends IIdentifiableEntityService
<DefinedTermBase
> {
45 * Returns a term according to it's uri
47 public DefinedTermBase
getByUri(URI uri
);
49 public UUID
saveLanguageData(LanguageStringBase languageData
);
51 public List
<LanguageString
> getAllLanguageStrings(int limit
, int start
);
53 public List
<Representation
> getAllRepresentations(int limit
, int start
);
55 public Language
getLanguageByIso(String iso639
);
57 public List
<Language
> getLanguagesByLocale(Enumeration
<Locale
> locales
);
59 public NamedArea
getAreaByTdwgAbbreviation(String tdwgAbbreviation
);
62 * Returns a paged list of Media that represent a given DefinedTerm instance
64 * @param definedTerm the definedTerm represented by these media
65 * @param pageSize The maximum number of media returned (can be null for all related media)
66 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
67 * @return a Pager of media instances
69 public Pager
<Media
> getMedia(DefinedTermBase definedTerm
, Integer pageSize
, Integer pageNumber
);
72 * Returns a paged list of NamedArea instances (optionally filtered by type or level)
74 * @param level restrict the result set to named areas of a certain level (can be null)
75 * @param type restrict the result set to named areas of a certain type (can be null)
76 * @param pageSize The maximum number of namedAreas returned (can be null for all named areas)
77 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
78 * @return a Pager of named areas
80 public Pager
<NamedArea
> list(NamedAreaLevel level
, NamedAreaType type
, Integer pageSize
, Integer pageNumber
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
83 * Return a paged list of terms which are specializations of a given definedTerm
85 * @param definedTerm The term which is a generalization of the terms returned
86 * @param pageSize The maximum number of terms returned (can be null for all specializations)
87 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
88 * @return a Pager of DefinedTerms
90 public <T
extends DefinedTermBase
> Pager
<T
> getGeneralizationOf(T definedTerm
, Integer pageSize
, Integer pageNumber
);
93 * Return a paged list of distinct terms which include the terms supplied
95 * @param definedTerms the set of terms which are part of the terms of interest
96 * @param pageSize The maximum number of terms returned (can be null for all terms)
97 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
98 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
99 * @return a Pager of DefinedTerms
101 public <T
extends DefinedTermBase
> Pager
<T
> getPartOf(Set
<T
> definedTerms
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
104 * Return a paged list of terms which are part of the terms supplied
106 * @param definedTerms the set of terms which include the terms of interest
107 * @param pageSize The maximum number of terms returned (can be null for all terms)
108 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
109 * @param propertyPaths properties to initialize - see {@link IBeanInitializer#initialize(Object, List)}
110 * @return a Pager of DefinedTerms
112 public <T
extends DefinedTermBase
> Pager
<T
> getIncludes(Collection
<T
> definedTerms
, Integer pageSize
, Integer pageNumber
, List
<String
> propertyPaths
);
115 * Return a paged list of terms which have representations that match the supplied string in the text (description)
117 * @param label a string to match (exactly)
118 * @param pageSize The maximum number of terms returned (can be null for all terms)
119 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
120 * @return a Pager of DefinedTerms
122 public <T
extends DefinedTermBase
> Pager
<T
> findByRepresentationText(String label
, Class
<T
> clazz
, Integer pageSize
, Integer pageNumber
);
125 * Return a paged list of terms which have representations that match the supplied string in the abbreviated label
127 * @param label a string to match (exactly)
128 * @param pageSize The maximum number of terms returned (can be null for all terms)
129 * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)
130 * @return a Pager of DefinedTerms
132 public <T
extends DefinedTermBase
> Pager
<T
> findByRepresentationAbbreviation(String abbrev
, Class
<T
> clazz
, Integer pageSize
, Integer pageNumber
);
135 * Retrieves all {@link DefinedTermBase}s with the given {@link TermType}
136 * @param termType the term type to filter the terms
140 * @param propertyPaths
141 * @return a list containing the terms
143 public <T
extends DefinedTermBase
> List
<T
> listByTermType(TermType termType
, Integer limit
, Integer start
, List
<OrderHint
> orderHints
, List
<String
> propertyPaths
);
146 * Delete the given term according to the given delete configuration.
147 * In case a problem occurrs while deleting the term the result will reflect this
149 * @param term the term to delete
150 * @param config the configurator
151 * @return DeleteResult which holds the status of the deletion.
153 public DeleteResult
delete(DefinedTermBase term
, TermDeletionConfigurator config
);
156 * Returns the term with the given idInVocabulary for the given vocabulary.
157 * If the same idInVocabulary exists with same vocabulary for multiple terms (though this is against the general
158 * contract of idInVocabulary) always the same term should be returned.
160 * @param id idInVocabulary
161 * @param vocabularyUuid uuid of vocabulary
162 * @param clazz term clazz filter on certain term classes. May be <code>null</code> for no filter.
164 * @throws IllegalArgumentException if id or vocabularyUuid is <code>null</code>
165 * @see #findUuidByIdInVocabulary(String, UUID, Class)
167 public <TERM
extends DefinedTermBase
> TERM
findByIdInVocabulary(String id
, UUID vocabularyUuid
, Class
<TERM
> clazz
)
168 throws IllegalArgumentException
;
171 * Returns the UUID of the term with the given idInVocabulary for the given vocabulary.
172 * If the same idInVocabulary exists with same vocabulary for multiple terms (though this is against the general
173 * contract of idInVocabulary) always the same term should be returned.
175 * @param id idInVocabulary
176 * @param vocabularyUuid uuid of vocabulary
177 * @param clazz term clazz filter on certain term classes. May be <code>null</code> for no filter.
179 * @throws IllegalArgumentException if id or vocabularyUuid is <code>null</code>
180 * @see #findByIdInVocabulary(String, UUID, Class)
182 public UUID
findUuidByIdInVocabulary(String id
, UUID vocabularyUuid
, Class
<?
extends DefinedTermBase
<?
>> clazz
)
183 throws IllegalArgumentException
;
185 public DeleteResult
delete(UUID termUuid
, TermDeletionConfigurator config
);
187 public DeleteResult
delete(List
<UUID
> termUuids
, TermDeletionConfigurator config
);
189 public DeleteResult
deleteTerms(List
<DefinedTermBase
> terms
, TermDeletionConfigurator config
);
191 public Language
getLanguageByLabel(String label
);
193 public Map
<UUID
, Representation
> saveOrUpdateRepresentations(Collection
<Representation
> representations
);
196 * Returns all terms that are included in the given parent term resp. a part of the given term.
197 * @param parentTerm the parent term
198 * @return a collection of included terms
200 public Collection
<TermDto
> getIncludesAsDto(TermDto parentTerm
);
203 * Returns all terms that the given term is a generalization of resp. that are a kind of the given term
204 * @param parentTerm the parent term
205 * @return a collection of included terms
207 public Collection
<TermDto
> getKindOfsAsDto(TermDto parentTerm
);
210 * Move the given term to the given parent
211 * @param termDto the {@link TermDto} of the term to move
212 * @param parentUuid the {@link UUID} of the new parent term
213 * @param termMovePosition enum to specify the position for {@link DefinedTermBase}s in an {@link OrderedTermVocabulary}
215 public UpdateResult
moveTerm(TermDto termDto
, UUID parentUuid
, TermMovePosition termMovePosition
);
218 * Move the given term to the given parent
219 * @param termDto the {@link TermDto} of the term to move
220 * @param parentUuid the {@link UUID} of the new parent term
222 public UpdateResult
moveTerm(TermDto termDto
, UUID parentUuid
);
225 * Creates a new term as a child of the given parent.
226 * @param termType the {@link TermType} of the term to create
227 * @param parentUuid the {@link UUID} of the parent term
228 * @param isKindOf if <code>true</code> the term will be added via a
229 * kindOf relation. Otherwise it will added via a partOf relation
230 * @return the new term
232 public TermDto
addNewTerm(TermType termType
, UUID parentUuid
, boolean isKindOf
, Language lang
);
236 * Returns a collection of {@link TermDto}s that match the given search parameters.
237 * @param title the term label that the terms have to match
238 * @param termType the termType that the terms have to match
239 * @return a collection of matching term DTOs
241 public Collection
<TermDto
> findByTitleAsDtoWithVocDto(String title
, TermType termType
);
244 * Returns a collection of {@link TermDto}s that match the given search parameters.
245 * @param uri the {@link URI} that the terms have to match
246 * @param termLabel the term label that the terms have to match
247 * @param termType the termType that the terms have to match
248 * @return a collection of matching term DTOs
250 public Collection
<TermDto
> findByUriAsDto(URI uri
, String termLabel
, TermType termType
);
253 * Returns a list of {@link UuidAndTitleCache} of named areas with titleCache or specified search field
254 * matches search parameter
256 public <S
extends DefinedTermBase
> List
<UuidAndTitleCache
<S
>> getUuidAndTitleCache(
257 Class
<S
> clazz
, List
<?
extends TermCollection
> vocs
,
258 Integer limit
, String pattern
, Language lang
, TermSearchField type
);
261 * Returns a list of {@link TermDto} of terms with uuid matches one of uuids in list
265 public Collection
<TermDto
> findByUUIDsAsDto(List
<UUID
> uuidList
);
268 public Collection
<TermDto
> findFeatureByUUIDsAsDto(List
<UUID
> uuidList
);
270 public Collection
<TermDto
> findFeatureByTitleAsDto(String title
);
272 public Country
getCountryByIso(String iso639
);
274 public List
<Country
> getCountryByName(String name
);
277 * Returns a map of {@link UUID} and {@link TermDto} of terms with uuid matches one of uuids in list
279 public Map
<UUID
, TermDto
> findFeatureByUUIDsAsDtos(List
<UUID
> uuidList
);