Package org.odpi.openmetadata.frameworks.connectors

Class Connector

java.lang.Object
org.odpi.openmetadata.frameworks.connectors.Connector
Direct Known Subclasses:
ConnectorBase
public abstract class Connector extends Object

The Connector is the interface for all connector instances. 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 (properties) about the assets.

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 object called ConnectedAssetProperties.

Each specific implementation of a connector then extends the Connector 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...

The initialize() method is called by the Connector Provider to set up the connector instance Identifier and the Connection properties for the connector as part of its construction process.

The start() method is called by the code that creates the connector when it is ready for the connector to run. This calling code is also responsible for calling disconnect().

ConnectedAssetProperties provides descriptive properties about the asset that the connector is accessing. It is supplied to the connector later during its initialization through the initializeConnectedAssetProperties() method. See AssetConsumer OMAS for an example of this.

Every connector is able to gather statistics during its operation - these are named properties, named counters and named timestamps. The getConnectorStatistics() returns the combination of these values.

Both the connector and the connector provider have base classes (ConnectorBase and ConnectorProviderBase respectively) that implement all the standard methods. The connector developer extends these classes to add the specific methods to manage the asset and configure the base classes.

  • Constructor Details

    • Connector

      protected Connector()
      Default constructor

  • Method Details

    • initialize

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

    • getConnectorInstanceId

      public abstract 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.
      Returns:
      guid for the connector instance

    • getConnection

      public abstract ConnectionProperties getConnection()
      Returns the connection object that was used to create the connector instance. Its contents are never refreshed during the lifetime of a connector instance even if the connection information is updated or removed from the originating metadata repository.
      Returns:
      connection properties object

    • initializeConnectedAssetProperties

      public abstract void initializeConnectedAssetProperties(ConnectedAssetProperties connectedAssetProperties)
      Set up the connected asset properties object. This provides the known metadata properties stored in one or more metadata repositories. The implementation of the connected asset properties object is free to determine when the properties are populated. It may be as lazy as whenever getConnectedAssetProperties() is called.
      Parameters:
      connectedAssetProperties - properties of the connected asset

    • getConnectedAssetProperties

      public abstract ConnectedAssetProperties getConnectedAssetProperties(String userId) throws PropertyServerException, UserNotAuthorizedException
      Returns the properties that contain the metadata for the asset. The asset metadata is retrieved from the metadata repository and cached in the ConnectedAssetProperties object each time the getConnectedAssetProperties method is requested by the caller. Once the ConnectedAssetProperties object has the metadata cached, it can be used to access the asset property values many times without a return to the metadata repository. The cache of metadata can be refreshed simply by calling this getConnectedAssetProperties() method again.
      Parameters:
      userId - userId of requesting user
      Returns:
      ConnectedAssetProperties connected asset properties
      Throws:
      PropertyServerException - indicates a problem retrieving properties from a metadata repository
      UserNotAuthorizedException - indicates that the user is not authorized to access the asset properties.

    • start

      public abstract void start() throws ConnectorCheckedException
      Indicates that the connector is completely configured and can begin processing.
      Throws:
      ConnectorCheckedException - there is a problem within the connector.

    • getConnectorStatistics

      public Map<String,Object> getConnectorStatistics()
      Retrieve all the statistics gathered by the connector.
      Returns:
      name-value pairs for the statistics

    • initializeStatisticCounter

      public void initializeStatisticCounter(String counterName, int counterValue, String methodName) throws InvalidParameterException
      Reset (or initialize) the value of a counter. This method reserves the counterName as a name for counters. This means the same name can not be used for a property or a timestamp.
      Parameters:
      counterName - name of the counter
      counterValue - initial value of the counter
      methodName - calling method
      Throws:
      InvalidParameterException - the counter name is already in use as a timestamp or property

    • incrementStatisticCounter

      public void incrementStatisticCounter(String counterName, String methodName) throws InvalidParameterException
      Increment the named counter. If the counter name is new, it is assumed to be set to zero, resulting in a value of 1.
      Parameters:
      counterName - name of counter
      methodName - calling method
      Throws:
      InvalidParameterException - the counter name is already in use as a timestamp or property

    • getStatisticCounter

      public int getStatisticCounter(String counterName, String methodName) throws InvalidParameterException
      Retrieve the value for a specific counter statistic. If the counter is not known, it is defined in the statistics list with a zero value.
      Parameters:
      counterName - name of the counter
      methodName - calling method
      Returns:
      counter value or 0 if the counter is not known
      Throws:
      InvalidParameterException - the counter name is actually in use as a timestamp or property

    • setStatisticProperty

      public void setStatisticProperty(String propertyName, String propertyValue, String methodName) throws InvalidParameterException
      Set up the requested property. An exception is thrown if the property name clashes with a counter or timestamp statistic.
      Parameters:
      propertyName - name of the property
      propertyValue - new value
      methodName - calling method name
      Throws:
      InvalidParameterException - the property name is already in use as either a counter or timestamp statistic

    • clearStatisticProperty

      public void clearStatisticProperty(String propertyName, String methodName) throws InvalidParameterException
      Remove a property statistic. An exception is thrown if the property name is actually the name of either a counter or timestamp statistic.
      Parameters:
      propertyName - name of property
      methodName - calling method
      Throws:
      InvalidParameterException - the property name is actually a counter or timestamp statistic

    • getStatisticProperty

      public String getStatisticProperty(String propertyName, String methodName) throws InvalidParameterException
      Return the value associated with the supplied property name (or null if the property name is not known.
      Parameters:
      propertyName - requested property name
      methodName - calling method
      Returns:
      property value
      Throws:
      InvalidParameterException - the property name is actually a counter or timestamp statistic

    • setStatisticTimestamp

      public void setStatisticTimestamp(String timestampName, Date timestampValue, String methodName) throws InvalidParameterException
      Set up the requested timestamp. An exception is thrown if the timestamp name clashes with a counter or property statistic.
      Parameters:
      timestampName - name of the timestamp
      timestampValue - new value
      methodName - calling method name
      Throws:
      InvalidParameterException - the timestamp name is already in use as either a counter or property statistic

    • clearStatisticTimestamp

      public void clearStatisticTimestamp(String timestampName, String methodName) throws InvalidParameterException
      Remove a timestamp statistic. An exception is thrown if the timestamp name is actually the name of either a counter or property statistic.
      Parameters:
      timestampName - name of timestamp
      methodName - calling method
      Throws:
      InvalidParameterException - the timestamp name is actually a counter or property statistic

    • getStatisticTimestamp

      public Date getStatisticTimestamp(String timestampName, String methodName) throws InvalidParameterException
      Return the value associated with the supplied timestamp name (or null if the timestamp name is not known).
      Parameters:
      timestampName - requested timestamp name
      methodName - calling method
      Returns:
      timestamp value
      Throws:
      InvalidParameterException - the timestamp name is actually a counter or property statistic

    • disconnect

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