/**
* 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.Collection;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Set;
import java.util.SortedMap;
import org.openmrs.Concept;
import org.openmrs.ConceptClass;
import org.openmrs.ConceptDatatype;
import org.openmrs.ConceptProposal;
import org.openmrs.EncounterType;
import org.openmrs.FieldType;
import org.openmrs.GlobalProperty;
import org.openmrs.ImplementationId;
import org.openmrs.Location;
import org.openmrs.MimeType;
import org.openmrs.PatientIdentifierType;
import org.openmrs.Privilege;
import org.openmrs.Role;
import org.openmrs.Tribe;
import org.openmrs.annotation.Authorized;
import org.openmrs.api.db.AdministrationDAO;
import org.openmrs.reporting.AbstractReportObject;
import org.openmrs.reporting.Report;
import org.openmrs.util.OpenmrsConstants;
import org.openmrs.util.PrivilegeConstants;
import org.springframework.transaction.annotation.Transactional;
/**
* Contains methods pertaining to doing some administrative tasks in OpenMRS
* <p>
* Use:<br/>
*
* <pre>
* List<GlobalProperty> globalProperties = Context.getAdministrationService().getGlobalProperties();
* </pre>
*
* @see org.openmrs.api.context.Context
*/
@Transactional
public interface AdministrationService extends OpenmrsService {
/**
* Used by Spring to set the specific/chosen database access implementation
*
* @param dao The dao implementation to use
*/
public void setAdministrationDAO(AdministrationDAO dao);
/**
* @deprecated use {@link org.openmrs.api.EncounterService#saveEncounterType(EncounterType)}
*/
public void createEncounterType(EncounterType encounterType) throws APIException;
/**
* @deprecated use {@link org.openmrs.api.EncounterService#saveEncounterType(EncounterType)}
*/
public void updateEncounterType(EncounterType encounterType) throws APIException;
/**
* @deprecated use {@link org.openmrs.api.EncounterService#purgeEncounterType(EncounterType)}
*/
public void deleteEncounterType(EncounterType encounterType) throws APIException;
/**
* @see org.openmrs.api.PatientService#savePatientIdentifierType(PatientIdentifierType)
* @deprecated replaced by
* {@link org.openmrs.api.PatientService#savePatientIdentifierType(PatientIdentifierType)}
*/
public void createPatientIdentifierType(PatientIdentifierType patientIdentifierType) throws APIException;
/**
* @see org.openmrs.api.PatientService#savePatientIdentifierType(PatientIdentifierType)
* @deprecated replaced by
* {@link org.openmrs.api.PatientService#savePatientIdentifierType(PatientIdentifierType)}
*/
public void updatePatientIdentifierType(PatientIdentifierType patientIdentifierType) throws APIException;
/**
* @see org.openmrs.api.PatientService#purgePatientIdentifierType(PatientIdentifierType)
* @deprecated replaced by
* {@link org.openmrs.api.PatientService#purgePatientIdentifierType(PatientIdentifierType)}
*/
public void deletePatientIdentifierType(PatientIdentifierType patientIdentifierType) throws APIException;
/**
* @deprecated The Tribe object is no longer supported. Install the Tribe module
*/
public void createTribe(Tribe tribe) throws APIException;
/**
* @deprecated The Tribe object is no longer supported. Install the Tribe module
*/
public void updateTribe(Tribe tribe) throws APIException;
/**
* @deprecated The Tribe object is no longer supported. Install the Tribe module
*/
public void deleteTribe(Tribe tribe) throws APIException;
/**
* @deprecated The Tribe object is no longer supported. Install the Tribe module
*/
public void retireTribe(Tribe tribe) throws APIException;
/**
* @deprecated The Tribe object is no longer supported. Install the Tribe module
*/
public void unretireTribe(Tribe tribe) throws APIException;
/**
* @deprecated use {@link FormService#saveFieldType(FieldType)}
*/
public void createFieldType(FieldType fieldType) throws APIException;
/**
* @deprecated use {@link FormService#saveFieldType(FieldType)}
*/
public void updateFieldType(FieldType fieldType) throws APIException;
/**
* @deprecated use {@link FormService#purgeFieldType(FieldType)}
*/
public void deleteFieldType(FieldType fieldType) throws APIException;
/**
* @deprecated see {@link org.openmrs.api.ObsService#saveMimeType(MimeType)}
**/
@Authorized(OpenmrsConstants.PRIV_MANAGE_MIME_TYPES)
public void createMimeType(MimeType mimeType) throws APIException;
/**
* @deprecated see {@link org.openmrs.api.ObsService#saveMimeType(MimeType)}
*/
@Authorized(OpenmrsConstants.PRIV_MANAGE_MIME_TYPES)
public void updateMimeType(MimeType mimeType) throws APIException;
/**
* @deprecated see {@link org.openmrs.api.ObsService#purgeMimeType(MimeType)}
*/
@Authorized(OpenmrsConstants.PRIV_MANAGE_MIME_TYPES)
public void deleteMimeType(MimeType mimeType) throws APIException;
/**
* @deprecated see {@link org.openmrs.api.LocationService#saveLocation(Location)}
*/
public void createLocation(Location location) throws APIException;
/**
* @deprecated see {@link org.openmrs.api.LocationService#saveLocation(Location)}
*/
public void updateLocation(Location location) throws APIException;
/**
* @deprecated see {@link org.openmrs.api.LocationService#purgeLocation(Location)}
*/
public void deleteLocation(Location location) throws APIException;
/**
* @deprecated see {@link org.openmrs.api.UserService#saveRole(Role)}
*/
public void createRole(Role role) throws APIException;
/**
* @deprecated see {@link org.openmrs.api.UserService#saveRole(Role)}
*/
public void updateRole(Role role) throws APIException;
/**
* @deprecated see {@link org.openmrs.api.UserService#purgeRole(Role)}
*/
public void deleteRole(Role role) throws APIException;
/**
* @deprecated see {@link org.openmrs.api.UserService#savePrivilege(Privilege)}
*/
public void createPrivilege(Privilege privilege) throws APIException;
/**
* @deprecated see {@link org.openmrs.api.UserService#savePrivilege(Privilege)}
*/
public void updatePrivilege(Privilege privilege) throws APIException;
/**
* @deprecated see {@link org.openmrs.api.UserService#purgePrivilege(Privilege)}
*/
public void deletePrivilege(Privilege privilege) throws APIException;
/**
* Create a new ConceptClass
*
* @param cc ConceptClass to create
* @throws APIException
* @deprecated use {@link org.openmrs.api.ConceptService#saveConceptClass(ConceptClass)}
*/
public void createConceptClass(ConceptClass cc) throws APIException;
/**
* Update ConceptClass
*
* @param cc ConceptClass to update
* @throws APIException
* @deprecated use {@link org.openmrs.api.ConceptService#saveConceptClass(ConceptClass)}
*/
public void updateConceptClass(ConceptClass cc) throws APIException;
/**
* Delete ConceptClass
*
* @param cc ConceptClass to delete
* @throws APIException
* @deprecated use {@link org.openmrs.api.ConceptService#purgeConceptClass(ConceptClass)}
*/
public void deleteConceptClass(ConceptClass cc) throws APIException;
/**
* Create a new ConceptDatatype
*
* @param cd ConceptDatatype to create
* @throws APIException
* @deprecated use {@link org.openmrs.api.ConceptService#saveConceptDatatype(ConceptDatatype)}
*/
public void createConceptDatatype(ConceptDatatype cd) throws APIException;
/**
* Update ConceptDatatype
*
* @param cd ConceptDatatype to update
* @throws APIException
* @deprecated use {@link org.openmrs.api.ConceptService#saveConceptDatatype(ConceptDatatype)}
*/
public void updateConceptDatatype(ConceptDatatype cd) throws APIException;
/**
* Delete ConceptDatatype
*
* @param cd ConceptDatatype to delete
* @throws APIException
* @deprecated use {@link org.openmrs.api#deleteConceptDatatype(ConceptDatatype)}
*/
public void deleteConceptDatatype(ConceptDatatype cd) throws APIException;
/**
* Create a new Report
*
* @param report Report to create
* @throws APIException
* @deprecated see reportingcompatibility module
*/
@Deprecated
public void createReport(Report report) throws APIException;
/**
* Update Report
*
* @param report Report to update
* @deprecated see reportingcompatibility module
* @throws APIException
*/
@Deprecated
public void updateReport(Report report) throws APIException;
/**
* Delete Report
*
* @param report Report to delete
* @throws APIException
* @deprecated see reportingcompatibility module
*/
@Deprecated
public void deleteReport(Report report) throws APIException;
/**
* Create a new Report Object
*
* @param reportObject Report Object to create
* @deprecated see reportingcompatibility module
* @throws APIException
*/
@Deprecated
public void createReportObject(AbstractReportObject reportObject) throws APIException;
/**
* Update Report Object
*
* @param reportObject the Report Object to update
* @deprecated see reportingcompatibility module
* @throws APIException
*/
@Deprecated
public void updateReportObject(AbstractReportObject reportObject) throws APIException;
/**
* Delete Report Object
*
* @param reportObjectId Internal identifier for the Report Object to delete
* @deprecated see reportingcompatibility module
* @throws APIException
*/
@Deprecated
public void deleteReportObject(Integer reportObjectId) throws APIException;
/**
* Iterates over the words in names and synonyms (for each locale) and updates the concept word
* business table
*
* @param concept
* @throws APIException
* @deprecated moved to {@link org.openmrs.api.ConceptService#updateConceptWord(Concept)}
*/
public void updateConceptWord(Concept concept) throws APIException;
/**
* Iterates over all concepts calling updateConceptWord(concept)
*
* @throws APIException
* @deprecated moved to {@link org.openmrs.api.ConceptService#updateConceptWords()}
*/
public void updateConceptWords() throws APIException;
/**
* Iterates over all concepts with conceptIds between <code>conceptIdStart</code> and
* <code>conceptIdEnd</code> (inclusive) calling updateConceptWord(concept)
*
* @throws APIException
* @deprecated moved to
* {@link org.openmrs.api.ConceptService#updateConceptWords(Integer, Integer)}
*/
public void updateConceptWords(Integer conceptIdStart, Integer conceptIdEnd) throws APIException;
/**
* Updates the concept set derived business table for this concept (bursting the concept sets)
*
* @param concept
* @throws APIException
* @deprecated moved to {@link org.openmrs.api.ConceptService#updateConceptSetDerived(Concept)};
*/
public void updateConceptSetDerived(Concept concept) throws APIException;
/**
* Iterates over all concepts calling updateConceptSetDerived(concept)
*
* @throws APIException
* @deprecated moved to {@link org.openmrs.api.ConceptService#updateConceptSetDerived()}
*/
public void updateConceptSetDerived() throws APIException;
/**
* Create a concept proposal
*
* @param cp
* @throws APIException
* @deprecated use {@link org.openmrs.api.ConceptService#saveConceptProposal(ConceptProposal)}
*/
public void createConceptProposal(ConceptProposal cp) throws APIException;
/**
* Update a concept proposal
*
* @param cp
* @throws APIException
* @deprecated use {@link org.openmrs.api.ConceptService#saveConceptProposal(ConceptProposal)}
*/
public void updateConceptProposal(ConceptProposal cp) throws APIException;
/**
* maps a concept proposal to a concept
*
* @param cp
* @param mappedConcept
* @throws APIException
* @deprecated moved to
* {@link org.openmrs.api.ConceptService#mapConceptProposalToConcept(ConceptProposal, Concept)}
*/
public void mapConceptProposalToConcept(ConceptProposal cp, Concept mappedConcept) throws APIException;
/**
* rejects a concept proposal
*
* @param cp
* @deprecated moved to
* {@link org.openmrs.api.ConceptService#rejectConceptProposal(ConceptProposal)}
*/
public void rejectConceptProposal(ConceptProposal cp);
/**
* @param site
* @param start
* @param count
* @deprecated use the mrngen module instead
*/
public void mrnGeneratorLog(String site, Integer start, Integer count);
/**
* @deprecated use the mrngen module instead
*/
@Transactional(readOnly = true)
public Collection<?> getMRNGeneratorLog();
/**
* Get a global property by its uuid. There should be only one of these in the database (well,
* in the world actually). If multiple are found, an error is thrown.
*
* @return the global property matching the given uuid
* @should find object given valid uuid
* @should return null if no object found with given uuid
*/
@Transactional(readOnly = true)
public GlobalProperty getGlobalPropertyByUuid(String uuid) throws APIException;
/**
* Get a listing or important variables used in openmrs
*
* @return a map from variable name to variable value
* @should return all registered system variables
*/
@Transactional(readOnly = true)
@Authorized(PrivilegeConstants.VIEW_ADMIN_FUNCTIONS)
public SortedMap<String, String> getSystemVariables() throws APIException;
/**
* Get a map of all the System Information. Java, user, time, runtime properties, etc
*
* @return a map from variable name to a map of the information
* @should return all system information
*/
@Transactional(readOnly = true)
@Authorized(PrivilegeConstants.VIEW_ADMIN_FUNCTIONS)
public Map<String, Map<String, String>> getSystemInformation() throws APIException;
/**
* Gets the global property that has the given <code>propertyName</code>.
* <p>
* If <code>propertyName</code> is not found in the list of Global Properties currently in the
* database, a null value is returned. This method should not have any authorization check.
*
* @param propertyName property key to look for
* @return value of property returned or null if none
* @see #getGlobalProperty(String, String)
* @should not fail with null propertyName
* @should get property value given valid property name
* @should get property in case sensitive way
*/
@Transactional(readOnly = true)
public String getGlobalProperty(String propertyName) throws APIException;
/**
* Gets the global property that has the given <code>propertyName</code>
* <p>
* If propertyName is not found in the list of Global Properties currently in the database, a
* <code>defaultValue</code> is returned
* <p>
* This method should not have any authorization check
*
* @param propertyName property key to look for
* @param defaultValue value to return if propertyName is not found
* @return value of propertyName property or defaultValue if none
* @should return default value if property name does not exist
* @should not fail with null default value
*/
@Transactional(readOnly = true)
public String getGlobalProperty(String propertyName, String defaultValue) throws APIException;
/**
* Gets the global property that has the given <code>propertyName</code>
*
* @param propertyName property key to look for
* @return the global property that matches the given <code>propertyName</code>
* @should return null when no global property match given property name
*/
@Transactional(readOnly = true)
public GlobalProperty getGlobalPropertyObject(String propertyName);
/**
* Gets all global properties that begin with <code>prefix</code>.
*
* @param prefix The beginning of the property name to match.
* @return a <code>List</code> of <code>GlobalProperty</code>s that match <code>prefix</code>
* @since 1.5
* @should return all relevant global properties in the database
*/
@Transactional(readOnly = true)
public List<GlobalProperty> getGlobalPropertiesByPrefix(String prefix);
/**
* Gets all global properties that end with <code>suffix</code>.
*
* @param prefix The end of the property name to match.
* @return a <code>List</code> of <code>GlobalProperty</code>s that match <code>.*suffix</code>
* @since 1.6
* @should return all relevant global properties in the database
*/
@Transactional(readOnly = true)
public List<GlobalProperty> getGlobalPropertiesBySuffix(String suffix);
/**
* Get a list of all global properties in the system
*
* @return list of global properties
* @should return all global properties in the database
*/
@Transactional(readOnly = true)
@Authorized(PrivilegeConstants.VIEW_GLOBAL_PROPERTIES)
public List<GlobalProperty> getAllGlobalProperties() throws APIException;
/**
* @deprecated use {@link #getAllGlobalProperties()}
*/
@Transactional(readOnly = true)
public List<GlobalProperty> getGlobalProperties();
/**
* Save the given list of global properties to the database overwriting all values with the
* given values. If a value exists in the database that does not exist in the given list, that
* property is deleted from the database.
*
* @param props list of GlobalProperty objects to save
* @return the saved global properties
* @should save all global properties to the database
* @should not fail with empty list
* @should delete property from database if not in list
* @should assign uuid to all new properties
* @should save properties with case difference only
*/
@Authorized(PrivilegeConstants.MANAGE_GLOBAL_PROPERTIES)
public List<GlobalProperty> saveGlobalProperties(List<GlobalProperty> props) throws APIException;
/**
* @deprecated use {@link #saveGlobalProperties(List)}
*/
public void setGlobalProperties(List<GlobalProperty> props);
/**
* Completely remove the given global property from the database
*
* @param globalProperty the global property to delete/remove from the database
* @throws APIException
* @should delete global property from database
*/
@Authorized(PrivilegeConstants.PURGE_GLOBAL_PROPERTIES)
public void purgeGlobalProperty(GlobalProperty globalProperty) throws APIException;
/**
* Use
*
* <pre>
* purgeGlobalProperty(new GlobalProperty(propertyName));
* </pre>
*
* @deprecated use {@link #purgeGlobalProperty(GlobalProperty)}
*/
public void deleteGlobalProperty(String propertyName);
/**
* Use
*
* <pre>
* purgeGlobalProperty(new GlobalProperty(propertyName, propertyValue));
* </pre>
*
* @deprecated use #saveGlobalProperty(GlobalProperty)
*/
public void setGlobalProperty(String propertyName, String propertyValue);
/**
* Save the given global property to the database
*
* @param gp global property to save
* @return the saved global property
* @throws APIException
* @should create global property in database
* @should overwrite global property if exists
* @should allow different properties to have the same string with different case
*/
@Authorized(PrivilegeConstants.MANAGE_GLOBAL_PROPERTIES)
public GlobalProperty saveGlobalProperty(GlobalProperty gp) throws APIException;
/**
* @deprecated use {@link #saveGlobalProperty(GlobalProperty)}
*/
public void setGlobalProperty(GlobalProperty gp);
/**
* @deprecated use {@link #saveGlobalProperty(GlobalProperty)}
*/
public void addGlobalProperty(String propertyName, String propertyValue);
/**
* @deprecated use {@link #saveGlobalProperty(GlobalProperty)}
*/
public void addGlobalProperty(GlobalProperty gp);
/**
* Allows code to be notified when a global property is created/edited/deleted.
*
* @see GlobalPropertyListener
* @param listener The listener to register
*/
public void addGlobalPropertyListener(GlobalPropertyListener listener);
/**
* Removes a GlobalPropertyListener previously registered by
* {@link #addGlobalPropertyListener(GlobalPropertyListener)}
*
* @param listener
*/
public void removeGlobalPropertyListener(GlobalPropertyListener listener);
/**
* Runs the <code>sql</code> on the database. If <code>selectOnly</code> is flagged then any
* non-select sql statements will be rejected.
*
* @param sql
* @param selectOnly
* @return ResultSet
* @throws APIException
* @should execute sql containing group by
*/
@Authorized(PrivilegeConstants.SQL_LEVEL_ACCESS)
public List<List<Object>> executeSQL(String sql, boolean selectOnly) throws APIException;
/**
* Get the implementation id stored for this server Returns null if no implementation id has
* been successfully set yet
*
* @return ImplementationId object that is this implementation's unique id
* @should return null if no implementation id is defined yet
*/
@Transactional(readOnly = true)
@Authorized(PrivilegeConstants.MANAGE_IMPLEMENTATION_ID)
public ImplementationId getImplementationId() throws APIException;
/**
* Set the given <code>implementationId</code> as this implementation's unique id
*
* @param implementationId the ImplementationId to save
* @throws APIException if implementationId is empty or is invalid according to central id
* server
* @should create implementation id in database
* @should overwrite implementation id in database if exists
* @should not fail if given implementationId is null
* @should throw APIException if given empty implementationId object
* @should throw APIException if given a caret in the implementationId code
* @should throw APIException if given a pipe in the implementationId code
* @should set uuid on implementation id global property
*/
@Authorized(PrivilegeConstants.MANAGE_IMPLEMENTATION_ID)
public void setImplementationId(ImplementationId implementationId) throws APIException;
/**
* Gets the list of locales which the administrator has allowed for use on the system. This is
* specified with a global property named
* {@link OpenmrsConstants#GLOBAL_PROPERTY_LOCALE_ALLOWED_LIST}.
*
* @return list of allowed locales
* @should return at least one locale if no locales defined in database yet
* @should not fail if not global property for locales allowed defined yet
* @should not return duplicates even if the global property has them
*/
@Transactional(readOnly = true)
public List<Locale> getAllowedLocales();
/**
* Gets the list of locales for which localized messages are available for the user interface
* (presentation layer). This set includes all the available locales (as indicated by the
* MessageSourceService) filtered by the allowed locales (as indicated by this
* AdministrationService).
*
* @return list of allowed presentation locales TODO change this return type to list?
* @should return at least one locale if no locales defined in database yet
* @should not return more locales than message source service locales
*/
@Transactional(readOnly = true)
public Set<Locale> getPresentationLocales();
/**
* Returns a global property according to the type specified
*
* @param <T>
* @param propertyName
* @should get property value in the proper type specified
* @should return default value if property name does not exist
* @return property value in the type of the default value
* @since 1.7
*/
public <T> T getGlobalPropertyValue(String propertyName, T defaultValue) throws APIException;
}