Package org.odpi.openmetadata.accessservices.digitalarchitecture.api

Interface ManageLocations

public interface ManageLocations

ManageLocations defines the client side interface for the Digital Architecture OMAS that is relevant for managing definitions of locations.

Method Summary

Modifier and Type	Method	Description
void	clearAdjacentLocation(String userId, String locationOneGUID, String locationTwoGUID)	Remove a peer-to-peer relationship between two locations.
void	clearLocationAsDigital(String userId, String locationGUID)	Remove the digital/cyber location designation from the location.
void	clearLocationAsFixedPhysical(String userId, String locationGUID)	Remove the fixed physical location designation from the location.
void	clearLocationAsSecure(String userId, String locationGUID)	Remove the secure location designation from the location.
void	clearNestedLocation(String userId, String parentLocationGUID, String childLocationGUID)	Remove a parent-child relationship between two locations.
String	createLocation(String userId, LocationProperties locationProperties)	Create a new metadata element to represent a location.
String	createLocationFromTemplate(String userId, 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.
LocationElement	getLocationByGUID(String userId, String locationGUID)	Retrieve the location metadata element with the supplied unique identifier.
List<LocationElement>	getLocationsByName(String userId, String name, int startFrom, int pageSize)	Retrieve the list of location metadata elements with a matching qualified or display name.
void	removeLocation(String userId, String locationGUID)	Remove the metadata element representing a location.
void	setLocationAsDigital(String userId, String locationGUID, String networkAddress)	Classify the location to indicate that it represents a digital/cyber location.
void	setLocationAsFixedPhysical(String userId, String locationGUID, String coordinates, String mapProjection, String postalAddress, String timeZone)	Classify the location to indicate that it represents a fixed physical location.
void	setLocationAsSecure(String userId, String locationGUID, String description, String level)	Classify the location to indicate that it represents a secure location.
void	setupAdjacentLocation(String userId, String locationOneGUID, String locationTwoGUID)	Create a peer-to-peer relationship between two locations.
void	setupNestedLocation(String userId, String parentLocationGUID, String childLocationGUID)	Create a parent-child relationship between two locations.
void	updateLocation(String userId, boolean isMergeUpdate, String locationGUID, LocationProperties locationProperties)	Update the metadata element representing a location.

Method Detail

createLocation

String createLocation(String userId,
                      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

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 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

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,
                    boolean isMergeUpdate,
                    String locationGUID,
                    LocationProperties locationProperties)
             throws InvalidParameterException,
                    UserNotAuthorizedException,
                    PropertyServerException

Update the metadata element representing a location.

Parameters:

userId - calling user

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

locationGUID - unique identifier of the metadata element to update

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 locationGUID,
                                String coordinates,
                                String mapProjection,
                                String postalAddress,
                                String timeZone)
                         throws InvalidParameterException,
                                UserNotAuthorizedException,
                                PropertyServerException

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

Parameters:

userId - calling user

locationGUID - unique identifier of the metadata element to classify

coordinates - position of the location

mapProjection - map projection used to define the coordinates

postalAddress - postal address of the location (if appropriate)

timeZone - time zone for 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 locationGUID)
                           throws InvalidParameterException,
                                  UserNotAuthorizedException,
                                  PropertyServerException

Remove the fixed physical location designation from the location.

Parameters:

userId - calling user

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 locationGUID,
                         String description,
                         String level)
                  throws InvalidParameterException,
                         UserNotAuthorizedException,
                         PropertyServerException

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

Parameters:

userId - calling user

locationGUID - unique identifier of the metadata element to classify

description - description of security at the site

level - level of security

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 locationGUID)
                    throws InvalidParameterException,
                           UserNotAuthorizedException,
                           PropertyServerException

Remove the secure location designation from the location.

Parameters:

userId - calling user

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 networkAddress)
                   throws InvalidParameterException,
                          UserNotAuthorizedException,
                          PropertyServerException

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

Parameters:

userId - calling user

locationGUID - unique identifier of the metadata element to classify

networkAddress - 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)

clearLocationAsDigital

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

Remove the digital/cyber location designation from the location.

Parameters:

userId - calling user

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)

removeLocation

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

Remove the metadata element representing a location.

Parameters:

userId - calling user

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)

setupNestedLocation

void setupNestedLocation(String userId,
                         String parentLocationGUID,
                         String childLocationGUID)
                  throws InvalidParameterException,
                         UserNotAuthorizedException,
                         PropertyServerException

Create a parent-child relationship between two locations.

Parameters:

userId - calling user

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)

clearNestedLocation

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

Remove a parent-child relationship between two locations.

Parameters:

userId - calling user

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 locationOneGUID,
                           String locationTwoGUID)
                    throws InvalidParameterException,
                           UserNotAuthorizedException,
                           PropertyServerException

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

Parameters:

userId - calling user

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)

clearAdjacentLocation

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

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

Parameters:

userId - calling user

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)

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 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)

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)