/**
* The contents of this file are subject to the OpenMRS Public License
* Version 1.0 (the "License"); you may not use this file except in
* compliance with the License. You may obtain a copy of the License at
* http://license.openmrs.org
*
* Software distributed under the License is distributed on an "AS IS"
* basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
* License for the specific language governing rights and limitations
* under the License.
*
* Copyright (C) OpenMRS, LLC. All Rights Reserved.
*/
package org.openmrs.api;
import java.util.Iterator;
import java.util.List;
import java.util.Locale;
import java.util.Set;
import org.openmrs.Concept;
import org.openmrs.ConceptAnswer;
import org.openmrs.ConceptClass;
import org.openmrs.ConceptComplex;
import org.openmrs.ConceptDatatype;
import org.openmrs.ConceptDescription;
import org.openmrs.ConceptMap;
import org.openmrs.ConceptName;
import org.openmrs.ConceptNameTag;
import org.openmrs.ConceptNumeric;
import org.openmrs.ConceptProposal;
import org.openmrs.ConceptSet;
import org.openmrs.ConceptSource;
import org.openmrs.ConceptWord;
import org.openmrs.Drug;
import org.openmrs.annotation.Authorized;
import org.openmrs.api.db.ConceptDAO;
import org.openmrs.util.OpenmrsConstants;
import org.springframework.transaction.annotation.Transactional;
/**
* Contains methods pertaining to creating/updating/deleting/retiring Concepts, Drugs, Concept
* Proposals, and all other things 'Concept'.
* <p>
* To get a list of concepts:
*
* <pre>
* List<Concept> concepts = Context.getConceptService().getAllConcepts();
* </pre>
* To get a single concept:
*
* <pre>
* // if there is a concept row in the database with concept_id = 3845
* Concept concept = Context.getConceptService().getConcept(3845);
*
* String name = concept.getPreferredName(Context.getLocale()).getName();
* </pre>
* To save a concept to the database
*
* <pre>
* Concept concept = new Concept();
* concept.setConceptClass(Context.getConceptService().getConceptClass(3));
* concept.setDatatype(Context.getConceptService().getConceptDatatype(17));
* concept.setName...
* ... // and other required values on the concept
* Context.getConceptService().saveConcept(concept);
* </pre>
*
* @see org.openmrs.api.context.Context
*/
@Transactional
public interface ConceptService extends OpenmrsService {
/**
* Sets the data access object for Concepts. The dao is used for saving and getting concepts
* to/from the database
*
* @param dao The data access object to use
*/
public void setConceptDAO(ConceptDAO dao);
/**
* @deprecated use #saveConcept(Concept)
*/
@Deprecated
@Authorized( { OpenmrsConstants.PRIV_MANAGE_CONCEPTS })
public void createConcept(Concept concept) throws APIException;
/**
* @deprecated use #saveConcept(Concept)
*/
@Deprecated
@Authorized( { OpenmrsConstants.PRIV_MANAGE_CONCEPTS })
public void createConcept(ConceptNumeric concept) throws APIException;
/**
* @deprecated use #saveConcept(Concept)
*/
@Deprecated
@Authorized( { OpenmrsConstants.PRIV_MANAGE_CONCEPTS })
public void updateConcept(Concept concept) throws APIException;
/**
* Get Concept by its UUID
*
* @param uuid
* @return
* @should find object given valid uuid
* @should return null if no object found with given uuid
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public Concept getConceptByUuid(String uuid);
/**
* @deprecated use #saveConcept(Concept)
*/
@Deprecated
@Authorized( { OpenmrsConstants.PRIV_MANAGE_CONCEPTS })
public void updateConcept(ConceptNumeric concept) throws APIException;
/**
* @deprecated use #saveDrug(Drug)
*/
@Deprecated
@Authorized( { OpenmrsConstants.PRIV_MANAGE_CONCEPTS })
public void createDrug(Drug drug) throws APIException;
/**
* @deprecated use #saveDrug(Drug)
*/
@Deprecated
@Authorized( { OpenmrsConstants.PRIV_MANAGE_CONCEPTS })
public void updateDrug(Drug drug) throws APIException;
/**
* @deprecated use #purgeConcept(Concept concept)
*/
@Deprecated
@Authorized( { OpenmrsConstants.PRIV_PURGE_CONCEPTS })
public void deleteConcept(Concept concept) throws APIException;
/**
* @deprecated use {@link #retireConcept(Concept, String)}
*/
@Deprecated
@Authorized( { OpenmrsConstants.PRIV_MANAGE_CONCEPTS })
public void voidConcept(Concept concept, String reason) throws APIException;
/**
* Save or update the given <code>Concept</code> or <code>ConceptNumeric</code> in the database
* <p>
* If this is a new concept, the returned concept will have a new {@link Concept#getConceptId()}
* inserted into it that was generated by the database
*
* @param concept The <code>Concept</code> or <code>ConceptNumeric</code> to save or update
* @return the <code>Concept</code> or <code>ConceptNumeric</code> that was saved or updated
* @throws APIException
* @throws ConceptsLockedException
* @throws ConceptInUseException
* @should put generated concept id onto returned concept
* @should create new concept in database
* @should update concept already existing in database
* @should generate id for new concept if none is specified
* @should keep id for new concept if one is specified
* @should save non ConceptNumeric object as conceptNumeric
* @should save a ConceptNumeric as a concept
* @should save a new ConceptNumeric
*/
@Authorized( { OpenmrsConstants.PRIV_MANAGE_CONCEPTS })
public Concept saveConcept(Concept concept) throws APIException;
/**
* Save or update the given <code>Drug</code> in the database. If this is a new drug, the
* returned drug object will have a new {@link Drug#getDrugId()} inserted into it that was
* generated by the database
*
* @param drug The Drug to save or update
* @return the Drug that was saved or updated
* @throws APIException
* @should put generated drug id onto returned drug
* @should create new drug in database
* @should update drug already existing in database
*/
@Authorized( { OpenmrsConstants.PRIV_MANAGE_CONCEPTS })
public Drug saveDrug(Drug drug) throws APIException;
/**
* Completely purge a <code>Concept</code> or <code>ConceptNumeric</code> from the database.
* This should not typically be used unless desperately needed. Most should just be retired. See
* {@link #retireConcept(Concept, String)}
*
* @param conceptOrConceptNumeric The <code>Concept</code> or <code>ConceptNumeric</code> to
* remove from the system
* @throws APIException
*/
@Authorized(OpenmrsConstants.PRIV_PURGE_CONCEPTS)
public void purgeConcept(Concept conceptOrConceptNumeric) throws APIException;
/**
* Retiring a concept essentially removes it from circulation
*
* @param conceptOrConceptNumeric The <code>Concept</code> or <code>ConceptNumeric</code> to
* retire
* @param reason The retire reason
* @return the retired <code>Concept</code> or <code>ConceptNumeric</code>
* @throws APIException
*/
@Authorized(OpenmrsConstants.PRIV_MANAGE_CONCEPTS)
public Concept retireConcept(Concept conceptOrConceptNumeric, String reason) throws APIException;
/**
* Retiring a Drug essentially removes it from circulation
*
* @param drug The Drug to retire
* @param reason The retire reason
* @throws APIException
* @return the retired Drug
*/
@Authorized(OpenmrsConstants.PRIV_MANAGE_CONCEPTS)
public Drug retireDrug(Drug drug, String reason) throws APIException;
/**
* Marks a drug that is currently retired as not retired.
*
* @param drug that is current set as retired
* @return the given drug, marked as not retired now, and saved to the db
* @throws APIException
* @should mark drug as retired
* @should not change attributes of drug that is already retired
*/
@Authorized(OpenmrsConstants.PRIV_MANAGE_CONCEPTS)
public Drug unretireDrug(Drug drug) throws APIException;
/**
* Completely purge a Drug from the database. This should not typically be used unless
* desperately needed. Most Drugs should just be retired.
*
* @param drug The Drug to remove from the system
* @throws APIException
*/
@Authorized(OpenmrsConstants.PRIV_PURGE_CONCEPTS)
public void purgeDrug(Drug drug) throws APIException;
/**
* Gets the concept with the given id
*
* @param conceptId
* @return the matching Concept object
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public Concept getConcept(Integer conceptId) throws APIException;
/**
* Gets the concept-name with the given id
*
* @param conceptNameId
* @return the matching Concept object
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public ConceptName getConceptName(Integer conceptNameId) throws APIException;
/**
* Gets the ConceptAnswer with the given id
*
* @param conceptAnswerId
* @return the matching ConceptAnswer object
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public ConceptAnswer getConceptAnswer(Integer conceptAnswerId) throws APIException;
/**
* Get the Drug with the given id
*
* @param drugId
* @return the matching Drug object
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public Drug getDrug(Integer drugId) throws APIException;
/**
* Get the ConceptNumeric with the given id
*
* @param conceptId The ConceptNumeric id
* @return the matching ConceptNumeric object
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public ConceptNumeric getConceptNumeric(Integer conceptId) throws APIException;
/**
* Return a Concept class matching the given identifier
*
* @throws APIException
* @param conceptClassId the concept class identifier
* @return the matching ConceptClass
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public ConceptClass getConceptClass(Integer conceptClassId) throws APIException;
/**
* Return a list of unretired concepts sorted by concept id ascending and
*
* @return a List<Concept> object containing all of the sorted concepts
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<Concept> getAllConcepts() throws APIException;
/**
* Return a list of concepts sorted on sortBy in dir direction (asc/desc)
*
* @param sortBy The property name to sort by; if null or invalid, concept_id is used.
* @param asc true = sort ascending; false = sort descending
* @param includeRetired If <code>true</code>, retired concepts will also be returned
* @return a List<Concept> object containing all of the sorted concepts
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<Concept> getAllConcepts(String sortBy, boolean asc, boolean includeRetired) throws APIException;
/**
* @deprecated use {@link #getAllConcepts(String, boolean, boolean)}
*/
@Deprecated
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<Concept> getConcepts(String sortBy, String dir) throws APIException;
/**
* Returns a list of concepts matching any part of a concept name, this method is case
* insensitive to the concept name string
*
* @param name The search string
* @throws APIException
* @return a List<Concept> object containing all of the matching concepts
* @should pass irrespective of the case of the passed parameter
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<Concept> getConceptsByName(String name) throws APIException;
/**
* Return a Concept that matches the name exactly
*
* @param name The search string
* @throws APIException
* @return the found Concept
* @should get concept by name
* @should get concept by partial name
* @should return null given null parameter
* @should find concepts with names in more specific locales
* @should find concepts with names in more generic locales
* @should find concepts with names in same specific locale
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public Concept getConceptByName(String name) throws APIException;
/**
* Get Concepts by id or name
* <p>
* Note: this just calls other impl methods; no DAO of its own
*
* @param idOrName
* @return the found Concept
* @deprecated use {@link #getConcept(String)}
* @throws APIException
*/
@Deprecated
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public Concept getConceptByIdOrName(String idOrName) throws APIException;
/**
* Get Concept by id or name convenience method
*
* @param conceptIdOrName
* @return the found Concept
* @throws APIException
* @should return null given null parameter
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public Concept getConcept(String conceptIdOrName) throws APIException;
/**
* Searches for concepts by the given parameters via the ConceptWord table
*
* @param phrase matched to the start of any word in any of the names of a concept
* @param locales List<Locale> to restrict to
* @param includeRetired boolean if false, will exclude retired concepts
* @param requireClasses List<ConceptClass> to restrict to
* @param excludeClasses List<ConceptClass> to leave out of results
* @param requireDatatypes List<ConceptDatatype> to restrict to
* @param excludeDatatypes List<ConceptDatatype> to leave out of results
* @param answersToConcept all results will be a possible answer to this concept
* @param start all results less than this number will be removed
* @param size if non zero, all results after <code>start</code> + <code>size</code> will be
* removed
* @return A List<ConceptWord> object containing all matching ConceptWords
* @throws APIException
* @should return the best matched name
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<ConceptWord> getConceptWords(String phrase, List<Locale> locales, boolean includeRetired,
List<ConceptClass> requireClasses, List<ConceptClass> excludeClasses,
List<ConceptDatatype> requireDatatypes, List<ConceptDatatype> excludeDatatypes,
Concept answersToConcept, Integer start, Integer size) throws APIException;
/**
* Convenience method for
* {@link #getConceptWords(String, List, boolean, List, List, List, List, Concept, Integer, Integer)}
*
* @param phrase search string
* @param locale
* @return List<ConceptWord> object matching search phrase and locale
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<ConceptWord> getConceptWords(String phrase, Locale locale) throws APIException;
/**
* @deprecated Use
* {@link #getConceptWords(String, List, boolean, List, List, List, List, Concept, Integer, Integer)}
*/
@Deprecated
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<ConceptWord> findConcepts(String phrase, Locale locale, boolean includeRetired) throws APIException;
/**
* @deprecated Use
* {@link #getConceptWords(String, List, boolean, List, List, List, List, Concept, Integer, Integer)}
*/
@Deprecated
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<ConceptWord> findConcepts(String phrase, Locale locale, boolean includeRetired,
List<ConceptClass> requireClasses, List<ConceptClass> excludeClasses,
List<ConceptDatatype> requireDatatypes, List<ConceptDatatype> excludeDatatypes)
throws APIException;
/**
* Get Drug by its UUID
*
* @param uuid
* @return
* @should find object given valid uuid
* @should return null if no object found with given uuid
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public Drug getDrugByUuid(String uuid);
/**
* @deprecated Use
* {@link #getConceptWords(String, List, boolean, List, List, List, List, Concept, Integer, Integer)}
*/
@Deprecated
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<ConceptWord> findConcepts(String phrase, Locale locale, boolean includeRetired, int start, int size)
throws APIException;
/**
* Return the drug object corresponding to the given name or drugId
*
* @param drugNameOrId String name or drugId to match exactly on
* @return matching Drug object
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public Drug getDrug(String drugNameOrId) throws APIException;
/**
* Return the drug object corresponding to the given name or drugId
*
* @param drugId String
* @throws APIException
* @return matching Drug object
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public Drug getDrugByNameOrId(String drugId) throws APIException;
/**
* @deprecated use {@link ConceptService#getAllDrugs()}
*/
@Deprecated
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<Drug> getDrugs() throws APIException;
/**
* Return a list of drugs currently in the database that are not retired
*
* @throws APIException
* @return a List<Drug> object containing all drugs
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<Drug> getAllDrugs() throws APIException;
/**
* @deprecated Use {@link #getDrugsByConcept(Concept)}
*/
@Deprecated
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<Drug> getDrugs(Concept concept) throws APIException;
/**
* Return a list of drugs associated with the given concept
*
* @throws APIException
* @param concept
* @return a List<Drug> object containing all matching drugs
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<Drug> getDrugsByConcept(Concept concept) throws APIException;
/**
* Get drugs by concept. This method is the utility method that should be used to generically
* retrieve all Drugs in the system.
*
* @param includeRetired If <code>true</code> then the search will include voided Drugs
* @return A List<Drug> object containing all matching Drugs
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<Drug> getAllDrugs(boolean includeRetired);
/**
* @deprecated Use {@link #getDrugs(String)}
*/
@Deprecated
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<Drug> findDrugs(String phrase, boolean includeVoided) throws APIException;
/**
* Find drugs in the system. The string search can match either drug.name or drug.concept.name
*
* @param phrase Search phrase
* @throws APIException
* @return A List<Drug> object containing all Drug matches
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<Drug> getDrugs(String phrase) throws APIException;
/**
* @param cc ConceptClass
* @return Returns all concepts in a given class
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<Concept> getConceptsByClass(ConceptClass cc) throws APIException;
/**
* Return a list of concept classes currently in the database
*
* @throws APIException
* @return List<ConceptClass> object with all ConceptClass objects
* @deprecated use {@link #getAllConceptClasses(boolean)}
*/
@Deprecated
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPT_CLASSES)
public List<ConceptClass> getConceptClasses() throws APIException;
/**
* Return a Concept class matching the given name
*
* @param name
* @return ConceptClass matching the given name
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPT_CLASSES)
public ConceptClass getConceptClassByName(String name) throws APIException;
/**
* Return a list of concept classes currently in the database
*
* @throws APIException
* @return List<ConceptClass> object with all ConceptClass objects
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPT_CLASSES)
public List<ConceptClass> getAllConceptClasses() throws APIException;
/**
* Return a list of concept classes currently in the database
*
* @param includeRetired include retired concept classes in the search results?
* @throws APIException
* @return List<ConceptClass> object with all ConceptClass objects
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPT_CLASSES)
public List<ConceptClass> getAllConceptClasses(boolean includeRetired) throws APIException;
/**
* Get ConceptClass by its UUID
*
* @param uuid
* @return
* @should find object given valid uuid
* @should return null if no object found with given uuid
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPT_CLASSES)
public ConceptClass getConceptClassByUuid(String uuid);
/**
* Get ConceptAnswer by its UUID
*
* @param uuid
* @return
* @should find object given valid uuid
* @should return null if no object found with given uuid
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public ConceptAnswer getConceptAnswerByUuid(String uuid);
/**
* Get ConceptName by its UUID
*
* @param uuid
* @return
* @should find object given valid uuid
* @should return null if no object found with given uuid
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public ConceptName getConceptNameByUuid(String uuid);
/**
* Get ConceptSet by its UUID
*
* @param uuid
* @return
* @should find object given valid uuid
* @should return null if no object found with given uuid
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public ConceptSet getConceptSetByUuid(String uuid);
/**
* Get ConceptSource by its UUID
*
* @param uuid
* @return
* @should find object given valid uuid
* @should return null if no object found with given uuid
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPT_SOURCES)
public ConceptSource getConceptSourceByUuid(String uuid);
/**
* Creates or updates a concept class
*
* @param cc ConceptClass to create or update
* @throws APIException
*/
@Authorized(OpenmrsConstants.PRIV_MANAGE_CONCEPT_CLASSES)
public ConceptClass saveConceptClass(ConceptClass cc) throws APIException;
/**
* Purge a ConceptClass
*
* @param cc ConceptClass to delete
* @throws APIException
*/
@Authorized(OpenmrsConstants.PRIV_PURGE_CONCEPT_CLASSES)
public void purgeConceptClass(ConceptClass cc) throws APIException;
/**
* Create or update a ConceptDatatype
*
* @param cd ConceptDatatype to create or update
* @throws APIException
*/
@Authorized( { OpenmrsConstants.PRIV_MANAGE_CONCEPT_DATATYPES })
public ConceptDatatype saveConceptDatatype(ConceptDatatype cd) throws APIException;
/**
* Purge a ConceptDatatype. This removes the concept datatype from the database completely.
*
* @param cd ConceptDatatype to purge
* @throws APIException
*/
@Authorized(OpenmrsConstants.PRIV_PURGE_CONCEPT_DATATYPES)
public void purgeConceptDatatype(ConceptDatatype cd) throws APIException;
/**
* Return a list of all concept datatypes currently in the database
*
* @throws APIException
* @return List of ConceptDatatypes
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPT_DATATYPES)
public List<ConceptDatatype> getAllConceptDatatypes() throws APIException;
/**
* Return a list of concept datatypes currently in the database
*
* @param includeRetired boolean - include the retired datatypes?
* @throws APIException
* @return List of ConceptDatatypes
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPT_DATATYPES)
public List<ConceptDatatype> getAllConceptDatatypes(boolean includeRetired) throws APIException;
/**
* Find concept datatypes that contain the given name string
*
* @deprecated you *probably* want to use {@link ConceptService#getConceptDatatypeByName(String)}
* @param name
* @return List<ConceptDatatype> object of ConceptDatatypes matching the string
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPT_DATATYPES)
@Deprecated
public List<ConceptDatatype> getConceptDatatypes(String name) throws APIException;
/**
* Return a ConceptDatatype matching the given identifier
*
* @param i Integer for the requested ConceptDatatype
* @return ConceptDatatype matching the given identifier
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPT_DATATYPES)
public ConceptDatatype getConceptDatatype(Integer i) throws APIException;
/**
* Get ConceptDatatype by its UUID
*
* @param uuid
* @return
* @should find object given valid uuid
* @should return null if no object found with given uuid
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPT_DATATYPES)
public ConceptDatatype getConceptDatatypeByUuid(String uuid);
/**
* Return a Concept datatype matching the given name
*
* @param name
* @return ConceptDatatype matching the given name
* @throws APIException
* @should return an exact match on name
* @should not return a fuzzy match on name
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPT_DATATYPES)
public ConceptDatatype getConceptDatatypeByName(String name) throws APIException;
/**
* Updates the concept set derived business table for this concept (bursting the concept sets)
*
* @param concept
* @throws APIException
*/
@Authorized( { OpenmrsConstants.PRIV_MANAGE_CONCEPTS })
public void updateConceptSetDerived(Concept concept) throws APIException;
/**
* Iterates over all concepts calling updateConceptSetDerived(concept)
*
* @throws APIException
*/
@Authorized( { OpenmrsConstants.PRIV_MANAGE_CONCEPTS })
public void updateConceptSetDerived() throws APIException;
/**
* @deprecated use {@link #getConceptSetsByConcept(Concept)}
*/
@Deprecated
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<ConceptSet> getConceptSets(Concept concept) throws APIException;
/**
* Return a list of the concept sets with concept_set matching concept
* <p>
* For example to find all concepts for ARVs, you would do
* getConceptSets(getConcept("ANTIRETROVIRAL MEDICATIONS")) and then take the conceptIds from
* the resulting list.
*
* @param concept The concept representing the concept set
* @return A List<ConceptSet> object containing all matching ConceptSets
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<ConceptSet> getConceptSetsByConcept(Concept concept) throws APIException;
/**
* @deprecated use {@link #getConceptsByConceptSet(Concept)}
*/
@Deprecated
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<Concept> getConceptsInSet(Concept concept) throws APIException;
/**
* Return a List of all concepts within a concept set
*
* @param concept The concept representing the concept set
* @return A List<Concept> object containing all objects within the ConceptSet
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<Concept> getConceptsByConceptSet(Concept concept) throws APIException;
/**
* Find all sets that the given concept is a member of
*
* @param concept
* @throws APIException
* @return A List<ConceptSet> object with all parent concept sets
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<ConceptSet> getSetsContainingConcept(Concept concept) throws APIException;
/**
* @deprecated use {@link #getAllConceptProposals(boolean)}
*/
@Deprecated
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPT_PROPOSALS)
public List<ConceptProposal> getConceptProposals(boolean includeCompleted) throws APIException;
/**
* Get a List of all concept proposals
*
* @param includeCompleted boolean - include completed proposals as well?
* @return a List<ConceptProposal> object of all found ConceptProposals
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPT_PROPOSALS)
public List<ConceptProposal> getAllConceptProposals(boolean includeCompleted) throws APIException;
/**
* Get ConceptNumeric by its UUID
*
* @param uuid
* @return
* @should find object given valid uuid
* @should return null if no object found with given uuid
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public ConceptNumeric getConceptNumericByUuid(String uuid);
/**
* Get a ConceptProposal by conceptProposalId
*
* @param conceptProposalId the Integer concept proposal Id
* @return the found ConceptProposal
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPT_PROPOSALS)
public ConceptProposal getConceptProposal(Integer conceptProposalId) throws APIException;
/**
* Find matching concept proposals
*
* @param text
* @return a List<ConceptProposal> object containing matching concept proposals
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPT_PROPOSALS)
public List<ConceptProposal> getConceptProposals(String text) throws APIException;
/**
* @deprecated Use {@link #getProposedConcepts(String)}
*/
@Deprecated
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPT_PROPOSALS)
public List<Concept> findProposedConcepts(String text) throws APIException;
/**
* Find matching proposed concepts
*
* @param text
* @return a List<Concept> object containing matching proposed concepts
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPT_PROPOSALS)
public List<Concept> getProposedConcepts(String text) throws APIException;
/**
* Searches on given phrase via the concept word table within a sorted list of Locales
*
* @param phrase String search phrase
* @param searchLocales ordered List of Locales within which to search
* @param includeRetired boolean
* @param requireClasses List<ConceptClass> of <code>ConceptClass</code>es that must be included
* @param excludeClasses List<ConceptClass> of <code>ConceptClass</code>es that must not be
* included
* @param requireDatatypes List<ConceptDatatype> of <code>ConceptDatatype</code>s that must be
* included
* @param excludeDatatypes List<ConceptDatatype>of <code>ConceptDatatype</code>s that must not
* be included
* @return List<ConceptWord> object of ConceptWords matching the criteria
* @see ConceptService#findConcepts(String,Locale,boolean)
*/
@Transactional(readOnly = true)
@Authorized( { "View Concepts" })
public List<ConceptWord> findConcepts(String phrase, List<Locale> searchLocales, boolean includeRetired,
List<ConceptClass> requireClasses, List<ConceptClass> excludeClasses,
List<ConceptDatatype> requireDatatypes, List<ConceptDatatype> excludeDatatypes);
/**
* @deprecated use {@link #saveConceptProposal(ConceptProposal)}
*/
@Deprecated
@Authorized(OpenmrsConstants.PRIV_ADD_CONCEPT_PROPOSALS)
public void proposeConcept(ConceptProposal conceptProposal) throws APIException;
/**
* Saves/updates/proposes a concept proposal
*
* @param conceptProposal The ConceptProposal to save
* @throws APIException
* @return the saved/updated ConceptProposal object
*/
@Authorized( { OpenmrsConstants.PRIV_ADD_CONCEPT_PROPOSALS, OpenmrsConstants.PRIV_EDIT_CONCEPT_PROPOSALS })
public ConceptProposal saveConceptProposal(ConceptProposal conceptProposal) throws APIException;
/**
* Removes a concept proposal from the database entirely.
*
* @param cp
* @throws APIException
*/
@Authorized(OpenmrsConstants.PRIV_PURGE_CONCEPT_PROPOSALS)
public void purgeConceptProposal(ConceptProposal cp) throws APIException;
/**
* Maps a concept proposal to a concept
*
* @param cp
* @param mappedConcept
* @return the mappedConcept
* @throws APIException
*/
@Authorized(OpenmrsConstants.PRIV_MANAGE_CONCEPTS)
public Concept mapConceptProposalToConcept(ConceptProposal cp, Concept mappedConcept) throws APIException;
/**
* @deprecated use {@link ConceptProposal#rejectConceptProposal()}
*/
@Deprecated
@Authorized(OpenmrsConstants.PRIV_EDIT_CONCEPT_PROPOSALS)
public void rejectConceptProposal(ConceptProposal cp) throws APIException;
/**
* @deprecated use {@link ConceptService#getConceptProposals(String)}
*/
@Deprecated
@Authorized(OpenmrsConstants.PRIV_ADD_CONCEPT_PROPOSALS)
public List<ConceptProposal> findMatchingConceptProposals(String text);
/**
* @deprecated use {@link #getConceptAnswers(String, Locale, Concept)}
*/
@Deprecated
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<ConceptWord> findConceptAnswers(String phrase, Locale locale, Concept concept, boolean includeRetired)
throws APIException;
/**
* Finds concepts that are possible value coded answers to concept parameter
*
* @param phrase
* @param locale
* @param concept the answers to match on
* @return List<ConceptWord> object
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<ConceptWord> getConceptAnswers(String phrase, Locale locale, Concept concept) throws APIException;
/**
* @deprecated use #getConceptsByAnswer(Concept)
*/
@Deprecated
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<Concept> getQuestionsForAnswer(Concept concept) throws APIException;
/**
* Returns all possible Concepts to which this concept is a value-coded answer. To navigate in
* the other direction, i.e., from Concept to its answers use Concept.getAnswers()
*
* @param concept
* @return A List<Concept> containing all possible questions to which this concept is a
* valued_Coded answer
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<Concept> getConceptsByAnswer(Concept concept) throws APIException;
/**
* Finds the previous concept in the dictionary that has the next lowest concept id
*
* @param concept the offset Concept
* @return the foundConcept
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public Concept getPrevConcept(Concept concept) throws APIException;
/**
* Finds the next concept in the dictionary that has the next largest concept id
*
* @param concept the offset Concept
* @return the foundConcept
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public Concept getNextConcept(Concept concept) throws APIException;
/**
* Check if the concepts are locked and if so, throw exception during manipulation of concept
*
* @throws ConceptsLockedException
*/
@Transactional(readOnly = true)
public void checkIfLocked() throws ConceptsLockedException;
/**
* Get ConceptProposal by its UUID
*
* @param uuid
* @return
* @should find object given valid uuid
* @should return null if no object found with given uuid
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPT_PROPOSALS)
public ConceptProposal getConceptProposalByUuid(String uuid);
/**
* Convenience method for finding concepts associated with drugs in formulary.
*
* @return A List<Concept> object of all concepts that occur as a Drug.concept.
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<Concept> getConceptsWithDrugsInFormulary() throws APIException;
/**
* Iterates over the words in names and synonyms (for each locale) and updates the concept_word
* table
*
* @param concept
* @throws APIException
*/
@Authorized( { OpenmrsConstants.PRIV_MANAGE_CONCEPTS })
public void updateConceptWord(Concept concept) throws APIException;
/**
* Iterates over all concepts and calls upddateConceptWords(Concept concept)
*
* @throws APIException
*/
@Authorized( { OpenmrsConstants.PRIV_MANAGE_CONCEPTS })
public void updateConceptWords() throws APIException;
/**
* Get ConceptNameTag by its UUID
*
* @param uuid
* @return
* @should find object given valid uuid
* @should return null if no object found with given uuid
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public ConceptNameTag getConceptNameTagByUuid(String uuid);
/**
* Iterates over all concepts with conceptIds between <code>conceptIdStart</code> and
* <code>conceptIdEnd</code> (inclusive) and calls updateConceptWord(concept)
*
* @param conceptIdStart starts update with this concept_id
* @param conceptIdEnd ends update with this concept_id
* @throws APIException
*/
@Authorized( { OpenmrsConstants.PRIV_MANAGE_CONCEPTS })
public void updateConceptWords(Integer conceptIdStart, Integer conceptIdEnd) throws APIException;
/**
* Get a ComplexConcept with the given conceptId
*
* @param conceptId of the ComplexConcept
* @return a ConceptComplex object
* @since 1.5
* @should return a concept complex object
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public ConceptComplex getConceptComplex(Integer conceptId);
/**
* Search for a ConceptNameTag by name
*
* @param tag String name of ConceptNameTag
* @return ConceptNameTag matching the given String tag
*/
@Transactional(readOnly = true)
@Authorized( { OpenmrsConstants.PRIV_VIEW_CONCEPTS })
public ConceptNameTag getConceptNameTagByName(String tag);
/**
* Gets the set of unique Locales used by existing concept names.
*
* @return set of used Locales
*/
@Transactional(readOnly = true)
public Set<Locale> getLocalesOfConceptNames();
/**
* Return a list of concept sources currently in the database that are not voided
*
* @return List of Concept source objects
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPT_SOURCES)
public List<ConceptSource> getAllConceptSources() throws APIException;
/**
* Return a Concept source matching the given concept source id
*
* @param i Integer conceptSourceId
* @return ConceptSource
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPT_SOURCES)
public ConceptSource getConceptSource(Integer i) throws APIException;
/**
* Create a new ConceptSource
*
* @param conceptSource ConceptSource to create
* @throws APIException
* @should not set creator if one is supplied already
* @should not set date created if one is supplied already
* @should save a ConceptSource with a null hl7Code
* @should not save a ConceptSource if voided is null
*/
@Authorized(OpenmrsConstants.PRIV_MANAGE_CONCEPT_SOURCES)
public ConceptSource saveConceptSource(ConceptSource conceptSource) throws APIException;
/**
* Delete ConceptSource
*
* @param cs ConceptSource object delete
* @throws APIException
*/
@Authorized(OpenmrsConstants.PRIV_PURGE_CONCEPT_SOURCES)
public ConceptSource purgeConceptSource(ConceptSource cs) throws APIException;
/**
* This effectively removes a concept source from the database. The source can still be
* referenced by old data, but no new data should use this source.
*
* @param cs the concept source to retire
* @param reason why the concept source is to be retired, must not be empty of null
* @return the retired concept source
* @throws APIException
* @should retire concept source
*/
@Authorized(OpenmrsConstants.PRIV_PURGE_CONCEPT_SOURCES)
public ConceptSource retireConceptSource(ConceptSource cs, String reason) throws APIException;
/**
* Creates a new Concept name tag if none exists. If a tag exists with the same name then that
* existing tag is returned.
*
* @param nameTag the concept name tag to be saved
* @return the newly created or existing concept name tag
* @should save a concept name tag if tag does not exist
* @should not save a concept name tag if tag exists
*/
@Authorized(OpenmrsConstants.PRIV_MANAGE_CONCEPT_NAME_TAGS)
public ConceptNameTag saveConceptNameTag(ConceptNameTag nameTag);
/**
* Gets the highest concept-id used by a concept.
*
* @return highest concept-id
*/
@Transactional(readOnly = true)
public Integer getMaxConceptId();
/**
* Returns an iterator for all concepts, including retired and expired.
*
* @return the Iterator
* @should start with the smallest concept id
* @should iterate over all concepts
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public Iterator<Concept> conceptIterator();
/**
* Looks up a concept via {@link ConceptMap} This will return the {@link Concept} which contains
* a {@link ConceptMap} entry whose <code>sourceCode</code> is equal to the passed
* <code>conceptCode</code> and whose {@link ConceptSource} has either a <code>name</code> or
* <code>hl7Code</code> that is equal to the passed <code>mappingCode</code>
*
* @param conceptCode the code associated with a concept within a given {@link ConceptSource}
* @param mappingCode the name or hl7Code of the {@link ConceptSource} to check
* @return the {@link Concept} that has the given mapping, or null if no {@link Concept} found
* @throws APIException
* @should get concept with given code and and source hl7 code
* @should get concept with given code and source name
* @should return null if code does not exist
* @should return null if mapping does not exist
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public Concept getConceptByMapping(String conceptCode, String mappingCode) throws APIException;
/**
* Get all the concept name tags defined in the database, included voided ones
*
* @return a list of the concept name tags stored in the database
* @since 1.5
*/
@Transactional(readOnly = true)
public List<ConceptNameTag> getAllConceptNameTags();
/**
* Gets the {@link ConceptNameTag} with the given database primary key
*
* @param id the concept name tag id to find
* @return the matching {@link ConceptNameTag} or null if none found
* @since 1.5
*/
@Transactional(readOnly = true)
@Authorized( { OpenmrsConstants.PRIV_VIEW_CONCEPTS })
public ConceptNameTag getConceptNameTag(Integer id);
/**
* Get ConceptDescription by its UUID
*
* @param uuid
* @return
* @should find object given valid uuid
* @should return null if no object found with given uuid
*/
@Transactional(readOnly = true)
@Authorized( { OpenmrsConstants.PRIV_VIEW_CONCEPTS })
public ConceptDescription getConceptDescriptionByUuid(String uuid);
/**
* Lookup a ConceptSource by its name property
*
* @param conceptSourceName
* @return ConceptSource
* @throws APIException
* @should get ConceptSource with the given name
* @should return null if no ConceptSource with that name is found
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPT_SOURCES)
public ConceptSource getConceptSourceByName(String conceptSourceName) throws APIException;
/**
* Looks up a list of ConceptMaps for a given ConceptSource
*
* @param conceptSource
* @return a List<ConceptMap> object
* @throws APIException
* @should return a List of ConceptMaps if concept mappings found
* @should return empty List of ConceptMaps if none found
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public List<ConceptMap> getConceptsByConceptSource(ConceptSource conceptSource) throws APIException;
/**
* Checks if there are any observations (including voided observations) for a concept.
*
* @param concept which used or not used by an observation
* @return boolean true if the concept is used by an observation
* @throws APIException
*/
@Transactional(readOnly = true)
@Authorized(OpenmrsConstants.PRIV_VIEW_CONCEPTS)
public boolean hasAnyObservation(Concept concept);
/**
* Returns the TRUE concept
*
* @return true concept
* @should return the true concept
*/
@Transactional(readOnly = true)
public Concept getTrueConcept();
/**
* Returns the FALSE concept
*
* @return false concept
* @should return the false concept
*/
@Transactional(readOnly = true)
public Concept getFalseConcept();
/**
* Changes the datatype of a concept from boolean to coded when it has observations it is
* associated to.
*
* @param conceptToChange the concept which to change
* @throws APIException
* @should convert the datatype of a boolean concept to coded
* @should fail if the datatype of the concept is not boolean
* @should explicitly add true concept as a value_Coded answer
* @should explicitly add false concept as a value_Coded answer
*/
@Authorized( { OpenmrsConstants.PRIV_MANAGE_CONCEPTS })
public void convertBooleanConceptToCoded(Concept conceptToChange) throws APIException;
}