Package org.odpi.openmetadata.frameworks.connectors

Class ConnectorBase

java.lang.Object
org.odpi.openmetadata.frameworks.connectors.Connector
org.odpi.openmetadata.frameworks.connectors.ConnectorBase
All Implemented Interfaces:
SecureConnectorExtension, VirtualConnectorExtension
Direct Known Subclasses:
ApacheAtlasRESTConnector, ApacheKafkaAdminConnector, BasicFileStoreConnector, BasicFolderConnector, CSVTabularDataSetConnector, GovernanceActionServiceConnector, IntegrationConnectorBase, JDBCResourceConnector, OMAGServerConfigStoreConnectorBase, OMAGServerConnectorBase, OMAGServerPlatformConnector, OMRSAuditLogStoreConnectorBase, OMRSCohortRegistryStoreConnectorBase, OMRSRepositoryConnector, OMRSRepositoryEventMapperConnector, OMRSTopicConnector, OpenMetadataArchiveStoreConnector, OpenMetadataSecurityConnector, OpenMetadataTopicConnector, OpenMetadataTopicConsumerBase, OSSUnityCatalogResourceConnector, PostgresTabularDataSetConnector, ReferenceDataSetConnectorBase, RepositoryGovernanceServiceConnector, RESTClientConnector, SecretsStoreConnector, SurveyActionServiceConnector, WatchdogActionServiceConnector
public abstract class ConnectorBase extends Connector implements SecureConnectorExtension, VirtualConnectorExtension
The ConnectorBase is an implementation of the Connector interface.

Connectors are client-side interfaces to assets such as data stores, data sets, APIs, analytical functions. They handle the communication with the server that hosts the assets, along with the communication with the metadata server to serve up metadata about the assets, and support for an audit log for the caller to log its activity.

Each connector implementation is paired with a connector provider. The connector provider is the factory for connector instances.

The Connector interface defines that a connector instance should be able to return a unique identifier, a connection object and a metadata properties object for its connected asset. These are supplied to the connector during its initialization.

The ConnectorBase base class implements all the methods required by the Connector interface. Each specific implementation of a connector then extends this interface to add the methods to work with the particular type of asset it supports. For example, a JDBC connector would add the standard JDBC SQL interface, the OMRS Connectors add the metadata repository management APIs...

  • Field Details

  • Constructor Details

    • ConnectorBase

      public ConnectorBase()
      Typical Constructor: Connectors should always have a constructor requiring no parameters and perform initialization in the initialize method.

  • Method Details

    • initialize

      public void initialize(String connectorInstanceId, Connection connectionDetails)
      Call made by the ConnectorProvider to initialize the Connector with the base services.
      Specified by:
      initialize in class Connector
      Parameters:
      connectorInstanceId - unique id for the connector instance useful for messages etc
      connectionDetails - POJO for the configuration used to create the connector.

    • combineConfigurationProperties

      protected Map<String,Object> combineConfigurationProperties(Map<String,Object> additionalConfigurationProperties)
      Combine the connector's configuration properties with the supplied additional configuration properties into a new map.
      Parameters:
      additionalConfigurationProperties - additional properties (can be null)
      Returns:
      combination of the connectors properties and the additional properties. Null is returned if both are null/empty.

    • logRecord

      protected void logRecord(String actionDescription, AuditLogMessageDefinition messageDefinition)
      Log an audit log record for an event, decision, error, or exception detected by the OMRS.
      Parameters:
      messageDefinition - description of the audit log record including specific resources involved
      actionDescription - calling method

    • logRecord

      protected void logRecord(String actionDescription, AuditLogMessageDefinition messageDefinition, String additionalInformation)
      Log an audit log record for an event, decision, error, or exception detected by the OMRS.
      Parameters:
      messageDefinition - description of the audit log record including specific resources involved
      actionDescription - calling method

    • logExceptionRecord

      protected void logExceptionRecord(String actionDescription, AuditLogMessageDefinition messageDefinition, Exception exception)
      Log an audit log record for an event, decision, error, or exception detected by the OMRS.
      Parameters:
      messageDefinition - description of the audit log record including specific resources involved
      actionDescription - calling method

    • initializeEmbeddedConnectors

      public void initializeEmbeddedConnectors(List<Connector> embeddedConnectors)
      Set up the list of connectors that this virtual connector will use to support its interface. The connectors are initialized waiting to start. When start() is called on the virtual connector, it needs to pass start() to each of the embedded connectors. Similar processing is needed for the disconnect() method.
      Specified by:
      initializeEmbeddedConnectors in interface VirtualConnectorExtension
      Parameters:
      embeddedConnectors - list of connectors

    • getConnectorInstanceId

      public String getConnectorInstanceId()
      Returns the unique connector instance id that assigned to the connector instance when it was created. It is useful for error and audit messages.
      Specified by:
      getConnectorInstanceId in class Connector
      Returns:
      guid for the connector instance

    • getConnection

      public Connection getConnection()
      Returns the connection object that was used to create the connector instance. Its contents are never refreshed during the lifetime of the connector instance, even if the connection information is updated or removed from the originating metadata repository.
      Specified by:
      getConnection in class Connector
      Returns:
      connection properties object

    • initializeSecretsStoreConnector

      public void initializeSecretsStoreConnector(String displayName, SecretsStoreConnector secretsStoreConnector)
      Set up information about an embedded connector that this connector can use to support secure access to its resources.
      Specified by:
      initializeSecretsStoreConnector in interface SecureConnectorExtension
      Parameters:
      displayName - name of the secrets store
      secretsStoreConnector - an embedded secrets store connector

    • start

      public void start() throws ConnectorCheckedException, UserNotAuthorizedException
      Indicates that the connector is completely configured and can begin processing.
      Specified by:
      start in class Connector
      Throws:
      ConnectorCheckedException - there is a problem within the connector.
      UserNotAuthorizedException - the connector was disconnected before/during start

    • getSuppliedPlaceholderProperties

      protected Map<String,String> getSuppliedPlaceholderProperties(Map<String,Object> configurationProperties)
      Pass the configuration properties as placeholder properties. This allows the caller to supply additional properties to a template beyond those envisaged in the connector implementation. The templating process is not affected if properties not use in the template are supplied
      Parameters:
      configurationProperties - supplied configuration properties
      Returns:
      placeholder properties map

    • getArrayConfigurationProperty

      protected List<String> getArrayConfigurationProperty(String propertyName, Map<String,Object> configurationProperties, List<String> defaultValue)
      Retrieve a configuration property that is a comma-separated list of strings.
      Parameters:
      propertyName - name of property
      configurationProperties - configuration properties
      defaultValue - value to use if the property is not specified.
      Returns:
      list of strings or null if not set

    • getArrayConfigurationProperty

      protected List<String> getArrayConfigurationProperty(String propertyName, Map<String,Object> configurationProperties, String defaultValue)
      Retrieve a configuration property that is a comma-separated list of strings.
      Parameters:
      propertyName - name of property
      configurationProperties - configuration properties
      defaultValue - value to use if the property is not specified.
      Returns:
      list of strings or null if not set

    • getArrayConfigurationProperty

      protected List<String> getArrayConfigurationProperty(String propertyName, Map<String,Object> configurationProperties)
      Retrieve a configuration property that is a comma-separated list of strings.
      Parameters:
      propertyName - name of property
      configurationProperties - configuration properties
      Returns:
      list of strings or null if not set

    • getBooleanConfigurationProperty

      protected boolean getBooleanConfigurationProperty(String propertyName, Map<String,Object> configurationProperties)
      Retrieve a configuration property that is a boolean. If any non-null value is set it returns true unless the value is set to FALSE, False or false.
      Parameters:
      propertyName - name of property
      configurationProperties - configuration properties
      Returns:
      boolean flag or false if not set

    • getIntConfigurationProperty

      protected int getIntConfigurationProperty(String propertyName, Map<String,Object> configurationProperties)
      Retrieve a configuration property that is an integer.
      Parameters:
      propertyName - name of property
      configurationProperties - configuration properties
      Returns:
      integer value or zero if not supplied

    • getLongConfigurationProperty

      protected long getLongConfigurationProperty(String propertyName, Map<String,Object> configurationProperties)
      Retrieve a configuration property that is an integer.
      Parameters:
      propertyName - name of property
      configurationProperties - configuration properties
      Returns:
      integer value or zero if not supplied

    • getStringConfigurationProperty

      protected String getStringConfigurationProperty(String propertyName, Map<String,Object> configurationProperties)
      Retrieve a configuration property that is a string or null if not set.
      Parameters:
      propertyName - name of property
      configurationProperties - configuration properties
      Returns:
      string value of property or null if not supplied

    • getStringConfigurationProperty

      protected String getStringConfigurationProperty(String propertyName, Map<String,Object> configurationProperties, String defaultValue)
      Retrieve a configuration property that is a string or null if not set.
      Parameters:
      propertyName - name of property
      configurationProperties - configuration properties
      defaultValue - value to use if the property is not in the configuration properties
      Returns:
      string value of property or null if not supplied

    • getDateConfigurationProperty

      protected Date getDateConfigurationProperty(String propertyName, Map<String,Object> configurationProperties) throws InvalidParameterException
      Retrieve a configuration property that is a string formatted date or null if not set.
      Parameters:
      propertyName - name of property
      configurationProperties - configuration properties
      Returns:
      string value of property or null if not supplied
      Throws:
      InvalidParameterException

    • fromCanonicalToSnakeCase

      public String fromCanonicalToSnakeCase(String name)
      Convert a canonical name to a name in snake case. Snake case is all in lower case with dashes between the words.
      Parameters:
      name - string to convert
      Returns:
      converted string

    • fromSnakeToCanonicalCase

      public String fromSnakeToCanonicalCase(String name)
      Return the supplied name in a canonical format used for this data source. Each word in the name should be capitalized, with spaces between the words to allow translation between different naming conventions.
      Parameters:
      name - string to convert
      Returns:
      string

    • fromCanonicalToKebabCase

      public String fromCanonicalToKebabCase(String name)
      Convert a canonical name to a name in snake case. Snake case is all in lower case with dashes between the words.
      Parameters:
      name - string to convert
      Returns:
      converted string

    • fromKebabToCanonicalCase

      public String fromKebabToCanonicalCase(String name)
      Return the supplied name in a canonical format used for this data source. Each word in the name should be capitalized, with spaces between the words to allow translation between different naming conventions.
      Parameters:
      name - string to convert
      Returns:
      string

    • throwNoAsset

      protected void throwNoAsset(String assetGUID, String connectorName, String methodName) throws ConnectorCheckedException
      Log that no asset has been returned to the connector. It is unable to proceed without this basic information.
      Parameters:
      assetGUID - the unique identifier of the asset from the connection context
      connectorName - name of the connector
      methodName - calling method
      Throws:
      ConnectorCheckedException - resulting exception

    • throwWrongTypeOfAsset

      protected void throwWrongTypeOfAsset(String assetGUID, String assetType, String supportedAssetType, String connectorName, String methodName) throws ConnectorCheckedException
      Log that the connector can not process the type of asset it has been passed.
      Parameters:
      assetGUID - identifier of the asset
      assetType - type of the asset
      supportedAssetType - supported asset types
      connectorName - name of the connector
      methodName - calling method
      Throws:
      ConnectorCheckedException - resulting exception

    • throwWrongTypeOfResource

      protected void throwWrongTypeOfResource(String assetGUID, String assetTypeName, String assetResourceName, String assetResourceType, String supportedResourceType, String connectorName, String methodName) throws ConnectorCheckedException
      Log that the connector can not process the type of asset it has been passed.
      Parameters:
      assetGUID - identifier of the asset
      assetTypeName - type of the asset
      assetResourceName - name of the resource
      assetResourceType - type of the resource
      supportedResourceType - supported resource types
      connectorName - name of the connector
      methodName - calling method
      Throws:
      ConnectorCheckedException - resulting exception

    • throwMissingResource

      protected void throwMissingResource(String assetGUID, String assetTypeName, String assetResourceName, String methodName) throws ConnectorCheckedException
      Log that the connector can not process the type of asset it has been passed.
      Parameters:
      assetGUID - identifier of the asset
      assetTypeName - type of the asset
      assetResourceName - name of the resource
      methodName - calling method
      Throws:
      ConnectorCheckedException - resulting exception

    • throwMissingConfigurationProperty

      protected void throwMissingConfigurationProperty(String connectorName, String resourceName, String propertyName, String methodName) throws ConnectorCheckedException
      Log that the connector can not process the named resource because a key configuration property is missing.
      Parameters:
      connectorName - name of the connector
      resourceName - source of the configuration properties
      propertyName - name of the missing property
      methodName - calling method
      Throws:
      ConnectorCheckedException - resulting exception

    • throwMissingEndpointAddress

      protected void throwMissingEndpointAddress(String connectorName, String methodName) throws ConnectorCheckedException
      Log that the connector does no have an endpoint address.
      Parameters:
      connectorName - name of the connector
      methodName - calling method
      Throws:
      ConnectorCheckedException - resulting exception

    • throwWrongTypeOfRootSchema

      protected void throwWrongTypeOfRootSchema(String assetGUID, String rootSchemaType, String supportedRootSchemaType, String connectorName, String methodName) throws ConnectorCheckedException
      Log that the survey action service can not process the type of root schema it has been passed.
      Parameters:
      assetGUID - identifier of the asset
      rootSchemaType - type of the root schema
      supportedRootSchemaType - supported root schema types
      connectorName - name of the connector
      methodName - calling method
      Throws:
      ConnectorCheckedException - resulting exception

    • disconnect

      public void disconnect() throws ConnectorCheckedException
      Free up any resources held since the connector is no longer needed.
      Specified by:
      disconnect in class Connector
      Throws:
      ConnectorCheckedException - there is a problem within the connector.

    • disconnectConnectors

      protected void disconnectConnectors(List<Connector> activeConnectors)
      Disconnect all the connectors in the supplied list. Any failures are ignored. This method is typically used by virtual connectors to disconnect their embedded connectors.
      Parameters:
      activeConnectors - connectors to disconnect.

    • isActive

      public boolean isActive()
      Return a flag indicating whether the connector is active. This means it has been started and not yet disconnected.
      Returns:
      isActive flag

    • hashCode

      public int hashCode()
      Provide a common implementation of hashCode for all OCF Connector objects. The UUID is unique and is randomly assigned and so its hashCode is as good as anything to describe the hash code of the connector object.
      Overrides:
      hashCode in class Object
      Returns:
      random UUID as hashcode

    • equals

      public boolean equals(Object object)
      Provide a common implementation of equals for all OCF Connector Provider objects. The UUID is unique and is randomly assigned and so its hashCode is as good as anything to evaluate the equality of the connector provider object.
      Overrides:
      equals in class Object
      Parameters:
      object - object to test
      Returns:
      boolean flag

    • toString

      public String toString()
      Standard toString method.
      Overrides:
      toString in class Object
      Returns:
      print out of variables in a JSON-style