org.openmrs.api

Interface ObsService

All Superinterfaces:

OpenmrsService

All Known Implementing Classes:

ObsServiceImpl

public interface ObsService
extends OpenmrsService

The ObsService deals with saving and getting Obs to/from the database Usage:

  ObsService obsService = Context.getObsService();
 
  // get the obs for patient with internal identifier of 1235
  List<Obs> someObsList = obsService.getObservationsByPerson(new Patient(1235));
 

There are also a number of convenience methods for extracting obs pertaining to certain Concepts, people, or encounters

See Also:

Obs, Context

Method Summary

Modifier and Type	Method and Description
Obs	getComplexObs(Integer obsId, String view) Deprecated. as of 2.1.0, use getObs(Integer)
ComplexObsHandler	getHandler(Obs obs) Get the ComplexObsHandler associated with a complex observation Returns the ComplexObsHandler.
ComplexObsHandler	getHandler(String key) Get the ComplexObsHandler that has been registered with the given key
Map<String,ComplexObsHandler>	getHandlers() Gets the handlers map registered
Obs	getObs(Integer obsId) Get an observation
Obs	getObsByUuid(String uuid) Get Obs by its UUID
Integer	getObservationCount(List<ConceptName> conceptNames, boolean includeVoided) Gets the number of observations(including voided ones) that are using the specified conceptNames as valueCodedName answers
Integer	getObservationCount(List<Person> whom, List<Encounter> encounters, List<Concept> questions, List<Concept> answers, List<OpenmrsConstants.PERSON_TYPE> personTypes, List<Location> locations, Integer obsGroupId, Date fromDate, Date toDate, boolean includeVoidedObs) This method fetches the count of observations according to the criteria in the given arguments.
Integer	getObservationCount(List<Person> whom, List<Encounter> encounters, List<Concept> questions, List<Concept> answers, List<OpenmrsConstants.PERSON_TYPE> personTypes, List<Location> locations, Integer obsGroupId, Date fromDate, Date toDate, boolean includeVoidedObs, String accessionNumber)
Integer	getObservationCount(List<Person> whom, List<Encounter> encounters, List<Concept> questions, List<Concept> answers, List<OpenmrsConstants.PERSON_TYPE> personTypes, List<Location> locations, List<Visit> visits, Integer obsGroupId, Date fromDate, Date toDate, boolean includeVoidedObs, String accessionNumber)
List<Obs>	getObservations(List<Person> whom, List<Encounter> encounters, List<Concept> questions, List<Concept> answers, List<OpenmrsConstants.PERSON_TYPE> personTypes, List<Location> locations, List<String> sort, Integer mostRecentN, Integer obsGroupId, Date fromDate, Date toDate, boolean includeVoidedObs) This method fetches observations according to the criteria in the given arguments.
List<Obs>	getObservations(List<Person> whom, List<Encounter> encounters, List<Concept> questions, List<Concept> answers, List<OpenmrsConstants.PERSON_TYPE> personTypes, List<Location> locations, List<String> sort, Integer mostRecentN, Integer obsGroupId, Date fromDate, Date toDate, boolean includeVoidedObs, String accessionNumber)
List<Obs>	getObservations(List<Person> whom, List<Encounter> encounters, List<Concept> questions, List<Concept> answers, List<OpenmrsConstants.PERSON_TYPE> personTypes, List<Location> locations, List<String> sort, List<Visit> visits, Integer mostRecentN, Integer obsGroupId, Date fromDate, Date toDate, boolean includeVoidedObs, String accessionNumber)
List<Obs>	getObservations(String searchString) This method searches the obs table based on the given searchString.
List<Obs>	getObservationsByPerson(Person who) Get all Observations for the given person, sorted by obsDatetime ascending.
List<Obs>	getObservationsByPersonAndConcept(Person who, Concept question) Get all nonvoided observations for the given patient with the given concept as the question concept (conceptId)
Obs	getRevisionObs(Obs initialObs) Get Revision Obs for initial Obs
void	purgeObs(Obs obs) Completely remove an observation from the database.
void	purgeObs(Obs obs, boolean cascade) Completely remove an observation from the database.
void	registerHandler(String key, ComplexObsHandler handler) Registers the given handler with the given key If the given String key exists, that handler is overwritten with the given handler
void	registerHandler(String key, String handlerClass) Convenience method for registerHandler(String, ComplexObsHandler)
void	removeHandler(String key) Remove the handler associated with the key from list of available handlers
Obs	saveObs(Obs obs, String changeMessage) Save the given obs to the database.
void	setHandlers(Map<String,ComplexObsHandler> handlers) Add the given map to this service's handlers.
void	setObsDAO(ObsDAO dao) Set the given dao on this obs service.
Obs	unvoidObs(Obs obs) Revive an observation (pull a Lazarus)
Obs	voidObs(Obs obs, String reason) Equivalent to deleting an observation

Methods inherited from interface org.openmrs.api.OpenmrsService

onShutdown, onStartup

Method Detail

setObsDAO

void setObsDAO(ObsDAO dao)

Set the given dao on this obs service. The dao will act as the conduit through with all obs calls get to the database

Parameters:

dao - specific ObsDAO to use for this service

getObs

@Authorized(value="Get Observations")
Obs getObs(Integer obsId)
                                          throws APIException

Get an observation

Parameters:

obsId - integer obsId of observation desired

Returns:

matching Obs

Throws:

APIException - Should get obs matching given obsId

getObsByUuid

@Authorized(value="Get Observations")
Obs getObsByUuid(String uuid)
                                                throws APIException

Get Obs by its UUID

Parameters:

uuid -

Returns:

obs or null Should find object given valid uuid Should return null if no object found with given uuid

Throws:

APIException

getRevisionObs

@Authorized(value="Get Observations")
Obs getRevisionObs(Obs initialObs)

Get Revision Obs for initial Obs

Parameters:

initialObs -

Returns:

obs or null

Since:

2.1 Should find revision obs for given valid obs Should return null if no revision obs found for given obs

saveObs

@Authorized(value={"Add Observations","Edit Observations"})
Obs saveObs(Obs obs,
                                                                        String changeMessage)
                                                                 throws APIException

Save the given obs to the database. The behavior differs for first-time save, and edit.

When you save a new observation to the database:

• the obs you pass in is saved to the database, and its obsId field is filled in
• the obs you pass in is returned
• the changeMesssage parameter is ignored

When you edit an existing observation:

• the values of the obs you pass to this method are written to the database as new obs
• the newly-created obs is returned (i.e. not the one you passed in)
• the obs you passed is marked as voided, with changeMessage as the void reason
• the newly-created obs points back to the voided one via its previousVersion field

Parameters:

obs - the Obs to save to the database

changeMessage - String explaining why obs is being changed. If obs is a new obs, changeMessage is nullable, or if it is being updated, it would be required

Returns:

Obs that was saved to the database

Throws:

APIException - Should create new file from complex data for new obs Should not overwrite file when updating a complex obs Should void the given obs in the database Should create very basic obs and add new obsId Should allow setting properties on obs Should return a different object when updating an obs Should set creator and dateCreated on new obs Should cascade save to child obs groups Should cascade update to new child obs groups Should link original and updated obs Should set void reason message to changeMessage Should not void an Obs with no changes

voidObs

@Authorized(value="Edit Observations")
Obs voidObs(Obs obs,
                                                   String reason)
                                            throws APIException

Equivalent to deleting an observation

Parameters:

obs - Obs to void

reason - String reason it's being voided

Throws:

APIException - Should set voided bit on given obs Should fail if reason parameter is empty

unvoidObs

@Authorized(value="Edit Observations")
Obs unvoidObs(Obs obs)
                                              throws APIException

Revive an observation (pull a Lazarus)

Parameters:

obs - Obs to unvoid

Throws:

APIException - Should unset voided bit on given obs Should cascade unvoid to child grouped obs

purgeObs

@Authorized(value="Delete Observations")
void purgeObs(Obs obs)
                                                throws APIException

Completely remove an observation from the database. This should typically not be called because we don't want to ever lose data. The data really should be voided and then it is not seen in interface any longer (see #voidObs(Obs) for that one) If other things link to this obs, an error will be thrown.

Parameters:

obs -

Throws:

APIException

See Also:

Should delete the given obs from the database

purgeObs

@Authorized(value="Delete Observations")
void purgeObs(Obs obs,
                                                       boolean cascade)
                                                throws APIException

Completely remove an observation from the database. This should typically not be called because we don't want to ever lose data. The data really should be voided and then it is not seen in interface any longer (see #voidObs(Obs) for that one)

Parameters:

obs - the observation to remove from the database

cascade - true/false whether or not to cascade down to other things that link to this observation (like Orders and ObsGroups)

Throws:

APIException

See Also:

Should throw APIException if given true cascade Should delete any obsGroupMembers before deleting the obs Should not delete referenced orders when purging obs

getObservationsByPerson

@Authorized(value="Get Observations")
List<Obs> getObservationsByPerson(Person who)

Get all Observations for the given person, sorted by obsDatetime ascending. Does not return voided observations.

Parameters:

who - the user to match on

Returns:

a List<Obs> object containing all non-voided observations for the specified person

See Also:

Should get all observations assigned to given person

getObservations

@Authorized(value="Get Observations")
List<Obs> getObservations(List<Person> whom,
                                                                List<Encounter> encounters,
                                                                List<Concept> questions,
                                                                List<Concept> answers,
                                                                List<OpenmrsConstants.PERSON_TYPE> personTypes,
                                                                List<Location> locations,
                                                                List<String> sort,
                                                                Integer mostRecentN,
                                                                Integer obsGroupId,
                                                                Date fromDate,
                                                                Date toDate,
                                                                boolean includeVoidedObs)
                                                         throws APIException

This method fetches observations according to the criteria in the given arguments. All arguments are optional and nullable. If more than one argument is non-null, the result is equivalent to an "and"ing of the arguments. (e.g. if both a location and a fromDate are given, only Obs that are both at that Location and after the fromDate are returned).

Note: If whom has elements, personType is ignored

Note: to get all observations on a certain date, use:
Date fromDate = "2009-08-15";
Date toDate = OpenmrsUtil.lastSecondOfDate(fromDate); List<Obs> obs = getObservations(...., fromDate, toDate, ...);

Parameters:

whom - List<Person> to restrict obs to (optional)

encounters - List<Encounter> to restrict obs to (optional)

questions - List<Concept> to restrict the obs to (optional)

answers - List<Concept> to restrict the valueCoded to (optional)

personTypes - List<PERSON_TYPE> objects to restrict this to. Only used if whom is an empty list (optional)

locations - The org.openmrs.Location objects to restrict to (optional)

sort - list of column names to sort on (obsId, obsDatetime, etc) if null, defaults to obsDatetime (optional)

mostRecentN - restrict the number of obs returned to this size (optional)

obsGroupId - the Obs.getObsGroupId() to this integer (optional)

fromDate - the earliest Obs date to get (optional)

toDate - the latest Obs date to get (optional)

includeVoidedObs - true/false whether to also include the voided obs (required)

Returns:

list of Observations that match all of the criteria given in the arguments

Throws:

APIException

getObservations

@Authorized(value="Get Observations")
List<Obs> getObservations(List<Person> whom,
                                                                List<Encounter> encounters,
                                                                List<Concept> questions,
                                                                List<Concept> answers,
                                                                List<OpenmrsConstants.PERSON_TYPE> personTypes,
                                                                List<Location> locations,
                                                                List<String> sort,
                                                                Integer mostRecentN,
                                                                Integer obsGroupId,
                                                                Date fromDate,
                                                                Date toDate,
                                                                boolean includeVoidedObs,
                                                                String accessionNumber)
                                                         throws APIException

Parameters:

whom - List<Person> to restrict obs to (optional)

encounters - List<Encounter> to restrict obs to (optional)

questions - List<Concept> to restrict the obs to (optional)

answers - List<Concept> to restrict the valueCoded to (optional)

personTypes - List<PERSON_TYPE> objects to restrict this to. Only used if whom is an empty list (optional)

locations - The org.openmrs.Location objects to restrict to (optional)

sort - list of column names to sort on (obsId, obsDatetime, etc) if null, defaults to obsDatetime (optional)

mostRecentN - restrict the number of obs returned to this size (optional)

obsGroupId - the Obs.getObsGroupId() to this integer (optional)

fromDate - the earliest Obs date to get (optional)

toDate - the latest Obs date to get (optional)

includeVoidedObs - true/false whether to also include the voided obs (required)

accessionNumber - accession number (optional)

Returns:

list of Observations that match all of the criteria given in the arguments

Throws:

APIException - Should compare dates using lte and gte Should get all obs assigned to given encounters Should get all obs with question concept in given questions parameter Should get all obs with answer concept in given answers parameter Should return all obs whose person is a person only Should return obs whose person is a patient only Should return obs whose person is a user only Should return obs with location in given locations parameter Should sort returned obs by obsDatetime if sort is empty Should sort returned obs by conceptId if sort is concept Should limit number of obs returned to mostReturnN parameter Should return obs whose groupId is given obsGroupId Should not include voided obs Should include voided obs if includeVoidedObs is true Should only return observations with matching accession number

Since:

1.12

See Also:

This method works exactly the same; it only adds accession number search criteria. It effectively surpasses the above method; the old one is however kept for backward compatibility reasons.

getObservationCount

@Authorized(value="Get Observations")
Integer getObservationCount(List<Person> whom,
                                                                  List<Encounter> encounters,
                                                                  List<Concept> questions,
                                                                  List<Concept> answers,
                                                                  List<OpenmrsConstants.PERSON_TYPE> personTypes,
                                                                  List<Location> locations,
                                                                  Integer obsGroupId,
                                                                  Date fromDate,
                                                                  Date toDate,
                                                                  boolean includeVoidedObs)
                                                           throws APIException

This method fetches the count of observations according to the criteria in the given arguments. All arguments are optional and nullable. If more than one argument is non-null, the result is equivalent to an "and"ing of the arguments. (e.g. if both a location and a fromDate are given, only Obs that are both at that Location and after the fromDate are returned).

Note: If whom has elements, personType is ignored

Note: to get all observations count on a certain date, use:
Date fromDate = "2009-08-15";
Date toDate = OpenmrsUtil.lastSecondOfDate(fromDate); List<Obs> obs = getObservations(...., fromDate, toDate, ...);

Parameters:

whom - List<Person> to restrict obs to (optional)

encounters - List<Encounter> to restrict obs to (optional)

questions - List<Concept> to restrict the obs to (optional)

answers - List<Concept> to restrict the valueCoded to (optional)

personTypes - List<PERSON_TYPE> objects to restrict this to. Only used if whom is an empty list (optional)

locations - The org.openmrs.Location objects to restrict to (optional) obsDatetime (optional)

obsGroupId - the Obs.getObsGroupId() to this integer (optional)

fromDate - the earliest Obs date to get (optional)

toDate - the latest Obs date to get (optional)

includeVoidedObs - true/false whether to also include the voided obs (required)

Returns:

list of Observations that match all of the criteria given in the arguments

Throws:

APIException

getObservationCount

@Authorized(value="Get Observations")
Integer getObservationCount(List<Person> whom,
                                                                  List<Encounter> encounters,
                                                                  List<Concept> questions,
                                                                  List<Concept> answers,
                                                                  List<OpenmrsConstants.PERSON_TYPE> personTypes,
                                                                  List<Location> locations,
                                                                  Integer obsGroupId,
                                                                  Date fromDate,
                                                                  Date toDate,
                                                                  boolean includeVoidedObs,
                                                                  String accessionNumber)
                                                           throws APIException

Parameters:

whom - List<Person> to restrict obs to (optional)

encounters - List<Encounter> to restrict obs to (optional)

questions - List<Concept> to restrict the obs to (optional)

answers - List<Concept> to restrict the valueCoded to (optional)

personTypes - List<PERSON_TYPE> objects to restrict this to. Only used if whom is an empty list (optional)

locations - The org.openmrs.Location objects to restrict to (optional) obsDatetime (optional)

obsGroupId - the Obs.getObsGroupId() to this integer (optional)

fromDate - the earliest Obs date to get (optional)

toDate - the latest Obs date to get (optional)

includeVoidedObs - true/false whether to also include the voided obs (required)

accessionNumber - accession number (optional)

Returns:

list of Observations that match all of the criteria given in the arguments

Throws:

APIException - Should compare dates using lte and gte Should get the count of all obs assigned to given encounters Should get the count of all obs with question concept in given questions parameter Should get the count of all obs with answer concept in given answers parameter Should return the count of all obs whose person is a person only Should return the count of all obs whose person is a patient only Should return the count of obs whose person is a user only Should return the count of obs with location in given locations parameter Should return the count of obs whose groupId is given obsGroupId Should not include count of voided obs Should include count of voided obs if includeVoidedObs is true Should return count of obs with matching accession number

Since:

1.12

See Also:

This method works exactly the same; it only adds accession number search criteria. It effectively surpasses the above method; the old one is however kept for backward compatibility reasons.

getObservations

@Authorized(value="Get Observations")
List<Obs> getObservations(String searchString)
                                                         throws APIException

This method searches the obs table based on the given searchString.

Parameters:

searchString - The string to search on

Returns:

observations matching the given string

Throws:

APIException - Should get obs matching patient identifier in searchString Should get obs matching encounterId in searchString Should get obs matching obsId in searchString

getObservationsByPersonAndConcept

@Authorized(value="Get Observations")
List<Obs> getObservationsByPersonAndConcept(Person who,
                                                                                  Concept question)
                                                                           throws APIException

Get all nonvoided observations for the given patient with the given concept as the question concept (conceptId)

Parameters:

who - person to match on

question - conceptId to match on

Returns:

list of all nonvoided observations matching these criteria

Throws:

APIException

See Also:

Should get observations matching person and question Should not fail with null person parameter

getComplexObs

@Deprecated
 @Authorized(value="Get Observations")
Obs getComplexObs(Integer obsId,
                                                                     String view)
                                                              throws APIException

Deprecated. as of 2.1.0, use getObs(Integer)

Get a complex observation. If obs.isComplex() is true, then returns an Obs with its ComplexData. Otherwise returns a simple Obs.

Parameters:

obsId -

Returns:

Obs with a ComplexData

Throws:

APIException

Since:

1.5 Should fill in complex data object for complex obs Should return normal obs for non complex obs Should not fail with null view

getHandler

ComplexObsHandler getHandler(String key)
                      throws APIException

Get the ComplexObsHandler that has been registered with the given key

Parameters:

key - that has been registered with a handler class

Returns:

Object representing the handler for the given key

Throws:

APIException

Since:

1.5 Should get handler with matching key Should have default image and text handlers registered by spring

getHandler

ComplexObsHandler getHandler(Obs obs)
                      throws APIException

Get the ComplexObsHandler associated with a complex observation Returns the ComplexObsHandler. Returns null if the Obs.isComplexObs() is false or there is an error instantiating the handler class.

Parameters:

obs - A complex Obs.

Returns:

ComplexObsHandler for the complex Obs. or null on error.

Throws:

APIException

Since:

1.12 Should get handler associated with complex observation

setHandlers

void setHandlers(Map<String,ComplexObsHandler> handlers)
          throws APIException

Add the given map to this service's handlers. This method registers each ComplexObsHandler to this service. If the given String key exists, that handler is overwritten with the given handler For most situations, this map is set via spring, see the applicationContext-service.xml file to add more handlers.

Parameters:

handlers - Map of class to handler object

Throws:

APIException

Since:

1.5 Should override handlers with same key Should add new handlers with new keys

getHandlers

Map<String,ComplexObsHandler> getHandlers()
                                   throws APIException

Gets the handlers map registered

Returns:

map of keys to handlers

Throws:

APIException - Should never return null

Since:

1.5

registerHandler

void registerHandler(String key,
                     ComplexObsHandler handler)
              throws APIException

Registers the given handler with the given key If the given String key exists, that handler is overwritten with the given handler

Parameters:

key - the key name to use for this handler

handler - the class to register with this key

Throws:

APIException

Since:

1.5 Should register handler with the given key

registerHandler

void registerHandler(String key,
                     String handlerClass)
              throws APIException

Convenience method for registerHandler(String, ComplexObsHandler)

Parameters:

key - the key name to use for this handler

handlerClass - the class to register with this key

Throws:

APIException

Since:

1.5 Should load handler and register key

removeHandler

void removeHandler(String key)
            throws APIException

Remove the handler associated with the key from list of available handlers

Parameters:

key - the key of the handler to unregister

Throws:

APIException

Since:

1.5 Should remove handler with matching key Should not fail with invalid key

getObservationCount

@Authorized(value="Get Observations")
Integer getObservationCount(List<ConceptName> conceptNames,
                                                                  boolean includeVoided)

Gets the number of observations(including voided ones) that are using the specified conceptNames as valueCodedName answers

Parameters:

conceptNames - the conceptNames to be searched against

includeVoided - whether voided observation should be included

Returns:

The number of observations using the specified conceptNames as valueCodedNames Should return the count of all observations using the specified conceptNames as answers Should include voided observations using the specified conceptNames as answers Should return zero if no observation is using any of the concepNames in the list

Since:

Version 1.7

getObservations

@Authorized(value="Get Observations")
List<Obs> getObservations(List<Person> whom,
                                                                List<Encounter> encounters,
                                                                List<Concept> questions,
                                                                List<Concept> answers,
                                                                List<OpenmrsConstants.PERSON_TYPE> personTypes,
                                                                List<Location> locations,
                                                                List<String> sort,
                                                                List<Visit> visits,
                                                                Integer mostRecentN,
                                                                Integer obsGroupId,
                                                                Date fromDate,
                                                                Date toDate,
                                                                boolean includeVoidedObs,
                                                                String accessionNumber)
                                                         throws APIException

Parameters:

visits - List<Visit> to restrict obs to (optional)

Throws:

APIException

Since:

2.7.0

See Also:

This method works exactly the same; it only adds visits to the search criteria. It effectively surpasses the above method; the old one is however kept for backward compatibility reasons.

getObservationCount

@Authorized(value="Get Observations")
Integer getObservationCount(List<Person> whom,
                                                                  List<Encounter> encounters,
                                                                  List<Concept> questions,
                                                                  List<Concept> answers,
                                                                  List<OpenmrsConstants.PERSON_TYPE> personTypes,
                                                                  List<Location> locations,
                                                                  List<Visit> visits,
                                                                  Integer obsGroupId,
                                                                  Date fromDate,
                                                                  Date toDate,
                                                                  boolean includeVoidedObs,
                                                                  String accessionNumber)
                                                           throws APIException

Parameters:

visits - List<Visit> to restrict obs to (optional)

Throws:

APIException

Since:

2.7.0

See Also:

This method works exactly the same; it only adds visits to the search criteria. It effectively surpasses the above method; the old one is however kept for backward compatibility reasons.