org.odpi.openmetadata.accessservices.digitalarchitecture.api.ManageLocations Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of digital-architecture-api Show documentation
Show all versions of digital-architecture-api Show documentation
API classes for the Digital Architecture Open Metadata Access Service (OMAS).
The newest version!
/* SPDX-License-Identifier: Apache-2.0 */
/* Copyright Contributors to the ODPi Egeria project. */
package org.odpi.openmetadata.accessservices.digitalarchitecture.api;
import org.odpi.openmetadata.accessservices.digitalarchitecture.metadataelements.LocationElement;
import org.odpi.openmetadata.accessservices.digitalarchitecture.properties.LocationProperties;
import org.odpi.openmetadata.accessservices.digitalarchitecture.properties.TemplateProperties;
import org.odpi.openmetadata.frameworks.connectors.ffdc.InvalidParameterException;
import org.odpi.openmetadata.frameworks.connectors.ffdc.PropertyServerException;
import org.odpi.openmetadata.frameworks.connectors.ffdc.UserNotAuthorizedException;
import java.util.List;
/**
* ManageLocations defines the client side interface for the Digital Architecture OMAS that is relevant for managing definitions of locations.
*/
public interface ManageLocations
{
/**
* Create a new metadata element to represent a location. Classifications can be added later to define the
* type of location.
*
* @param userId calling user
* @param locationProperties properties to store
*
* @return unique identifier of the new metadata element
*
* @throws InvalidParameterException one of the parameters is invalid
* @throws UserNotAuthorizedException the user is not authorized to issue this request
* @throws PropertyServerException there is a problem reported in the open metadata server(s)
*/
String createLocation(String userId,
LocationProperties locationProperties) 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.
*
* @param userId calling user
* @param templateGUID unique identifier of the metadata element to copy
* @param templateProperties properties that override the template
*
* @return unique identifier of the new metadata element
*
* @throws InvalidParameterException one of the parameters is invalid
* @throws UserNotAuthorizedException the user is not authorized to issue this request
* @throws PropertyServerException there is a problem reported in the open metadata server(s)
*/
String createLocationFromTemplate(String userId,
String templateGUID,
TemplateProperties templateProperties) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Update the metadata element representing a location.
*
* @param userId calling user
* @param isMergeUpdate should the new properties be merged with existing properties (true) or completely replace them (false)?
* @param locationGUID unique identifier of the metadata element to update
* @param locationProperties new properties for this element
*
* @throws InvalidParameterException one of the parameters is invalid
* @throws UserNotAuthorizedException the user is not authorized to issue this request
* @throws PropertyServerException there is a problem reported in the open metadata server(s)
*/
void updateLocation(String userId,
boolean isMergeUpdate,
String locationGUID,
LocationProperties locationProperties) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Classify the location to indicate that it represents a fixed physical location.
*
* @param userId calling user
* @param locationGUID unique identifier of the metadata element to classify
* @param coordinates position of the location
* @param mapProjection map projection used to define the coordinates
* @param postalAddress postal address of the location (if appropriate)
* @param timeZone time zone for the location
*
* @throws InvalidParameterException one of the parameters is invalid
* @throws UserNotAuthorizedException the user is not authorized to issue this request
* @throws PropertyServerException there is a problem reported in the open metadata server(s)
*/
void setLocationAsFixedPhysical(String userId,
String locationGUID,
String coordinates,
String mapProjection,
String postalAddress,
String timeZone) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Remove the fixed physical location designation from the location.
*
* @param userId calling user
* @param locationGUID unique identifier of the metadata element to unclassify
*
* @throws InvalidParameterException one of the parameters is invalid
* @throws UserNotAuthorizedException the user is not authorized to issue this request
* @throws PropertyServerException there is a problem reported in the open metadata server(s)
*/
void clearLocationAsFixedPhysical(String userId,
String locationGUID) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Classify the location to indicate that it represents a secure location.
*
* @param userId calling user
* @param locationGUID unique identifier of the metadata element to classify
* @param description description of security at the site
* @param level level of security
*
* @throws InvalidParameterException one of the parameters is invalid
* @throws UserNotAuthorizedException the user is not authorized to issue this request
* @throws PropertyServerException there is a problem reported in the open metadata server(s)
*/
void setLocationAsSecure(String userId,
String locationGUID,
String description,
String level) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Remove the secure location designation from the location.
*
* @param userId calling user
* @param locationGUID unique identifier of the metadata element to unclassify
*
* @throws InvalidParameterException one of the parameters is invalid
* @throws UserNotAuthorizedException the user is not authorized to issue this request
* @throws PropertyServerException there is a problem reported in the open metadata server(s)
*/
void clearLocationAsSecure(String userId,
String locationGUID) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Classify the location to indicate that it represents a digital/cyber location.
*
* @param userId calling user
* @param locationGUID unique identifier of the metadata element to classify
* @param networkAddress position of the location
*
* @throws InvalidParameterException one of the parameters is invalid
* @throws UserNotAuthorizedException the user is not authorized to issue this request
* @throws PropertyServerException there is a problem reported in the open metadata server(s)
*/
void setLocationAsDigital(String userId,
String locationGUID,
String networkAddress) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Remove the digital/cyber location designation from the location.
*
* @param userId calling user
* @param locationGUID unique identifier of the metadata element to unclassify
*
* @throws InvalidParameterException one of the parameters is invalid
* @throws UserNotAuthorizedException the user is not authorized to issue this request
* @throws PropertyServerException there is a problem reported in the open metadata server(s)
*/
void clearLocationAsDigital(String userId,
String locationGUID) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Remove the metadata element representing a location.
*
* @param userId calling user
* @param locationGUID unique identifier of the metadata element to remove
*
* @throws InvalidParameterException one of the parameters is invalid
* @throws UserNotAuthorizedException the user is not authorized to issue this request
* @throws PropertyServerException there is a problem reported in the open metadata server(s)
*/
void removeLocation(String userId,
String locationGUID) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Create a parent-child relationship between two locations.
*
* @param userId calling user
* @param parentLocationGUID unique identifier of the location that is the broader location
* @param childLocationGUID unique identifier of the location that is the smaller, nested location
*
* @throws InvalidParameterException one of the parameters is invalid
* @throws UserNotAuthorizedException the user is not authorized to issue this request
* @throws PropertyServerException there is a problem reported in the open metadata server(s)
*/
void setupNestedLocation(String userId,
String parentLocationGUID,
String childLocationGUID) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Remove a parent-child relationship between two locations.
*
* @param userId calling user
* @param parentLocationGUID unique identifier of the location that is the broader location
* @param childLocationGUID unique identifier of the location that is the smaller, nested location
*
* @throws InvalidParameterException one of the parameters is invalid
* @throws UserNotAuthorizedException the user is not authorized to issue this request
* @throws PropertyServerException there is a problem reported in the open metadata server(s)
*/
void clearNestedLocation(String userId,
String parentLocationGUID,
String childLocationGUID) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Create a peer-to-peer relationship between two locations.
*
* @param userId calling user
* @param locationOneGUID unique identifier of the first location
* @param locationTwoGUID unique identifier of the second location
*
* @throws InvalidParameterException one of the parameters is invalid
* @throws UserNotAuthorizedException the user is not authorized to issue this request
* @throws PropertyServerException there is a problem reported in the open metadata server(s)
*/
void setupAdjacentLocation(String userId,
String locationOneGUID,
String locationTwoGUID) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Remove a peer-to-peer relationship between two locations.
*
* @param userId calling user
* @param locationOneGUID unique identifier of the first location
* @param locationTwoGUID unique identifier of the second location
*
* @throws InvalidParameterException one of the parameters is invalid
* @throws UserNotAuthorizedException the user is not authorized to issue this request
* @throws PropertyServerException there is a problem reported in the open metadata server(s)
*/
void clearAdjacentLocation(String userId,
String locationOneGUID,
String locationTwoGUID) 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.
*
* @param userId calling user
* @param searchString string to find in the properties
* @param startFrom paging start point
* @param pageSize maximum results that can be returned
*
* @return list of matching metadata elements
*
* @throws InvalidParameterException one of the parameters is invalid
* @throws UserNotAuthorizedException the user is not authorized to issue this request
* @throws PropertyServerException there is a problem reported in the open metadata server(s)
*/
List findLocations(String userId,
String searchString,
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.
*
* @param userId calling user
* @param name name to search for
* @param startFrom paging start point
* @param pageSize maximum results that can be returned
*
* @return list of matching metadata elements
*
* @throws InvalidParameterException one of the parameters is invalid
* @throws UserNotAuthorizedException the user is not authorized to issue this request
* @throws PropertyServerException there is a problem reported in the open metadata server(s)
*/
List getLocationsByName(String userId,
String name,
int startFrom,
int pageSize) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Retrieve the location metadata element with the supplied unique identifier.
*
* @param userId calling user
* @param locationGUID unique identifier of the requested metadata element
*
* @return matching metadata element
*
* @throws InvalidParameterException one of the parameters is invalid
* @throws UserNotAuthorizedException the user is not authorized to issue this request
* @throws PropertyServerException there is a problem reported in the open metadata server(s)
*/
LocationElement getLocationByGUID(String userId,
String locationGUID) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
}