Class Connector

  • Direct Known Subclasses:
    ConnectorBase

    public abstract class Connector
    extends java.lang.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 Id 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 Summary

      Constructors 
      Modifier Constructor Description
      protected Connector()
      Default constructor
    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      void clearStatisticProperty​(java.lang.String propertyName, java.lang.String methodName)
      Remove a property statistic.
      void clearStatisticTimestamp​(java.lang.String timestampName, java.lang.String methodName)
      Remove a timestamp statistic.
      abstract void disconnect()
      Free up any resources held since the connector is no longer needed.
      abstract ConnectedAssetProperties getConnectedAssetProperties​(java.lang.String userId)
      Returns the properties that contain the metadata for the asset.
      abstract ConnectionProperties getConnection()
      Returns the connection object that was used to create the connector instance.
      abstract java.lang.String getConnectorInstanceId()
      Returns the unique connector instance id that assigned to the connector instance when it was created.
      java.util.Map<java.lang.String,​java.lang.Object> getConnectorStatistics()
      Retrieve all the statistics gathered by the connector.
      int getStatisticCounter​(java.lang.String counterName, java.lang.String methodName)
      Retrieve the value for a specific counter statistic.
      java.lang.String getStatisticProperty​(java.lang.String propertyName, java.lang.String methodName)
      Return the value associated with the supplied property name (or null if the property name is not known.
      java.util.Date getStatisticTimestamp​(java.lang.String timestampName, java.lang.String methodName)
      Return the value associated with the supplied timestamp name (or null if the timestamp name is not known).
      void incrementStatisticCounter​(java.lang.String counterName, java.lang.String methodName)
      Increment the named counter.
      abstract void initialize​(java.lang.String connectorInstanceId, ConnectionProperties connection)
      Call made by the ConnectorProvider to initialize the Connector with the base services.
      abstract void initializeConnectedAssetProperties​(ConnectedAssetProperties connectedAssetProperties)
      Set up the connected asset properties object.
      void initializeStatisticCounter​(java.lang.String counterName, int counterValue, java.lang.String methodName)
      Reset (or initialize) the value of a counter.
      void setStatisticProperty​(java.lang.String propertyName, java.lang.String propertyValue, java.lang.String methodName)
      Set up the requested property.
      void setStatisticTimestamp​(java.lang.String timestampName, java.util.Date timestampValue, java.lang.String methodName)
      Set up the requested timestamp.
      abstract void start()
      Indicates that the connector is completely configured and can begin processing.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • Connector

        protected Connector()
        Default constructor
    • Method Detail

      • initialize

        public abstract void initialize​(java.lang.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 java.lang.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​(java.lang.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.
      • getConnectorStatistics

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

        public void initializeStatisticCounter​(java.lang.String counterName,
                                               int counterValue,
                                               java.lang.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​(java.lang.String counterName,
                                              java.lang.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​(java.lang.String counterName,
                                       java.lang.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​(java.lang.String propertyName,
                                         java.lang.String propertyValue,
                                         java.lang.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​(java.lang.String propertyName,
                                           java.lang.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 java.lang.String getStatisticProperty​(java.lang.String propertyName,
                                                     java.lang.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​(java.lang.String timestampName,
                                          java.util.Date timestampValue,
                                          java.lang.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​(java.lang.String timestampName,
                                            java.lang.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 java.util.Date getStatisticTimestamp​(java.lang.String timestampName,
                                                    java.lang.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