org.openmrs.api.impl

Class LocationServiceImpl

java.lang.Object

org.openmrs.api.impl.BaseOpenmrsService

org.openmrs.api.impl.LocationServiceImpl

All Implemented Interfaces:

LocationService, OpenmrsService

@Transactional
public class LocationServiceImpl
extends BaseOpenmrsService
implements LocationService

Default implementation of the LocationService

This class should not be instantiated alone, get a service class from the Context: Context.getLocationService();

See Also:

Context, LocationService, Location

Constructor Summary

Constructors

Constructor and Description
LocationServiceImpl()

Method Summary

Modifier and Type	Method and Description
String	getAddressTemplate() Returns the xml of default address template.
List<LocationAttributeType>	getAllLocationAttributeTypes()
List<Location>	getAllLocations() Returns all locations, includes retired locations.
List<Location>	getAllLocations(boolean includeRetired) Returns all locations.
List<LocationTag>	getAllLocationTags() Returns all location tags, includes retired location tags.
List<LocationTag>	getAllLocationTags(boolean includeRetired) Returns all location tags.
Integer	getCountOfLocations(String nameFragment, 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(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(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(String uuid)
LocationAttributeType	getLocationAttributeType(Integer id)
LocationAttributeType	getLocationAttributeTypeByName(String name) Retrieves a LocationAttributeType object based on the name provided
LocationAttributeType	getLocationAttributeTypeByUuid(String uuid)
Location	getLocationByUuid(String uuid) Returns a location by uuid
List<Location>	getLocations(String nameFragment) Returns locations that match the beginning of the given string.
List<Location>	getLocations(String nameFragment, Location parent, Map<LocationAttributeType,Object> attributeValues, boolean includeRetired, Integer start, Integer length) Gets the locations matching the specified arguments.
List<Location>	getLocationsByTag(LocationTag tag) Returns locations that contain the given tag.
List<Location>	getLocationsHavingAllTags(List<LocationTag> tags) Returns locations that are mapped to all given tags.
List<Location>	getLocationsHavingAnyTag(List<LocationTag> tags) Returns locations that are mapped to any of the given tags.
LocationTag	getLocationTag(Integer locationTagId) Returns a location tag given that locations primary key locationTagId.
LocationTag	getLocationTagByName(String tag) Returns a location tag given the location's exact name (tag).
LocationTag	getLocationTagByUuid(String uuid) Returns a location tag by uuid
List<LocationTag>	getLocationTags(String search) Returns location tags that match the beginning of the given string.
List<String>	getPossibleAddressValues(Address incomplete, String fieldName) Given an Address object, returns all the possible values for the specified AddressField.
List<Location>	getRootLocations(boolean includeRetired) Returns all root locations (i.e. those who have no parentLocation), optionally including retired ones.
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, String reason) Retires the given location.
LocationAttributeType	retireLocationAttributeType(LocationAttributeType locationAttributeType, String reason) Retires the given location attribute type in the database
LocationTag	retireLocationTag(LocationTag tag, String reason) Retire the given location tag.
void	saveAddressTemplate(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 class org.openmrs.api.impl.BaseOpenmrsService

onShutdown, onStartup

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.openmrs.api.OpenmrsService

onShutdown, onStartup

Constructor Detail

LocationServiceImpl

public LocationServiceImpl()

Method Detail

setLocationDAO

public void setLocationDAO(LocationDAO dao)

Description copied from interface: LocationService

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

Specified by:

setLocationDAO in interface LocationService

See Also:

LocationService.setLocationDAO(org.openmrs.api.db.LocationDAO)

saveLocation

public Location saveLocation(Location location)
                      throws APIException

Description copied from interface: LocationService

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

Specified by:

saveLocation in interface LocationService

Parameters:

location - is the location to be saved to the database Should throw APIException if location has no name Should overwrite transient tag if tag with same name exists Should throw APIException if transient tag is not found Should return saved object Should remove location tag from location Should add location tag to location Should remove child location from location Should cascade save to child location from location Should update location successfully Should create location successfully

Throws:

APIException

See Also:

LocationService.saveLocation(org.openmrs.Location)

getLocation

@Transactional(readOnly=true)
public Location getLocation(Integer locationId)
                                                   throws APIException

Description copied from interface: LocationService

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

Specified by:

getLocation in interface LocationService

Parameters:

locationId - integer primary key of the location to find

Returns:

Location object that has location.locationId = locationId passed in. Should return null when no location match given location id

Throws:

APIException

See Also:

LocationService.getLocation(java.lang.Integer)

getLocation

@Transactional(readOnly=true)
public Location getLocation(String name)
                                                   throws APIException

Description copied from interface: LocationService

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

Specified by:

getLocation in interface LocationService

Parameters:

name - the exact name of the location to match on

Returns:

Location matching the name to Location.name Should return null when no location match given location name

Throws:

APIException

See Also:

LocationService.getLocation(java.lang.String)

getDefaultLocation

@Transactional(readOnly=true)
public Location getDefaultLocation()
                                                          throws APIException

Description copied from interface: LocationService

Returns the default location for this implementation.

Specified by:

getDefaultLocation in interface LocationService

Returns:

The default location for this implementation. Should return default location for the implementation Should return Unknown Location if the global property is something else that doesnot exist

Throws:

APIException

See Also:

LocationService.getDefaultLocation()

getLocationByUuid

@Transactional(readOnly=true)
public Location getLocationByUuid(String uuid)
                                                         throws APIException

Description copied from interface: LocationService

Returns a location by uuid

Specified by:

getLocationByUuid in interface LocationService

Parameters:

uuid - is the uuid of the desired location

Returns:

location with the given uuid Should find object given valid uuid Should return null if no object found with given uuid

Throws:

APIException

See Also:

LocationService.getLocationByUuid(java.lang.String)

getLocationTagByUuid

@Transactional(readOnly=true)
public LocationTag getLocationTagByUuid(String uuid)
                                                               throws APIException

Description copied from interface: LocationService

Returns a location tag by uuid

Specified by:

getLocationTagByUuid in interface LocationService

Parameters:

uuid - is the uuid of the desired location tag

Returns:

location tag with the given uuid Should find object given valid uuid Should return null if no object found with given uuid

Throws:

APIException

See Also:

LocationService.getLocationTagByUuid(java.lang.String)

getAllLocations

@Transactional(readOnly=true)
public List<Location> getAllLocations()
                                                             throws APIException

Description copied from interface: LocationService

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

Specified by:

getAllLocations in interface LocationService

Returns:

locations that are in the database Should return all locations including retired

Throws:

APIException

See Also:

LocationService.getAllLocations()

getAllLocations

@Transactional(readOnly=true)
public List<Location> getAllLocations(boolean includeRetired)
                                                             throws APIException

Description copied from interface: LocationService

Returns all locations.

Specified by:

getAllLocations in interface LocationService

Parameters:

includeRetired - whether or not to include retired locations Should return all locations when includeRetired is true Should return only unretired locations when includeRetires is false

Throws:

APIException

See Also:

LocationService.getAllLocations(boolean)

getLocations

@Transactional(readOnly=true)
public List<Location> getLocations(String nameFragment)
                                                          throws APIException

Description copied from interface: LocationService

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

Specified by:

getLocations in interface LocationService

Parameters:

nameFragment - is the string used to search for locations Should return empty list when no location match the name fragment

Throws:

APIException

See Also:

LocationService.getLocations(java.lang.String)

getLocationsByTag

@Transactional(readOnly=true)
public List<Location> getLocationsByTag(LocationTag tag)
                                                               throws APIException

Description copied from interface: LocationService

Returns locations that contain the given tag.

Specified by:

getLocationsByTag in interface LocationService

Parameters:

tag - LocationTag criterion Should get locations by tag Should return empty list when no locations has the given tag

Throws:

APIException

See Also:

LocationService.getLocationsByTag(LocationTag)

getLocationsHavingAllTags

@Transactional(readOnly=true)
public List<Location> getLocationsHavingAllTags(List<LocationTag> tags)
                                                                       throws APIException

Description copied from interface: LocationService

Returns locations that are mapped to all given tags.

Specified by:

getLocationsHavingAllTags in interface LocationService

Parameters:

tags - Set of LocationTag criteria Should get locations having all tags Should return all unretired locations given an empty tag list

Throws:

APIException

See Also:

LocationService.getLocationsHavingAllTags(List)

getLocationsHavingAnyTag

@Transactional(readOnly=true)
public List<Location> getLocationsHavingAnyTag(List<LocationTag> tags)
                                                                      throws APIException

Description copied from interface: LocationService

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

Specified by:

getLocationsHavingAnyTag in interface LocationService

Parameters:

tags - Set of LocationTag criteria Should get locations having any tag Should return empty list when no location has the given tags Should return empty list when given an empty tag list

Throws:

APIException

See Also:

LocationService.getLocationsHavingAnyTag(List)

retireLocation

public Location retireLocation(Location location,
                               String reason)
                        throws APIException

Description copied from interface: LocationService

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

Specified by:

retireLocation in interface LocationService

Parameters:

location - location to be retired

reason - is the reason why the location is being retired Should retire location successfully

Throws:

APIException

See Also:

LocationService.retireLocation(Location, String)

unretireLocation

public Location unretireLocation(Location location)
                          throws APIException

Description copied from interface: LocationService

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

Specified by:

unretireLocation in interface LocationService

Returns:

the newly unretired location

Throws:

APIException - Should unretire retired location

See Also:

LocationService.unretireLocation(org.openmrs.Location)

purgeLocation

public void purgeLocation(Location location)
                   throws APIException

Description copied from interface: LocationService

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

Specified by:

purgeLocation in interface LocationService

Parameters:

location - the Location to clean out of the database. Should delete location successfully

Throws:

APIException

See Also:

LocationService.purgeLocation(org.openmrs.Location)

saveLocationTag

public LocationTag saveLocationTag(LocationTag tag)
                            throws APIException

Description copied from interface: LocationService

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

Specified by:

saveLocationTag in interface LocationService

Parameters:

tag - is the tag to be saved to the database Should throw APIException if tag has no name Should return saved object Should update location tag successfully Should create location tag successfully Should throw exception if tag name is null

Throws:

APIException

See Also:

LocationService.saveLocationTag(org.openmrs.LocationTag)

getLocationTag

@Transactional(readOnly=true)
public LocationTag getLocationTag(Integer locationTagId)
                                                         throws APIException

Description copied from interface: LocationService

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

Specified by:

getLocationTag in interface LocationService

Parameters:

locationTagId - integer primary key of the location tag to find

Returns:

LocationTag object that has LocationTag.locationTagId = locationTagId passed in. Should return null when no location tag match given id

Throws:

APIException

See Also:

LocationService.getLocationTag(java.lang.Integer)

getLocationTagByName

@Transactional(readOnly=true)
public LocationTag getLocationTagByName(String tag)
                                                               throws APIException

Description copied from interface: LocationService

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

Specified by:

getLocationTagByName in interface LocationService

Parameters:

tag - the exact name of the tag to match on

Returns:

LocationTag matching the name to LocationTag.tag Should get location tag by name Should return null when no location tag match given name

Throws:

APIException

See Also:

LocationService.getLocationTagByName(java.lang.String)

getAllLocationTags

@Transactional(readOnly=true)
public List<LocationTag> getAllLocationTags()
                                                                   throws APIException

Description copied from interface: LocationService

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

Specified by:

getAllLocationTags in interface LocationService

Returns:

location tags that are in the database Should return all location tags including retired

Throws:

APIException

See Also:

LocationService.getAllLocationTags()

getAllLocationTags

@Transactional(readOnly=true)
public List<LocationTag> getAllLocationTags(boolean includeRetired)
                                                                   throws APIException

Description copied from interface: LocationService

Returns all location tags.

Specified by:

getAllLocationTags in interface LocationService

Parameters:

includeRetired - whether or not to include retired location tags Should return all location tags if includeRetired is true Should return only unretired location tags if includeRetired is false

Throws:

APIException

See Also:

LocationService.getAllLocationTags(boolean)

getLocationTags

@Transactional(readOnly=true)
public List<LocationTag> getLocationTags(String search)
                                                                throws APIException

Description copied from interface: LocationService

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

Specified by:

getLocationTags in interface LocationService

Parameters:

search - is the string used to search for tags Should return empty list when no location tag match given search string

Throws:

APIException

See Also:

LocationService.getLocationTags(java.lang.String)

retireLocationTag

public LocationTag retireLocationTag(LocationTag tag,
                                     String reason)
                              throws APIException

Description copied from interface: LocationService

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

Specified by:

retireLocationTag in interface LocationService

Parameters:

tag - location tag to be retired

reason - is the reason why the location tag is being retired Should retire location tag successfully Should retire location tag with given reason

Throws:

APIException

See Also:

LocationService.retireLocationTag(LocationTag, String)

unretireLocationTag

public LocationTag unretireLocationTag(LocationTag tag)
                                throws APIException

Description copied from interface: LocationService

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

Specified by:

unretireLocationTag in interface LocationService

Returns:

the newly unretired location tag

Throws:

APIException - Should unretire retired location tag

See Also:

LocationService.unretireLocationTag(org.openmrs.LocationTag)

purgeLocationTag

public void purgeLocationTag(LocationTag tag)
                      throws APIException

Description copied from interface: LocationService

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

Specified by:

purgeLocationTag in interface LocationService

Parameters:

tag - the LocationTag to clean out of the database. Should delete location tag

Throws:

APIException

See Also:

LocationService.purgeLocationTag(org.openmrs.LocationTag)

getCountOfLocations

@Transactional(readOnly=true)
public Integer getCountOfLocations(String nameFragment,
                                                                 Boolean includeRetired)

Description copied from interface: LocationService

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

Specified by:

getCountOfLocations in interface LocationService

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

See Also:

LocationService.getCountOfLocations(String, Boolean)

getLocations

public List<Location> getLocations(String nameFragment,
                                   Location parent,
                                   Map<LocationAttributeType,Object> attributeValues,
                                   boolean includeRetired,
                                   Integer start,
                                   Integer length)

Description copied from interface: LocationService

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.

Specified by:

getLocations in interface LocationService

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 Should return empty list when no location has matching attribute values Should get locations having all matching attribute values

See Also:

LocationService.getLocations(String, org.openmrs.Location, java.util.Map, boolean, Integer, Integer)

getRootLocations

@Transactional(readOnly=true)
public List<Location> getRootLocations(boolean includeRetired)
                                                              throws APIException

Description copied from interface: LocationService

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

Specified by:

getRootLocations in interface LocationService

Returns:

return all root locations depends on includeRetired Should return all root locations when includeRetired is true Should return only unretired root locations when includeRetired is false

Throws:

APIException

See Also:

LocationService.getRootLocations(boolean)

getPossibleAddressValues

public List<String> getPossibleAddressValues(Address incomplete,
                                             String fieldName)
                                      throws APIException

Description copied from interface: LocationService

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.

Specified by:

getPossibleAddressValues in interface LocationService

Parameters:

incomplete - the incomplete address

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

Returns:

a list of possible address values for the specified field Should return empty list if no possible address matches Should return null if method not implemented Should return null by default

Throws:

APIException

See Also:

LocationService.getPossibleAddressValues(Address, String)

getAllLocationAttributeTypes

@Transactional(readOnly=true)
public List<LocationAttributeType> getAllLocationAttributeTypes()

Specified by:

getAllLocationAttributeTypes in interface LocationService

Returns:

all LocationAttributeTypes

See Also:

LocationService.getAllLocationAttributeTypes()

getLocationAttributeType

@Transactional(readOnly=true)
public LocationAttributeType getLocationAttributeType(Integer id)

Specified by:

getLocationAttributeType in interface LocationService

Returns:

the LocationAttributeType with the given internal id

See Also:

LocationService.getLocationAttributeType(java.lang.Integer)

getLocationAttributeTypeByUuid

@Transactional(readOnly=true)
public LocationAttributeType getLocationAttributeTypeByUuid(String uuid)

Specified by:

getLocationAttributeTypeByUuid in interface LocationService

Returns:

the LocationAttributeType with the given uuid

See Also:

LocationService.getLocationAttributeTypeByUuid(java.lang.String)

saveLocationAttributeType

public LocationAttributeType saveLocationAttributeType(LocationAttributeType locationAttributeType)

Description copied from interface: LocationService

Creates or updates the given location attribute type in the database

Specified by:

saveLocationAttributeType in interface LocationService

Returns:

the LocationAttributeType created/saved

See Also:

LocationService.saveLocationAttributeType(org.openmrs.LocationAttributeType)

retireLocationAttributeType

public LocationAttributeType retireLocationAttributeType(LocationAttributeType locationAttributeType,
                                                         String reason)

Description copied from interface: LocationService

Retires the given location attribute type in the database

Specified by:

retireLocationAttributeType in interface LocationService

Returns:

the locationAttribute retired

See Also:

LocationService.retireLocationAttributeType(org.openmrs.LocationAttributeType, java.lang.String)

unretireLocationAttributeType

public LocationAttributeType unretireLocationAttributeType(LocationAttributeType locationAttributeType)

Description copied from interface: LocationService

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

Specified by:

unretireLocationAttributeType in interface LocationService

Returns:

the LocationAttributeType unretired

See Also:

LocationService.unretireLocationAttributeType(org.openmrs.LocationAttributeType)

purgeLocationAttributeType

public void purgeLocationAttributeType(LocationAttributeType locationAttributeType)

Description copied from interface: LocationService

Completely removes a location attribute type from the database

Specified by:

purgeLocationAttributeType in interface LocationService

See Also:

LocationService.purgeLocationAttributeType(org.openmrs.LocationAttributeType)

getLocationAttributeByUuid

@Transactional(readOnly=true)
public LocationAttribute getLocationAttributeByUuid(String uuid)

Specified by:

getLocationAttributeByUuid in interface LocationService

Returns:

the LocationAttribute with the given uuid

See Also:

LocationService.getLocationAttributeByUuid(java.lang.String)

getAddressTemplate

@Transactional(readOnly=true)
public String getAddressTemplate()
                                                        throws APIException

Description copied from interface: LocationService

Returns the xml of default address template.

Specified by:

getAddressTemplate in interface LocationService

Returns:

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

Throws:

APIException

See Also:

LocationService.getAddressTemplate()

saveAddressTemplate

public void saveAddressTemplate(String xml)
                         throws APIException

Description copied from interface: LocationService

Saved default address template to global properties

Specified by:

saveAddressTemplate in interface LocationService

Parameters:

xml - is a string to be saved as address template Should throw APIException if the string is empty Should update default address template successfully Should create default address template successfully

Throws:

APIException

See Also:

LocationService.saveAddressTemplate(String)

getLocationAttributeTypeByName

@Transactional(readOnly=true)
public LocationAttributeType getLocationAttributeTypeByName(String name)

Description copied from interface: LocationService

Retrieves a LocationAttributeType object based on the name provided

Specified by:

getLocationAttributeTypeByName in interface LocationService

Returns:

the LocationAttributeType with the specified name

See Also:

LocationService.getLocationAttributeTypeByName(java.lang.String)