org.odpi.openmetadata.accessservices.digitalarchitecture.api.ManageConnections 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.ConnectionElement;
import org.odpi.openmetadata.accessservices.digitalarchitecture.metadataelements.ConnectorTypeElement;
import org.odpi.openmetadata.accessservices.digitalarchitecture.metadataelements.EndpointElement;
import org.odpi.openmetadata.accessservices.digitalarchitecture.properties.ConnectionProperties;
import org.odpi.openmetadata.accessservices.digitalarchitecture.properties.ConnectorTypeProperties;
import org.odpi.openmetadata.accessservices.digitalarchitecture.properties.EndpointProperties;
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;
import java.util.Map;
/**
* ManageConnections provides methods to define connections and their supporting objects
*
* The interface supports the following types of objects
*
*
* - Connections - the connections used to create connector instances that can access the connection.
* - ConnectorTypes - description of a specific that can be used to access the connection.
* - ConnectorCategories - the network information needed to access the connection.
* - Endpoints - the network information needed to access the connection.
*
*/
public interface ManageConnections
{
/*
* The Connection entity is the top level element to describe the information needed to create a connector to an asset.
*/
/**
* Create a new metadata element to represent the connection.
*
* @param userId calling user
* @param connectionProperties 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 createConnection(String userId,
ConnectionProperties connectionProperties) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Create a new metadata element to represent a connection using an existing metadata element as a template.
* The template defines additional classifications and relationships that should be added to the new asset.
*
* @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 createConnectionFromTemplate(String userId,
String templateGUID,
TemplateProperties templateProperties) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Update the metadata element representing a connection.
*
* @param userId calling user
* @param connectionGUID unique identifier of the metadata element to update
* @param isMergeUpdate should the new properties be merged with existing properties (true) or completely replace them (false)?
* @param connectionProperties 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 updateConnection(String userId,
String connectionGUID,
boolean isMergeUpdate,
ConnectionProperties connectionProperties) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Create a relationship between a connection and a connector type.
*
* @param userId calling user
* @param connectionGUID unique identifier of the connection in the external asset manager
* @param connectorTypeGUID unique identifier of the connector type in the external asset manager
*
* @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 setupConnectorType(String userId,
String connectionGUID,
String connectorTypeGUID) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Remove a relationship between a connection and a connector type.
*
* @param userId calling user
* @param connectionGUID unique identifier of the connection in the external asset manager
* @param connectorTypeGUID unique identifier of the connector type in the external asset manager
*
* @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 clearConnectorType(String userId,
String connectionGUID,
String connectorTypeGUID) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Create a relationship between a connection and an endpoint.
*
* @param userId calling user
* @param connectionGUID unique identifier of the connection in the external asset manager
* @param endpointGUID unique identifier of the endpoint in the external asset manager
*
* @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 setupEndpoint(String userId,
String connectionGUID,
String endpointGUID) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Remove a relationship between a connection and an endpoint.
*
* @param userId calling user
* @param connectionGUID unique identifier of the connection in the external asset manager
* @param endpointGUID unique identifier of the endpoint in the external asset manager
*
* @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 clearEndpoint(String userId,
String connectionGUID,
String endpointGUID) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Create a relationship between a virtual connection and an embedded connection.
*
* @param userId calling user
* @param connectionGUID unique identifier of the virtual connection in the external asset manager
* @param position which order should this connection be processed
* @param arguments What additional properties should be passed to the embedded connector via the configuration properties
* @param displayName what does this connector signify?
* @param embeddedConnectionGUID unique identifier of the embedded connection in the external asset manager
*
* @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 setupEmbeddedConnection(String userId,
String connectionGUID,
int position,
String displayName,
Map arguments,
String embeddedConnectionGUID) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Remove a relationship between a virtual connection and an embedded connection.
*
* @param userId calling user
* @param connectionGUID unique identifier of the virtual connection in the external asset manager
* @param embeddedConnectionGUID unique identifier of the embedded connection in the external asset manager
*
* @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 clearEmbeddedConnection(String userId,
String connectionGUID,
String embeddedConnectionGUID) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Create a relationship between an asset and its connection.
*
* @param userId calling user
* @param assetGUID unique identifier of the asset
* @param assetSummary summary of the asset that is stored in the relationship between the asset and the connection.
* @param connectionGUID unique identifier of the connection
*
* @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 setupAssetConnection(String userId,
String assetGUID,
String assetSummary,
String connectionGUID) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Remove a relationship between an asset and its connection.
*
* @param userId calling user
* @param assetGUID unique identifier of the asset
* @param connectionGUID unique identifier of the connection
*
* @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 clearAssetConnection(String userId,
String assetGUID,
String connectionGUID) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Remove the metadata element representing a connection. This will delete all anchored
* elements such as comments.
*
* @param userId calling user
* @param connectionGUID 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 removeConnection(String userId,
String connectionGUID) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Retrieve the list of asset 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 findConnections(String userId,
String searchString,
int startFrom,
int pageSize) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Retrieve the list of asset 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 getConnectionsByName(String userId,
String name,
int startFrom,
int pageSize) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Retrieve the connection metadata element with the supplied unique identifier.
*
* @param userId calling user
* @param connectionGUID 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)
*/
ConnectionElement getConnectionByGUID(String userId,
String connectionGUID) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/*
* The Endpoint entity describes the location of the resource.
*/
/**
* Create a new metadata element to represent the endpoint.
*
* @param userId calling user
* @param endpointProperties 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 createEndpoint(String userId,
EndpointProperties endpointProperties) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Create a new metadata element to represent a endpoint using an existing metadata element as a template.
* The template defines additional classifications and relationships that should be added to the new endpoint.
*
* @param userId calling user
* @param networkAddress location of the endpoint
* @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 createEndpointFromTemplate(String userId,
String networkAddress,
String templateGUID,
TemplateProperties templateProperties) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Update the metadata element representing a endpoint.
*
* @param userId calling user
* @param isMergeUpdate should the new properties be merged with existing properties (true) or completely replace them (false)?
* @param endpointGUID unique identifier of the metadata element to update
* @param endpointProperties 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 updateEndpoint(String userId,
boolean isMergeUpdate,
String endpointGUID,
EndpointProperties endpointProperties) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Remove the metadata element representing a endpoint. This will delete the endpoint and all categories
* and terms.
*
* @param userId calling user
* @param endpointGUID 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 removeEndpoint(String userId,
String endpointGUID) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Retrieve the list of endpoint 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 findEndpoints(String userId,
String searchString,
int startFrom,
int pageSize) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Retrieve the list of endpoint 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 getEndpointsByName(String userId,
String name,
int startFrom,
int pageSize) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Retrieve the endpoint metadata element with the supplied unique identifier.
*
* @param userId calling user
* @param endpointGUID 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)
*/
EndpointElement getEndpointByGUID(String userId,
String endpointGUID) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/*
* The ConnectorType entity describes a specific connector implementation.
*/
/**
* Create a new metadata element to represent the root of a connectorType.
*
* @param userId calling user
* @param connectorTypeProperties 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 createConnectorType(String userId,
ConnectorTypeProperties connectorTypeProperties) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Create a new metadata element to represent a connectorType using an existing metadata element as a template.
* The template defines additional classifications and relationships that should be added to the new connectorType.
*
* @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 createConnectorTypeFromTemplate(String userId,
String templateGUID,
TemplateProperties templateProperties) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Update the metadata element representing a connectorType.
*
* @param userId calling user
* @param isMergeUpdate should the new properties be merged with existing properties (true) or completely replace them (false)?
* @param connectorTypeGUID unique identifier of the metadata element to update
* @param connectorTypeProperties 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 updateConnectorType(String userId,
boolean isMergeUpdate,
String connectorTypeGUID,
ConnectorTypeProperties connectorTypeProperties) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Remove the metadata element representing a connectorType. This will delete the connectorType and all categories
* and terms.
*
* @param userId calling user
* @param connectorTypeGUID 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 removeConnectorType(String userId,
String connectorTypeGUID) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Retrieve the list of connectorType 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 findConnectorTypes(String userId,
String searchString,
int startFrom,
int pageSize) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Retrieve the list of connectorType 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 getConnectorTypesByName(String userId,
String name,
int startFrom,
int pageSize) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
/**
* Retrieve the connectorType metadata element with the supplied unique identifier.
*
* @param userId calling user
* @param connectorTypeGUID 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)
*/
ConnectorTypeElement getConnectorTypeByGUID(String userId,
String connectorTypeGUID) throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException;
}