+// $Id$\r
/**\r
* Copyright (C) 2007 EDIT\r
* European Distributed Institute of Taxonomy \r
import eu.etaxonomy.cdm.model.description.Scope;\r
import eu.etaxonomy.cdm.model.description.TaxonDescription;\r
import eu.etaxonomy.cdm.model.description.TaxonNameDescription;\r
-import eu.etaxonomy.cdm.model.description.TextData;\r
import eu.etaxonomy.cdm.model.location.NamedArea;\r
import eu.etaxonomy.cdm.model.media.Media;\r
import eu.etaxonomy.cdm.model.name.TaxonNameBase;\r
import eu.etaxonomy.cdm.model.taxon.Taxon;\r
+import eu.etaxonomy.cdm.persistence.dao.BeanInitializer;\r
+import eu.etaxonomy.cdm.persistence.query.OrderHint;\r
\r
public interface IDescriptionService extends IIdentifiableEntityService<DescriptionBase> {\r
-\r
+ \r
/**\r
- * @param uuid\r
+ * \r
* @return\r
+ * @deprecated use TermService#getVocabulary(VocabularyType) instead\r
*/\r
- // FIXME candidate for harmonization? findByUuid\r
- public DescriptionBase getDescriptionBaseByUuid(UUID uuid);\r
+ public TermVocabulary<Feature> getDefaultFeatureVocabulary();\r
\r
/**\r
- * Persists a <code>Description</code>\r
- * @param description\r
- * @return\r
+ * @deprecated use TermService#getVocabulary(VocabularyType) instead\r
*/\r
- // FIXME candidate for harmonization? save\r
- public UUID saveDescription(DescriptionBase description);\r
+ public TermVocabulary<Feature> getFeatureVocabulary(UUID uuid);\r
\r
/**\r
- * Persists a <code>FeatureTree</code>\r
- * @param tree\r
- * @return\r
+ * Gets a DescriptionElementBase instance matching the supplied uuid\r
+ * \r
+ * @param uuid the uuid of the DescriptionElement of interest\r
+ * @return a DescriptionElement, or null if the DescriptionElement does not exist\r
*/\r
- public UUID saveFeatureTree(FeatureTree tree);\r
- // FIXME could you handle the feature data elements using @Cascade?\r
- public void saveFeatureDataAll(Collection<VersionableEntity> featureData);\r
- public Map<UUID, FeatureTree> saveFeatureTreeAll(Collection<FeatureTree> trees);\r
- public Map<UUID, FeatureNode> saveFeatureNodeAll(Collection<FeatureNode> nodes);\r
+ public DescriptionElementBase getDescriptionElementByUuid(UUID uuid);\r
\r
/**\r
- * Gets a FeatureTree instance matching the supplied uuid\r
+ * Loads and existing DescriptionElementBase instance matching the supplied uuid,\r
+ * and recursively initializes all bean properties given in the\r
+ * <code>propertyPaths</code> parameter.\r
+ * <p>\r
+ * For detailed description and examples <b>please refer to:</b> \r
+ * {@link BeanInitializer#initialize(Object, List)}\r
* \r
- * @param uuid the uuid of the FeatureTree of interest\r
- * @return a FeatureTree, or null if the FeatureTree does not exist\r
+ * @param uuid the uuid of the DescriptionElement of interest\r
+ * @return a DescriptionElement, or null if the DescriptionElement does not exist\r
*/\r
- public FeatureTree getFeatureTreeByUuid(UUID uuid);\r
+ public DescriptionElementBase loadDescriptionElement(UUID uuid,List<String> propertyPaths);\r
\r
- public List<FeatureTree> getFeatureTreesAll();\r
- public List<FeatureNode> getFeatureNodesAll();\r
+ /**\r
+ * Persists a <code>DescriptionElementBase</code>\r
+ * @param descriptionElement\r
+ * @return\r
+ */\r
+ public UUID saveDescriptionElement(DescriptionElementBase descriptionElement);\r
\r
- public TermVocabulary<Feature> getDefaultFeatureVocabulary();\r
- //public TermVocabulary<Feature> getFeatureVocabulary();\r
- public TermVocabulary<Feature> getFeatureVocabulary(UUID uuid);\r
-\r
/**\r
- * Gets a DescriptionElementBase instance matching the supplied uuid\r
+ * Delete an existing description element\r
* \r
- * @param uuid the uuid of the DescriptionElement of interest\r
- * @return a DescriptionElement, or null if the DescriptionElement does not exist\r
+ * @param descriptionElement the description element to be deleted\r
+ * @return the unique identifier of the deleted entity\r
*/\r
- public DescriptionElementBase getDescriptionElementByUuid(UUID uuid);\r
+ public UUID deleteDescriptionElement(DescriptionElementBase descriptionElement);\r
\r
/**\r
- * List the descriptions of type <TYPE>, filtered using the following parameters\r
+ * List the descriptions of type <T>, filtered using the following parameters\r
* \r
* @param type The type of description returned (Taxon, TaxonName, or Specimen)\r
* @param hasMedia Restrict the description to those that do (true) or don't (false) contain <i>elements</i> that have one or more media (can be null)\r
* @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)\r
* @param pageSize The maximum number of descriptions returned (can be null for all descriptions)\r
* @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)\r
+ * @param orderHints may be null\r
+ * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}\r
* @return a Pager containing DescriptionBase instances\r
*/\r
- public <TYPE extends DescriptionBase> Pager<TYPE> listDescriptions(Class<TYPE> type, Boolean hasMedia, Boolean hasText, Set<Feature> feature, Integer pageSize, Integer pageNumber);\r
+ public Pager<DescriptionBase> page(Class<? extends DescriptionBase> type, Boolean hasMedia, Boolean hasText, Set<Feature> feature, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);\r
\r
/**\r
* Count the descriptions of type <TYPE>, filtered using the following parameters\r
* @param feature Restrict the description to those <i>elements</i> which are scoped by one of the Features passed (can be null or empty)\r
* @return a count of DescriptionBase instances\r
*/\r
- public <TYPE extends DescriptionBase> int countDescriptions(Class<TYPE> type, Boolean hasImages, Boolean hasText, Set<Feature> feature);\r
+ public int count(Class<? extends DescriptionBase> type, Boolean hasImages, Boolean hasText, Set<Feature> feature);\r
\r
/**\r
* Returns description elements of type <TYPE>, belonging to a given description, optionally filtered by one or more features\r
* @param description The description which these description elements belong to (can be null to count all description elements)\r
* @param features Restrict the results to those description elements which are scoped by one of the Features passed (can be null or empty)\r
* @param type The type of description\r
+ * @param class \r
* @param pageSize The maximum number of description elements returned (can be null for all description elements)\r
* @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)\r
+ * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}\r
* @return a Pager containing DescriptionElementBase instances\r
*/\r
- public <TYPE extends DescriptionElementBase> Pager<TYPE> getDescriptionElements(DescriptionBase description,Set<Feature> features, Class<TYPE> type, Integer pageSize, Integer pageNumber);\r
+ public Pager<DescriptionElementBase> getDescriptionElements(DescriptionBase description,Set<Feature> features, Class<? extends DescriptionElementBase> type, Integer pageSize, Integer pageNumber, List<String> propertyPaths);\r
\r
/**\r
* Returns a List of TaxonDescription instances, optionally filtered by parameters passed to this method\r
* @param geographicalScope Restrict the results to those descriptions which have a geographical scope that overlaps with the NamedArea instances passed (can be null or empty)\r
* @param pageSize The maximum number of descriptions returned (can be null for all descriptions)\r
* @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)\r
+ * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}\r
* @return a Pager containing TaxonDescription instances\r
*/\r
- public Pager<TaxonDescription> getTaxonDescriptions(Taxon taxon, Set<Scope> scopes, Set<NamedArea> geographicalScope, Integer pageSize, Integer pageNumber);\r
+ public Pager<TaxonDescription> getTaxonDescriptions(Taxon taxon, Set<Scope> scopes, Set<NamedArea> geographicalScope, Integer pageSize, Integer pageNumber, List<String> propertyPaths);\r
\r
/**\r
* Returns a List of TaxonNameDescription instances, optionally filtered by the name which they refer to\r
* @param name Restrict the results to those descriptions that refer to a specific name (can be null for all TaxonNameDescription instances)\r
* @param pageSize The maximum number of descriptions returned (can be null for all descriptions)\r
* @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)\r
+ * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}\r
* @return a Pager containing TaxonNameBase instances\r
*/\r
- public Pager<TaxonNameDescription> getTaxonNameDescriptions(TaxonNameBase name, Integer pageSize, Integer pageNumber);\r
+ public Pager<TaxonNameDescription> getTaxonNameDescriptions(TaxonNameBase name, Integer pageSize, Integer pageNumber, List<String> propertyPaths);\r
\r
/**\r
* Returns a List of distinct TaxonDescription instances which have Distribution elements that refer to one of the NamedArea instances passed (optionally\r
* @param presence Restrict the descriptions to those which have Distribution elements are of this status (can be null)\r
* @param pageSize The maximum number of descriptions returned (can be null for all descriptions)\r
* @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)\r
+ * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)\r
+ * @param propertyPaths Properties to initialize in the returned entities, following the syntax described in {@link BeanInitializer#initialize(Object, List)}\r
* @return a Pager containing TaxonDescription instances\r
*/\r
- public Pager<TaxonDescription> searchDescriptionByDistribution(Set<NamedArea> namedAreas, PresenceAbsenceTermBase presence, Integer pageSize, Integer pageNumber);\r
+ public Pager<TaxonDescription> searchDescriptionByDistribution(Set<NamedArea> namedAreas, PresenceAbsenceTermBase presence, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);\r
\r
/**\r
- * Returns a List of TextData elements that match a given queryString provided.\r
+ * Returns a Paged List of DescriptionElementBase instances where the default field matches the String queryString (as interpreted by the Lucene QueryParser)\r
* \r
- * @param queryString \r
- * @param pageSize\r
- * @param pageNumber\r
- * @return\r
- * @throws QueryParseException\r
+ * @param clazz filter the results by class (or pass null to return all DescriptionElementBase instances)\r
+ * @param queryString\r
+ * @param pageSize The maximum number of descriptionElements returned (can be null for all matching descriptionElements)\r
+ * @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)\r
+ * @param orderHints\r
+ * Supports path like <code>orderHints.propertyNames</code> which\r
+ * include *-to-one properties like createdBy.username or\r
+ * authorTeam.persistentTitleCache\r
+ * @param propertyPaths properties to be initialized\r
+ * @return a Pager DescriptionElementBase instances\r
+ * @see <a href="http://lucene.apache.org/java/2_4_0/queryparsersyntax.html">Apache Lucene - Query Parser Syntax</a>\r
*/\r
- public Pager<TextData> searchTextData(String queryString, Integer pageSize, Integer pageNumber);\r
+ public Pager<DescriptionElementBase> searchElements(Class<? extends DescriptionElementBase> clazz, String queryString, Integer pageSize, Integer pageNumber, List<OrderHint> orderHints, List<String> propertyPaths);\r
\r
/**\r
* Returns a List of Media that are associated with a given description element\r
* @param descriptionElement the description element associated with these media\r
* @param pageSize The maximum number of media returned (can be null for all related media)\r
* @param pageNumber The offset (in pageSize chunks) from the start of the result set (0 - based)\r
+ * @param propertyPaths properties to initialize - see {@link BeanInitializer#initialize(Object, List)}\r
* @return a Pager containing media instances\r
*/\r
- public Pager<Media> getMedia(DescriptionElementBase descriptionElement, Integer pageSize, Integer pageNumber);\r
- \r
+ public Pager<Media> getMedia(DescriptionElementBase descriptionElement, Integer pageSize, Integer pageNumber, List<String> propertyPaths);\r
}
\ No newline at end of file