org.openmrs.api

Interface LocationService

All Superinterfaces:

OpenmrsService

All Known Implementing Classes:

LocationServiceImpl

@Transactional
public interface LocationService
extends OpenmrsService

API methods for managing Locations

Example Usage:
List locations = Context.getLocationService().getAllLocations();

See Also:

Context, Location

Method Summary

Modifier and Type	Method and Description
java.lang.String	getAddressTemplate() Returns the xml of default address template.
java.util.List<LocationAttributeType>	getAllLocationAttributeTypes()
java.util.List<Location>	getAllLocations() Returns all locations, includes retired locations.
java.util.List<Location>	getAllLocations(boolean includeRetired) Returns all locations.
java.util.List<LocationTag>	getAllLocationTags() Returns all location tags, includes retired location tags.
java.util.List<LocationTag>	getAllLocationTags(boolean includeRetired) Returns all location tags.
java.lang.Integer	getCountOfLocations(java.lang.String nameFragment, java.lang.Boolean includeRetired) Return the number of all locations that start with the given name fragment, if the name fragment is null or an empty string, then the number of all locations will be returned
Location	getDefaultLocation() Returns the default location for this implementation.
Location	getLocation(java.lang.Integer locationId) Returns a location given that locations primary key locationId A null value is returned if no location exists with this location.
Location	getLocation(java.lang.String name) Returns a location given the location's exact name A null value is returned if there is no location with this name
LocationAttribute	getLocationAttributeByUuid(java.lang.String uuid)
LocationAttributeType	getLocationAttributeType(java.lang.Integer id)
LocationAttributeType	getLocationAttributeTypeByUuid(java.lang.String uuid)
Location	getLocationByUuid(java.lang.String uuid) Returns a location by uuid
java.util.List<Location>	getLocations(java.lang.String nameFragment) Returns locations that match the beginning of the given string.
java.util.List<Location>	getLocations(java.lang.String nameFragment, boolean includeRetired, java.lang.Integer start, java.lang.Integer length) Deprecated. replaced by getLocations(String, org.openmrs.Location, java.util.Map, boolean, Integer, Integer)
java.util.List<Location>	getLocations(java.lang.String nameFragment, Location parent, java.util.Map<LocationAttributeType,java.lang.Object> attributeValues, boolean includeRetired, java.lang.Integer start, java.lang.Integer length) Gets the locations matching the specified arguments.
java.util.List<Location>	getLocationsByTag(LocationTag tag) Returns locations that contain the given tag.
java.util.List<Location>	getLocationsHavingAllTags(java.util.List<LocationTag> tags) Returns locations that are mapped to all given tags.
java.util.List<Location>	getLocationsHavingAnyTag(java.util.List<LocationTag> tags) Returns locations that are mapped to any of the given tags.
LocationTag	getLocationTag(java.lang.Integer locationTagId) Returns a location tag given that locations primary key locationTagId.
LocationTag	getLocationTagByName(java.lang.String tag) Returns a location tag given the location's exact name (tag).
LocationTag	getLocationTagByUuid(java.lang.String uuid) Returns a location tag by uuid
java.util.List<LocationTag>	getLocationTags(java.lang.String search) Returns location tags that match the beginning of the given string.
java.util.List<java.lang.String>	getPossibleAddressValues(Address incomplete, java.lang.String fieldName) Given an Address object, returns all the possible values for the specified AddressField.
java.util.List<Location>	getRootLocations(boolean includeRetired) Returns all root locations (i.e.
void	purgeLocation(Location location) Completely remove a location from the database (not reversible) This method delegates to #purgeLocation(location, boolean) method
void	purgeLocationAttributeType(LocationAttributeType locationAttributeType) Completely removes a location attribute type from the database
void	purgeLocationTag(LocationTag tag) Completely remove a location tag from the database (not reversible).
Location	retireLocation(Location location, java.lang.String reason) Retires the given location.
LocationAttributeType	retireLocationAttributeType(LocationAttributeType locationAttributeType, java.lang.String reason) Retires the given location attribute type in the database
LocationTag	retireLocationTag(LocationTag tag, java.lang.String reason) Retire the given location tag.
void	saveAddressTemplate(java.lang.String xml) Saved default address template to global properties
Location	saveLocation(Location location) Save location to database (create if new or update if changed)
LocationAttributeType	saveLocationAttributeType(LocationAttributeType locationAttributeType) Creates or updates the given location attribute type in the database
LocationTag	saveLocationTag(LocationTag tag) Save location tag to database (create if new or update if changed)
void	setLocationDAO(LocationDAO dao) Set the data access object that the service will use to interact with the database.
Location	unretireLocation(Location location) Unretire the given location.
LocationAttributeType	unretireLocationAttributeType(LocationAttributeType locationAttributeType) Restores a location attribute type that was previous retired in the database
LocationTag	unretireLocationTag(LocationTag tag) Unretire the given location tag.

Methods inherited from interface org.openmrs.api.OpenmrsService

onShutdown, onStartup

Method Detail

setLocationDAO

void setLocationDAO(LocationDAO dao)

Set the data access object that the service will use to interact with the database. This is set by spring in the applicationContext-service.xml file

Parameters:

dao -

saveLocation

@Authorized(value="Manage Locations")
Location saveLocation(Location location)
                                                     throws APIException

Save location to database (create if new or update if changed)

Parameters:

location - is the location to be saved to the database

Throws:

APIException

getLocation

@Transactional(readOnly=true)
 @Authorized(value="View Locations")
Location getLocation(java.lang.Integer locationId)
                                                                                 throws APIException

Returns a location given that locations primary key locationId A null value is returned if no location exists with this location.

Parameters:

locationId - integer primary key of the location to find

Returns:

Location object that has location.locationId = locationId passed in.

Throws:

APIException

getLocation

@Transactional(readOnly=true)
 @Authorized(value="View Locations")
Location getLocation(java.lang.String name)
                                                                                 throws APIException

Returns a location given the location's exact name A null value is returned if there is no location with this name

Parameters:

name - the exact name of the location to match on

Returns:

Location matching the name to Location.name

Throws:

APIException

getDefaultLocation

@Transactional(readOnly=true)
 @Authorized(value="View Locations")
Location getDefaultLocation()
                                                                                        throws APIException

Returns the default location for this implementation.

Returns:

The default location for this implementation.

Throws:

APIException

getLocationByUuid

@Transactional(readOnly=true)
 @Authorized(value="View Locations")
Location getLocationByUuid(java.lang.String uuid)
                                                                                       throws APIException

Returns a location by uuid

Parameters:

uuid - is the uuid of the desired location

Returns:

location with the given uuid

Throws:

APIException

getLocationTagByUuid

@Transactional(readOnly=true)
 @Authorized(value="View Locations")
LocationTag getLocationTagByUuid(java.lang.String uuid)
                                                                                             throws APIException

Returns a location tag by uuid

Parameters:

uuid - is the uuid of the desired location tag

Returns:

location tag with the given uuid

Throws:

APIException

getAllLocations

@Transactional(readOnly=true)
 @Authorized(value="View Locations")
java.util.List<Location> getAllLocations()
                                                                                                     throws APIException

Returns all locations, includes retired locations. This method delegates to the #getAllLocations(boolean) method

Returns:

locations that are in the database

Throws:

APIException

getAllLocations

@Transactional(readOnly=true)
 @Authorized(value="View Locations")
java.util.List<Location> getAllLocations(boolean includeRetired)
                                                                                                     throws APIException

Returns all locations.

Parameters:

includeRetired - whether or not to include retired locations

Throws:

APIException

getLocations

@Transactional(readOnly=true)
 @Authorized(value="View Locations")
java.util.List<Location> getLocations(java.lang.String nameFragment)
                                                                                                  throws APIException

Returns locations that match the beginning of the given string. A null list will never be returned. An empty list will be returned if there are no locations. Search is case insensitive. matching this nameFragment

Parameters:

nameFragment - is the string used to search for locations

Throws:

APIException

getLocations

@Deprecated
 @Transactional(readOnly=true)
 @Authorized(value="View Locations")
java.util.List<Location> getLocations(java.lang.String nameFragment,
                                                                                                                      boolean includeRetired,
                                                                                                                      java.lang.Integer start,
                                                                                                                      java.lang.Integer length)
                                                                                                               throws APIException

Deprecated. replaced by getLocations(String, org.openmrs.Location, java.util.Map, boolean, Integer, Integer)

Returns a specific number locations from the specified starting position that match the beginning of the given string. A null list will never be returned. An empty list will be returned if there are no locations. Search is case insensitive. matching this nameFragment. If start and length are not specified, then all matches are returned

Parameters:

nameFragment - is the string used to search for locations

includeRetired - Specifies if retired locations should be returned

start - the beginning index

length - the number of matching locations to return

Throws:

APIException

Since:

1.8

getLocations

@Transactional(readOnly=true)
 @Authorized(value="View Locations")
java.util.List<Location> getLocations(java.lang.String nameFragment,
                                                                                                         Location parent,
                                                                                                         java.util.Map<LocationAttributeType,java.lang.Object> attributeValues,
                                                                                                         boolean includeRetired,
                                                                                                         java.lang.Integer start,
                                                                                                         java.lang.Integer length)
                                                                                                  throws APIException

Gets the locations matching the specified arguments. A null list will never be returned. An empty list will be returned if there are no locations. Search is case insensitive. matching this nameFragment. If start and length are not specified, then all matches are returned.

Parameters:

nameFragment - is the string used to search for locations

parent - only return children of this parent

attributeValues - the attribute values

includeRetired - specifies if retired locations should also be returned

start - the beginning index

length - the number of matching locations to return

Returns:

the list of locations

Throws:

APIException

Since:

1.9.4

getLocationsByTag

@Transactional(readOnly=true)
 @Authorized(value="View Locations")
java.util.List<Location> getLocationsByTag(LocationTag tag)
                                                                                                       throws APIException

Returns locations that contain the given tag.

Parameters:

tag - LocationTag criterion

Throws:

APIException

Since:

1.5

getLocationsHavingAllTags

@Transactional(readOnly=true)
 @Authorized(value="View Locations")
java.util.List<Location> getLocationsHavingAllTags(java.util.List<LocationTag> tags)
                                                                                                               throws APIException

Returns locations that are mapped to all given tags.

Parameters:

tags - Set of LocationTag criteria

Throws:

APIException

Since:

1.5

getLocationsHavingAnyTag

@Transactional(readOnly=true)
 @Authorized(value="View Locations")
java.util.List<Location> getLocationsHavingAnyTag(java.util.List<LocationTag> tags)
                                                                                                              throws APIException

Returns locations that are mapped to any of the given tags.

Parameters:

tags - Set of LocationTag criteria

Throws:

APIException

Since:

1.5

retireLocation

@Authorized(value="Manage Locations")
Location retireLocation(Location location,
                                                              java.lang.String reason)
                                                       throws APIException

Retires the given location. This effectively removes the location from circulation or use.

Parameters:

location - location to be retired

reason - is the reason why the location is being retired

Throws:

APIException

unretireLocation

@Authorized(value="Manage Locations")
Location unretireLocation(Location location)
                                                         throws APIException

Unretire the given location. This restores a previously retired location back into circulation and use.

Parameters:

location -

Returns:

the newly unretired location

Throws:

APIException

purgeLocation

@Authorized(value="Purge Locations")
void purgeLocation(Location location)
                                                 throws APIException

Completely remove a location from the database (not reversible) This method delegates to #purgeLocation(location, boolean) method

Parameters:

location - the Location to clean out of the database.

Throws:

APIException

saveLocationTag

@Authorized(value="Manage Location Tags")
LocationTag saveLocationTag(LocationTag tag)
                                                               throws APIException

Save location tag to database (create if new or update if changed)

Parameters:

tag - is the tag to be saved to the database

Throws:

APIException

Since:

1.5

getLocationTag

@Transactional(readOnly=true)
 @Authorized(value="View Locations")
LocationTag getLocationTag(java.lang.Integer locationTagId)
                                                                                       throws APIException

Returns a location tag given that locations primary key locationTagId. A null value is returned if no tag exists with this ID.

Parameters:

locationTagId - integer primary key of the location tag to find

Returns:

LocationTag object that has LocationTag.locationTagId = locationTagId passed in.

Throws:

APIException

Since:

1.5

getLocationTagByName

@Transactional(readOnly=true)
 @Authorized(value="View Locations")
LocationTag getLocationTagByName(java.lang.String tag)
                                                                                             throws APIException

Returns a location tag given the location's exact name (tag). A null value is returned if there is no tag with this name.

Parameters:

tag - the exact name of the tag to match on

Returns:

LocationTag matching the name to LocationTag.tag

Throws:

APIException

Since:

1.5

getAllLocationTags

@Transactional(readOnly=true)
 @Authorized(value="View Locations")
java.util.List<LocationTag> getAllLocationTags()
                                                                                                           throws APIException

Returns all location tags, includes retired location tags. This method delegates to the #getAllLocationTags(boolean) method.

Returns:

location tags that are in the database

Throws:

APIException

Since:

1.5

getAllLocationTags

@Transactional(readOnly=true)
 @Authorized(value="View Locations")
java.util.List<LocationTag> getAllLocationTags(boolean includeRetired)
                                                                                                           throws APIException

Returns all location tags.

Parameters:

includeRetired - whether or not to include retired location tags

Throws:

APIException

Since:

1.5

getLocationTags

@Transactional(readOnly=true)
 @Authorized(value="View Locations")
java.util.List<LocationTag> getLocationTags(java.lang.String search)
                                                                                                        throws APIException

Returns location tags that match the beginning of the given string. A null list will never be returned. An empty list will be returned if there are no tags. Search is case insensitive. matching this search

Parameters:

search - is the string used to search for tags

Throws:

APIException

Since:

1.5

retireLocationTag

@Authorized(value="Manage Location Tags")
LocationTag retireLocationTag(LocationTag tag,
                                                                        java.lang.String reason)
                                                                 throws APIException

Retire the given location tag. This effectively removes the tag from circulation or use.

Parameters:

tag - location tag to be retired

reason - is the reason why the location tag is being retired

Throws:

APIException

Since:

1.5

unretireLocationTag

@Authorized(value="Manage Location Tags")
LocationTag unretireLocationTag(LocationTag tag)
                                                                   throws APIException

Unretire the given location tag. This restores a previously retired tag back into circulation and use.

Parameters:

tag -

Returns:

the newly unretired location tag

Throws:

APIException

Since:

1.5

purgeLocationTag

@Authorized(value="Purge Location Tags")
void purgeLocationTag(LocationTag tag)
                                                        throws APIException

Completely remove a location tag from the database (not reversible).

Parameters:

tag - the LocationTag to clean out of the database.

Throws:

APIException

Since:

1.5

getCountOfLocations

@Transactional(readOnly=true)
 @Authorized(value="View Locations")
java.lang.Integer getCountOfLocations(java.lang.String nameFragment,
                                                                                                         java.lang.Boolean includeRetired)

Return the number of all locations that start with the given name fragment, if the name fragment is null or an empty string, then the number of all locations will be returned

Parameters:

nameFragment - is the string used to search for locations

includeRetired - Specifies if retired locations should be counted or ignored

Returns:

the number of all locations starting with the given nameFragment

Since:

1.8

getRootLocations

@Transactional(readOnly=true)
 @Authorized(value="View Locations")
java.util.List<Location> getRootLocations(boolean includeRetired)

Returns all root locations (i.e. those who have no parentLocation), optionally including retired ones.

Parameters:

includeRetired -

Returns:

return all root locations depends on includeRetired

Since:

1.9

getPossibleAddressValues

java.util.List<java.lang.String> getPossibleAddressValues(Address incomplete,
                                                          java.lang.String fieldName)
                                                   throws APIException

Given an Address object, returns all the possible values for the specified AddressField. This method is not implemented in core, but is meant to overridden by implementing modules such as the Address Hierarchy module.

Parameters:

incomplete - the incomplete address

field - the address field we are looking for possible values for

Returns:

a list of possible address values for the specified field

Throws:

APIException

Since:

1.7.2

getAddressTemplate

@Transactional(readOnly=true)
 @Authorized(value="View Locations")
java.lang.String getAddressTemplate()
                                                                                                throws APIException

Returns the xml of default address template.

Returns:

a string value of the default address template. If the GP is empty, the default template is returned

Throws:

APIException

Since:

1.9

See Also:

OpenmrsConstants.GLOBAL_PROPERTY_ADDRESS_TEMPLATE, OpenmrsConstants.DEFAULT_ADDRESS_TEMPLATE

saveAddressTemplate

@Authorized(value="Manage Address Templates")
void saveAddressTemplate(java.lang.String xml)
                                                                throws APIException

Saved default address template to global properties

Parameters:

xml - is a string to be saved as address template

Throws:

APIException

Since:

1.9

getAllLocationAttributeTypes

@Transactional(readOnly=true)
 @Authorized(value="View Location Attribute Types")
java.util.List<LocationAttributeType> getAllLocationAttributeTypes()

Returns:

all LocationAttributeTypes

Since:

1.9

getLocationAttributeType

@Transactional(readOnly=true)
 @Authorized(value="View Location Attribute Types")
LocationAttributeType getLocationAttributeType(java.lang.Integer id)

Parameters:

id -

Returns:

the LocationAttributeType with the given internal id

Since:

1.9

getLocationAttributeTypeByUuid

@Transactional(readOnly=true)
 @Authorized(value="View Location Attribute Types")
LocationAttributeType getLocationAttributeTypeByUuid(java.lang.String uuid)

Parameters:

uuid -

Returns:

the LocationAttributeType with the given uuid

Since:

1.9

saveLocationAttributeType

@Authorized(value="Manage Location Attribute Types")
LocationAttributeType saveLocationAttributeType(LocationAttributeType locationAttributeType)

Creates or updates the given location attribute type in the database

Parameters:

locationAttributeType -

Returns:

the LocationAttributeType created/saved

Since:

1.9

retireLocationAttributeType

@Authorized(value="Manage Location Attribute Types")
LocationAttributeType retireLocationAttributeType(LocationAttributeType locationAttributeType,
                                                                                                       java.lang.String reason)

Retires the given location attribute type in the database

Parameters:

locationAttributeType -

Returns:

the locationAttribute retired

Since:

1.9

unretireLocationAttributeType

@Authorized(value="Manage Location Attribute Types")
LocationAttributeType unretireLocationAttributeType(LocationAttributeType locationAttributeType)

Restores a location attribute type that was previous retired in the database

Parameters:

locationAttributeType -

Returns:

the LocationAttributeType unretired

Since:

1.9

purgeLocationAttributeType

@Authorized(value="Purge Location Attribute Types")
void purgeLocationAttributeType(LocationAttributeType locationAttributeType)

Completely removes a location attribute type from the database

Parameters:

locationAttributeType -

Since:

1.9

getLocationAttributeByUuid

@Transactional(readOnly=true)
 @Authorized(value="View Locations")
LocationAttribute getLocationAttributeByUuid(java.lang.String uuid)

Parameters:

uuid -

Returns:

the LocationAttribute with the given uuid

Since:

1.9