Package com.ibm.di.connector

Class RACConnector

  • All Implemented Interfaces:
    ConnectorInterface, VersionInfoInterface
    public class RACConnector
extends Connector
implements ConnectorInterface

    The RAC Connector collaborates with the Agent Controller and Generic Log Adapter technologies to: - supply a TDI Assembly Line with log data from the log of a remote software system (in Iterator mode) - allow a TDI Assembly Line to publish data to remote clients (in AddOnly mode) (Agent Controller is the new name of the Remote Agent Controller (RAC))

    When operating in AddOnly mode, the Connector registers a Logging Agent with the local Agent Controller. All Common Base Event objects, received from the Assembly Line, are serialized as XML and written to the Logging Agent. The Logging Agent stays operational as long as the process of the TDI server is alive. During its lifetime it can be monitored by clients even if the Connector which registered it has already closed. When the TDI server stops (or crashes), however, the Agent Controller (RAC) terminates the TDI Logging Agent's registration. The Connector could wait a specified amount of time for a monitoring client to arrive before starting to write data to the Logging Agent. Particularly, it can wait forever. When a client starts monitoring the agent, the agent starts transferring data to the Agent Controller. The Agent Controller then sends the data to the client. Waiting happens before each write attempt (the 'putEntry' method of the Connector). If the waiting time expires and there is still no monitoring client, the Connector throws an Exception. Internally the Connector uses the TPTP Logging Agent implementation - org.eclipse.hyades.logging.core.LoggingAgent.

    In Iterator mode the RAC Connector acts as a client of a remote Agent Controller. It connects to the Agent Controller to obtain a handle to the Logging Agent, whose name is specified in the Connector's configuration. After that the Connector starts monitoring the Logging Agent. During the monitoring, the Connector receives data, produced by the Logging Agent. If there is no active agent with the specified name, when the Connector contacts the Agent Controller, the Connector waits until such agent is registered. If at some point the agent gets unregistered (while the Connector is listening for events), the Connector will wait for another agent with the same name to appear. Essentially the Connector never stops unless its connection to the Agent Controller fails. The implementation of the Connector relies on the Java client library, which is part of the Agent Controller technology.

    Since:
    6.1.1

    • Field Detail

      • PARAM_REMOTE_LOGGING_AGENT_NAME

        public static final java.lang.String PARAM_REMOTE_LOGGING_AGENT_NAME
        The name of the remote Logging Agent to be monitored.
        See Also:
        Constant Field Values

      • PARAM_AGENT_CONTROLLER_HOST

        public static final java.lang.String PARAM_AGENT_CONTROLLER_HOST
        Host of the remote Agent Controller.
        See Also:
        Constant Field Values

      • PARAM_AGENT_CONTROLLER_PORT

        public static final java.lang.String PARAM_AGENT_CONTROLLER_PORT
        Port of the remote Agent Controller.
        See Also:
        Constant Field Values

      • PARAM_RECEIVING_QUEUE_SIZE

        public static final java.lang.String PARAM_RECEIVING_QUEUE_SIZE
        The size of the queue, where the received events are buffered before the Connector manages to read them.
        See Also:
        Constant Field Values

      • PARAM_WAIT_FOR_DEAD_AGENT_DATA_TIMEOUT

        public static final java.lang.String PARAM_WAIT_FOR_DEAD_AGENT_DATA_TIMEOUT
        Timeout (in seconds) for each data reception after the remote agent dies. If this timeout expires, the agent's data is considered depleted and the Connector starts looking for another agent with the same name.
        See Also:
        Constant Field Values

      • PARAM_CONNECTION_TIMEOUT

        public static final java.lang.String PARAM_CONNECTION_TIMEOUT
        Timeout (in seconds) for the connection to the Agent Controller.
        See Also:
        Constant Field Values

      • PARAM_LOGGING_AGENT_NAME

        public static final java.lang.String PARAM_LOGGING_AGENT_NAME
        The name of the Logging Agent within the local Agent Controller.
        See Also:
        Constant Field Values

      • PARAM_WAIT_TO_BE_MONITORED

        public static final java.lang.String PARAM_WAIT_TO_BE_MONITORED
        Time to wait (in seconds) for the agent to be monitored. If zero, waits forever. Potentially, waiting can be performed before each write.
        See Also:
        Constant Field Values

    • Constructor Detail

      • RACConnector

        public RACConnector()
        Constructor for the RAC Connector object

    • Method Detail

      • initialize

        public void initialize​(java.lang.Object aObj)
                throws java.lang.Exception

        Reads and validates the Connector's configuration parameters.

        In Iterator mode establishes a connection to the remote Agent Controller.

        In AddOnly mode registers a Logging Agent within the local Agent Controller. If a Logging Agent with the specified name is already registered, it is reused.

        Specified by:
        initialize in interface ConnectorInterface
        Overrides:
        initialize in class Connector
        Parameters:
        aObj - - ignored.
        Throws:
        java.lang.Exception - if some of the configuration parameters has invalid value in Iterator mode, if a problem occurs while connecting to the remote Agent Controller

      • getNextEntry

        public Entry getNextEntry()
                   throws java.lang.Exception
        Retrieves the next CommonBaseEvent produced by the remote Logging Agent.
        Specified by:
        getNextEntry in interface ConnectorInterface
        Overrides:
        getNextEntry in class Connector
        Returns:
        the next CBE or null if no more are available.
        Throws:
        java.lang.Exception - if some error occurred during the interaction with the remote Agent Controller
        See Also:
        ConnectorInterface.selectEntries()

      • putEntry

        public void putEntry​(Entry aEntry)
              throws java.lang.Exception

        Creates a CommonBaseEvent object using the attributes of the given Entry. After that serializes the Common Base Event object as a XML fragment and publishes the XML fragment through the Logging Agent.

        Before doing anything, however, the method will wait a client to monitor the Logging Agent. (If there is already a monitoring client, the method will not wait.) If the Connector is configured to wait for a finite time and that time expires, an exception will be thrown.

        Specified by:
        putEntry in interface ConnectorInterface
        Overrides:
        putEntry in class Connector
        Parameters:
        aEntry - the CBE object (as entry) to publish.
        Throws:
        java.lang.Exception - if there is no monitoring client within the configured waiting time if the specified Entry cannot be converted into a CommonBaseEvent

      • terminate

        public void terminate()
        Terminate the Connector.

        In Iterator mode stops monitoring and detaches from the remote agent, so that other clients can monitor it.

        In AddOnly mode does nothing - does not deregister the Logging Agent. This way the agent can be reused by other Connectors inside the same TDI server instance. All agents will get automatically unregistered by the Agent Controller when the TDI server process exits (the JVM shuts down).

        Specified by:
        terminate in interface ConnectorInterface
        Overrides:
        terminate in class Connector

      • isLogging

        public boolean isLogging()
        This method determines whether the Logging Agent, which the Connector uses, is currently being monitored by a client. (The Connector will not write anything to the agent until it is monitored.) The method can be used only in AddOnly mode.
        Returns:
        true if the Logging Agent is logging, false otherwise.

      • getCurrentCbeObject

        public org.eclipse.hyades.logging.events.cbe.CommonBaseEvent getCurrentCbeObject()
        Returns the Common Base Event object, obtained by the Connector on the current Assembly Line iteration (the last event, processed by the 'getNextEntry' method of the Connector).
        Returns:
        the current CBE.

      • getVersion

        public java.lang.String getVersion()
        Version information.
        Specified by:
        getVersion in interface VersionInfoInterface
        Returns:
        The version of the Connector.