Package org.odpi.openmetadata.accessservices.communityprofile.api

Interface LocationManagementInterface

public interface LocationManagementInterface

LocationManagementInterface defines the client side interface for the Community Profile OMAS that is relevant for managing definitions of locations.

Method Summary

Modifier and Type	Method	Description
void	clearAdjacentLocation(String userId, String externalSourceGUID, String externalSourceName, String locationOneGUID, String locationTwoGUID)	Remove a peer-to-peer relationship between two locations.
void	clearAssetLocation(String userId, String externalSourceGUID, String externalSourceName, String assetGUID, String locationGUID)	Remove an asset location relationship between an asset and a location.
void	clearLocationAsDigital(String userId, String externalSourceGUID, String externalSourceName, String locationGUID)	Remove the digital/cyber location designation from the location.
void	clearLocationAsFixedPhysical(String userId, String externalSourceGUID, String externalSourceName, String locationGUID)	Remove the fixed physical location designation from the location.
void	clearLocationAsSecure(String userId, String externalSourceGUID, String externalSourceName, String locationGUID)	Remove the secure location designation from the location.
void	clearNestedLocation(String userId, String externalSourceGUID, String externalSourceName, String parentLocationGUID, String childLocationGUID)	Remove a parent-child relationship between two locations.
void	clearProfileLocation(String userId, String externalSourceGUID, String externalSourceName, String actorProfileGUID, String locationGUID)	Remove a profile location relationship between an actor profile and a location.
String	createLocation(String userId, String externalSourceGUID, String externalSourceName, LocationProperties locationProperties)	Create a new metadata element to represent a location.
String	createLocationFromTemplate(String userId, String externalSourceGUID, String externalSourceName, String templateGUID, TemplateProperties templateProperties)	Create a new metadata element to represent a location using an existing metadata element as a template.
List<LocationElement>	findLocations(String userId, String searchString, int startFrom, int pageSize)	Retrieve the list of location metadata elements that contain the search string.
List<LocationElement>	getAdjacentLocations(String userId, String locationGUID, int startFrom, int pageSize)	Retrieve the list of adjacent location metadata elements linked to locationGUID.
List<LocationElement>	getGroupingLocations(String userId, String locationGUID, int startFrom, int pageSize)	Retrieve the list of location metadata elements that has the location identifier with locationGUID nested inside it.
List<LocationElement>	getKnownLocationsForAsset(String userId, String assetGUID, int startFrom, int pageSize)	Retrieve the list of location metadata elements linked to assetGUID.
LocationElement	getLocationByGUID(String userId, String locationGUID)	Retrieve the location metadata element with the supplied unique identifier.
List<LocationElement>	getLocations(String userId, int startFrom, int pageSize)	Retrieve the list of location metadata elements.
List<LocationElement>	getLocationsByName(String userId, String name, int startFrom, int pageSize)	Retrieve the list of location metadata elements with a matching qualified name, identifier or display name.
List<LocationElement>	getLocationsByProfile(String userId, String actorProfileGUID, int startFrom, int pageSize)	Retrieve the list of location metadata elements linked to actorProfileGUID.
List<LocationElement>	getNestedLocations(String userId, String locationGUID, int startFrom, int pageSize)	Retrieve the list of nested location metadata elements linked to locationGUID.
void	removeLocation(String userId, String externalSourceGUID, String externalSourceName, String locationGUID)	Remove the metadata element representing a location.
void	setLocationAsDigital(String userId, String locationGUID, String externalSourceGUID, String externalSourceName, DigitalLocationProperties properties)	Classify the location to indicate that it represents a digital/cyber location.
void	setLocationAsFixedPhysical(String userId, String externalSourceGUID, String externalSourceName, String locationGUID, FixedLocationProperties properties)	Classify the location to indicate that it represents a fixed physical location.
void	setLocationAsSecure(String userId, String externalSourceGUID, String externalSourceName, String locationGUID, SecureLocationProperties properties)	Classify the location to indicate that it represents a secure location.
void	setupAdjacentLocation(String userId, String externalSourceGUID, String externalSourceName, String locationOneGUID, String locationTwoGUID, AdjacentLocationProperties properties)	Create a peer-to-peer relationship between two locations.
void	setupAssetLocation(String userId, String externalSourceGUID, String externalSourceName, String assetGUID, String locationGUID, AssetLocationProperties properties)	Create an asset location relationship between an asset and a location.
void	setupNestedLocation(String userId, String externalSourceGUID, String externalSourceName, String parentLocationGUID, String childLocationGUID, NestedLocationProperties properties)	Create a parent-child relationship between two locations.
void	setupProfileLocation(String userId, String externalSourceGUID, String externalSourceName, String actorProfileGUID, String locationGUID, ProfileLocationProperties properties)	Create a profile location relationship between an actor profile and a location.
void	updateLocation(String userId, String externalSourceGUID, String externalSourceName, String locationGUID, boolean isMergeUpdate, LocationProperties locationProperties)	Update the metadata element representing a location.

Method Detail

createLocation

String createLocation(String userId,
                      String externalSourceGUID,
                      String externalSourceName,
                      LocationProperties locationProperties)
               throws InvalidParameterException,
                      UserNotAuthorizedException,
                      PropertyServerException

Create a new metadata element to represent a location. Classifications can be added later to define the type of location.

Parameters:

userId - calling user

externalSourceGUID - unique identifier of software capability representing the caller

externalSourceName - unique name of software capability representing the caller

locationProperties - properties to store

Returns:

unique identifier of the new metadata element

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

createLocationFromTemplate

String createLocationFromTemplate(String userId,
                                  String externalSourceGUID,
                                  String externalSourceName,
                                  String templateGUID,
                                  TemplateProperties templateProperties)
                           throws InvalidParameterException,
                                  UserNotAuthorizedException,
                                  PropertyServerException

Create a new metadata element to represent a location using an existing metadata element as a template. The template defines additional classifications and relationships that should be added to the new location.

Parameters:

userId - calling user

externalSourceGUID - unique identifier of software capability representing the caller

externalSourceName - unique name of software capability representing the caller

templateGUID - unique identifier of the metadata element to copy

templateProperties - properties that override the template

Returns:

unique identifier of the new metadata element

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

updateLocation

void updateLocation(String userId,
                    String externalSourceGUID,
                    String externalSourceName,
                    String locationGUID,
                    boolean isMergeUpdate,
                    LocationProperties locationProperties)
             throws InvalidParameterException,
                    UserNotAuthorizedException,
                    PropertyServerException

Update the metadata element representing a location.

Parameters:

userId - calling user

externalSourceGUID - unique identifier of software capability representing the caller

externalSourceName - unique name of software capability representing the caller

locationGUID - unique identifier of the metadata element to update

isMergeUpdate - should the new properties be merged with existing properties (true) or completely replace them (false)?

locationProperties - new properties for this element

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

setLocationAsFixedPhysical

void setLocationAsFixedPhysical(String userId,
                                String externalSourceGUID,
                                String externalSourceName,
                                String locationGUID,
                                FixedLocationProperties properties)
                         throws InvalidParameterException,
                                UserNotAuthorizedException,
                                PropertyServerException

Classify the location to indicate that it represents a fixed physical location.

Parameters:

userId - calling user

externalSourceGUID - unique identifier of software capability representing the caller

externalSourceName - unique name of software capability representing the caller

locationGUID - unique identifier of the metadata element to classify

properties - time zone and position of the location

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

clearLocationAsFixedPhysical

void clearLocationAsFixedPhysical(String userId,
                                  String externalSourceGUID,
                                  String externalSourceName,
                                  String locationGUID)
                           throws InvalidParameterException,
                                  UserNotAuthorizedException,
                                  PropertyServerException

Remove the fixed physical location designation from the location.

Parameters:

userId - calling user

externalSourceGUID - unique identifier of software capability representing the caller

externalSourceName - unique name of software capability representing the caller

locationGUID - unique identifier of the metadata element to unclassify

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

setLocationAsSecure

void setLocationAsSecure(String userId,
                         String externalSourceGUID,
                         String externalSourceName,
                         String locationGUID,
                         SecureLocationProperties properties)
                  throws InvalidParameterException,
                         UserNotAuthorizedException,
                         PropertyServerException

Classify the location to indicate that it represents a secure location.

Parameters:

userId - calling user

externalSourceGUID - unique identifier of software capability representing the caller

externalSourceName - unique name of software capability representing the caller

locationGUID - unique identifier of the metadata element to classify

properties - properties of security at the site

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

clearLocationAsSecure

void clearLocationAsSecure(String userId,
                           String externalSourceGUID,
                           String externalSourceName,
                           String locationGUID)
                    throws InvalidParameterException,
                           UserNotAuthorizedException,
                           PropertyServerException

Remove the secure location designation from the location.

Parameters:

userId - calling user

externalSourceGUID - unique identifier of software capability representing the caller

externalSourceName - unique name of software capability representing the caller

locationGUID - unique identifier of the metadata element to unclassify

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

setLocationAsDigital

void setLocationAsDigital(String userId,
                          String locationGUID,
                          String externalSourceGUID,
                          String externalSourceName,
                          DigitalLocationProperties properties)
                   throws InvalidParameterException,
                          UserNotAuthorizedException,
                          PropertyServerException

Classify the location to indicate that it represents a digital/cyber location.

Parameters:

userId - calling user

externalSourceGUID - unique identifier of software capability representing the caller

externalSourceName - unique name of software capability representing the caller

locationGUID - unique identifier of the metadata element to classify

properties - address of the location

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

clearLocationAsDigital

void clearLocationAsDigital(String userId,
                            String externalSourceGUID,
                            String externalSourceName,
                            String locationGUID)
                     throws InvalidParameterException,
                            UserNotAuthorizedException,
                            PropertyServerException

Remove the digital/cyber location designation from the location.

Parameters:

userId - calling user

externalSourceGUID - unique identifier of software capability representing the caller

externalSourceName - unique name of software capability representing the caller

locationGUID - unique identifier of the metadata element to unclassify

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

setupNestedLocation

void setupNestedLocation(String userId,
                         String externalSourceGUID,
                         String externalSourceName,
                         String parentLocationGUID,
                         String childLocationGUID,
                         NestedLocationProperties properties)
                  throws InvalidParameterException,
                         UserNotAuthorizedException,
                         PropertyServerException

Create a parent-child relationship between two locations.

Parameters:

userId - calling user

externalSourceGUID - unique identifier of software capability representing the caller

externalSourceName - unique name of software capability representing the caller

parentLocationGUID - unique identifier of the location that is the broader location

childLocationGUID - unique identifier of the location that is the smaller, nested location

properties - relationship properties

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

clearNestedLocation

void clearNestedLocation(String userId,
                         String externalSourceGUID,
                         String externalSourceName,
                         String parentLocationGUID,
                         String childLocationGUID)
                  throws InvalidParameterException,
                         UserNotAuthorizedException,
                         PropertyServerException

Remove a parent-child relationship between two locations.

Parameters:

userId - calling user

externalSourceGUID - unique identifier of software capability representing the caller

externalSourceName - unique name of software capability representing the caller

parentLocationGUID - unique identifier of the location that is the broader location

childLocationGUID - unique identifier of the location that is the smaller, nested location

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

setupAdjacentLocation

void setupAdjacentLocation(String userId,
                           String externalSourceGUID,
                           String externalSourceName,
                           String locationOneGUID,
                           String locationTwoGUID,
                           AdjacentLocationProperties properties)
                    throws InvalidParameterException,
                           UserNotAuthorizedException,
                           PropertyServerException

Create a peer-to-peer relationship between two locations.

Parameters:

userId - calling user

externalSourceGUID - unique identifier of software capability representing the caller

externalSourceName - unique name of software capability representing the caller

locationOneGUID - unique identifier of the first location

locationTwoGUID - unique identifier of the second location

properties - relationship properties

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

clearAdjacentLocation

void clearAdjacentLocation(String userId,
                           String externalSourceGUID,
                           String externalSourceName,
                           String locationOneGUID,
                           String locationTwoGUID)
                    throws InvalidParameterException,
                           UserNotAuthorizedException,
                           PropertyServerException

Remove a peer-to-peer relationship between two locations.

Parameters:

userId - calling user

externalSourceGUID - unique identifier of software capability representing the caller

externalSourceName - unique name of software capability representing the caller

locationOneGUID - unique identifier of the first location

locationTwoGUID - unique identifier of the second location

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

setupProfileLocation

void setupProfileLocation(String userId,
                          String externalSourceGUID,
                          String externalSourceName,
                          String actorProfileGUID,
                          String locationGUID,
                          ProfileLocationProperties properties)
                   throws InvalidParameterException,
                          UserNotAuthorizedException,
                          PropertyServerException

Create a profile location relationship between an actor profile and a location.

Parameters:

userId - calling user

externalSourceGUID - unique identifier of software capability representing the caller

externalSourceName - unique name of software capability representing the caller

actorProfileGUID - unique identifier of the actor profile

locationGUID - unique identifier of the location

properties - type of association with the location

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

clearProfileLocation

void clearProfileLocation(String userId,
                          String externalSourceGUID,
                          String externalSourceName,
                          String actorProfileGUID,
                          String locationGUID)
                   throws InvalidParameterException,
                          UserNotAuthorizedException,
                          PropertyServerException

Remove a profile location relationship between an actor profile and a location.

Parameters:

userId - calling user

externalSourceGUID - unique identifier of software capability representing the caller

externalSourceName - unique name of software capability representing the caller

actorProfileGUID - unique identifier of the actor profile

locationGUID - unique identifier of the location

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

setupAssetLocation

void setupAssetLocation(String userId,
                        String externalSourceGUID,
                        String externalSourceName,
                        String assetGUID,
                        String locationGUID,
                        AssetLocationProperties properties)
                 throws InvalidParameterException,
                        UserNotAuthorizedException,
                        PropertyServerException

Create an asset location relationship between an asset and a location.

Parameters:

userId - calling user

externalSourceGUID - unique identifier of software capability representing the caller

externalSourceName - unique name of software capability representing the caller

assetGUID - unique identifier of the actor profile

locationGUID - unique identifier of the location

properties - type of association with the location

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

clearAssetLocation

void clearAssetLocation(String userId,
                        String externalSourceGUID,
                        String externalSourceName,
                        String assetGUID,
                        String locationGUID)
                 throws InvalidParameterException,
                        UserNotAuthorizedException,
                        PropertyServerException

Remove an asset location relationship between an asset and a location.

Parameters:

userId - calling user

externalSourceGUID - unique identifier of software capability representing the caller

externalSourceName - unique name of software capability representing the caller

assetGUID - unique identifier of the asset

locationGUID - unique identifier of the location

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

removeLocation

void removeLocation(String userId,
                    String externalSourceGUID,
                    String externalSourceName,
                    String locationGUID)
             throws InvalidParameterException,
                    UserNotAuthorizedException,
                    PropertyServerException

Remove the metadata element representing a location.

Parameters:

userId - calling user

externalSourceGUID - unique identifier of software capability representing the caller

externalSourceName - unique name of software capability representing the caller

locationGUID - unique identifier of the metadata element to remove

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

findLocations

List<LocationElement> findLocations(String userId,
                                    String searchString,
                                    int startFrom,
                                    int pageSize)
                             throws InvalidParameterException,
                                    UserNotAuthorizedException,
                                    PropertyServerException

Retrieve the list of location metadata elements that contain the search string. The search string is treated as a regular expression.

Parameters:

userId - calling user

searchString - string to find in the properties

startFrom - paging start point

pageSize - maximum results that can be returned

Returns:

list of matching metadata elements

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

getLocationsByName

List<LocationElement> getLocationsByName(String userId,
                                         String name,
                                         int startFrom,
                                         int pageSize)
                                  throws InvalidParameterException,
                                         UserNotAuthorizedException,
                                         PropertyServerException

Retrieve the list of location metadata elements with a matching qualified name, identifier or display name. There are no wildcards supported on this request.

Parameters:

userId - calling user

name - name to search for

startFrom - paging start point

pageSize - maximum results that can be returned

Returns:

list of matching metadata elements

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

getAdjacentLocations

List<LocationElement> getAdjacentLocations(String userId,
                                           String locationGUID,
                                           int startFrom,
                                           int pageSize)
                                    throws InvalidParameterException,
                                           UserNotAuthorizedException,
                                           PropertyServerException

Retrieve the list of adjacent location metadata elements linked to locationGUID.

Parameters:

userId - calling user

locationGUID - locationGUID to search for

startFrom - paging start point

pageSize - maximum results that can be returned

Returns:

list of matching metadata elements

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

getNestedLocations

List<LocationElement> getNestedLocations(String userId,
                                         String locationGUID,
                                         int startFrom,
                                         int pageSize)
                                  throws InvalidParameterException,
                                         UserNotAuthorizedException,
                                         PropertyServerException

Retrieve the list of nested location metadata elements linked to locationGUID.

Parameters:

userId - calling user

locationGUID - locationGUID to search for

startFrom - paging start point

pageSize - maximum results that can be returned

Returns:

list of matching metadata elements

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

getGroupingLocations

List<LocationElement> getGroupingLocations(String userId,
                                           String locationGUID,
                                           int startFrom,
                                           int pageSize)
                                    throws InvalidParameterException,
                                           UserNotAuthorizedException,
                                           PropertyServerException

Retrieve the list of location metadata elements that has the location identifier with locationGUID nested inside it.

Parameters:

userId - calling user

locationGUID - locationGUID to search for

startFrom - paging start point

pageSize - maximum results that can be returned

Returns:

list of matching metadata elements

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

getLocationsByProfile

List<LocationElement> getLocationsByProfile(String userId,
                                            String actorProfileGUID,
                                            int startFrom,
                                            int pageSize)
                                     throws InvalidParameterException,
                                            UserNotAuthorizedException,
                                            PropertyServerException

Retrieve the list of location metadata elements linked to actorProfileGUID.

Parameters:

userId - calling user

actorProfileGUID - actorProfileGUID to search for

startFrom - paging start point

pageSize - maximum results that can be returned

Returns:

list of matching metadata elements

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

getKnownLocationsForAsset

List<LocationElement> getKnownLocationsForAsset(String userId,
                                                String assetGUID,
                                                int startFrom,
                                                int pageSize)
                                         throws InvalidParameterException,
                                                UserNotAuthorizedException,
                                                PropertyServerException

Retrieve the list of location metadata elements linked to assetGUID.

Parameters:

userId - calling user

assetGUID - assetGUID to search for

startFrom - paging start point

pageSize - maximum results that can be returned

Returns:

list of matching metadata elements

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

getLocations

List<LocationElement> getLocations(String userId,
                                   int startFrom,
                                   int pageSize)
                            throws InvalidParameterException,
                                   UserNotAuthorizedException,
                                   PropertyServerException

Retrieve the list of location metadata elements.

Parameters:

userId - calling user

startFrom - paging start point

pageSize - maximum results that can be returned

Returns:

list of matching metadata elements

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

getLocationByGUID

LocationElement getLocationByGUID(String userId,
                                  String locationGUID)
                           throws InvalidParameterException,
                                  UserNotAuthorizedException,
                                  PropertyServerException

Retrieve the location metadata element with the supplied unique identifier.

Parameters:

userId - calling user

locationGUID - unique identifier of the requested metadata element

Returns:

matching metadata element

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)