Class D2Japi



  • public class D2Japi
    extends java.lang.Object
    Singleton class providing entry point to get connection to D2000
    • Method Detail

      • getInstance

        public static D2Japi getInstance​()
        Get single instance of D2Japi class.
        Returns:
        single instance
      • createConnector

        public java.util.concurrent.Future<D2Connector> createConnector​(java.lang.String connectionString,
                                                                        D2ConnectorEventsListener eventsListener)
        Create new instance of D2Connector connected and ready for use.
        Parameters:
        connectionString - connection string is in format hostname:port or ipaddress:port. for example localhost:3120
        eventsListener - listener object to receive connection asynchronous events from JAPI
        Returns:
        upcoming connection in form of Future object
      • createConnector

        public java.util.concurrent.Future<D2Connector> createConnector​(java.lang.String connectionString,
                                                                        java.lang.String certificatePath,
                                                                        D2ConnectorEventsListener eventsListener)
        Create new instance of D2Connector connected with TLS and ready for use.
        Parameters:
        connectionString - connection string is in format hostname:port or ipaddress:port. for example localhost:3120
        certificatePath - path to *.cer file with certificate
        eventsListener - listener object to receive connection asynchronous events from JAPI
        Returns:
        upcoming connection in form of Future object
      • startListeningForConnection

        public ListeningHandle startListeningForConnection​(java.lang.String address,
                                                           int port,
                                                           ServerSocketEventsListener listener)
                                                    throws ConnectorException
        Open server socket at provided address and port and wait for incoming connection from D2Connector.

        Incoming socket connection is at first consulted with listener whether to accept it or reject it. If listener accepts incoming connection, triple handshake procedure follows in order to verify, that it is D2Connector.exe process connecting. After successful handshake a new instance of D2Connector is created and passed to the listener. Otherwise the listener is notified about failure.

        It is possible to to open listening socket on either one or all available network interfaces. Set value of address to address of specific network interface or to null for listening on all interfaces. Network interface is addressable either by its IP address (both v4 and v6) or DNS.

        Parameters:
        address - address of specific interface or null for all interfaces
        port - number of port for listening socket from range 1 .. 0xFFFF.
        listener - instance that is being consulted and notified about incoming connections
        Returns:
        a handle for closing listening socket
        Throws:
        ConnectorException - when it is not possible to open listening socket
      • startListeningForConnection

        public ListeningHandle startListeningForConnection​(java.lang.String address,
                                                           int port,
                                                           java.lang.String certificatePath,
                                                           ServerSocketEventsListener listener)
                                                    throws ConnectorException
        Open server socket at provided address and port and wait for incoming TLS connection from D2Connector.

        Incoming socket connection is at first consulted with listener whether to accept it or reject it. If listener accepts incoming connection, triple handshake procedure follows in order to verify, that it is D2Connector.exe process connecting. After successful handshake a new instance of D2Connector is created and passed to the listener. Otherwise the listener is notified about failure.

        It is possible to to open listening socket on either one or all available network interfaces. Set value of address to address of specific network interface or to null for listening on all interfaces. Network interface is addressable either by its IP address (both v4 and v6) or DNS.

        Parameters:
        address - address of specific interface or null for all interfaces
        port - number of port for listening socket from range 1 .. 0xFFFF.
        certificatePath - path to the file with certificate
        listener - instance that is being consulted and notified about incoming connections
        Returns:
        a handle for closing listening socket
        Throws:
        ConnectorException - when it is not possible to open listening socket
      • createRedundantConnectionManager

        public RedundantConnectionManager createRedundantConnectionManager​(java.util.List<ConnectionParameters> connectionParameters,
                                                                           RedundantConnectionEventListener listener,
                                                                           long retryTime,
                                                                           java.util.concurrent.TimeUnit retryUnit,
                                                                           boolean disconnectStandBySessions)
        Create new instance of RedundantConnectionManager for handling direct connections.

        Instance runs background job that tries to keep opened D2Connector instances for each item of connectionParameters list.

        When request for new D2Session occurs, it tries to create a new session with each of opened connector and returns the one connected to HOT kernel. Other sessions are closed. It repeats its attempts until HOT session is obtained with (retryTime, retryUnit) sleep interval.

        Depending on D2Connector.exe process configuration, change of HOT kernel might end up with:

        • D2Connector.exe keeps the opened sessions alive and connected to (from now on) SBS kernel, although in read-only mode. They might become active again, when kernel becomes HOT sometime in future.
        • D2Connector.exe explicitly terminates all the sessions, since it disconnects from SBS server and tries to find and connect to new HOT kernel itself.
        Parameters:
        connectionParameters - list of address:port pairs with optional path to certificate file.
        listener - optional listener that receives events about underlying D2Connectors.
        retryTime - sleep period size
        retryUnit - sleep period time unit
        disconnectStandBySessions - if true RedundantConnectionManager forcibly disconnects sessions that became connected to SBS kernel after redundancy switch.
        Returns:
        new instance of RedundantConnectionManager
      • createRedundantConnectionManager

        public RedundantConnectionManager createRedundantConnectionManager​(java.lang.String localInterface,
                                                                           int localPort,
                                                                           java.util.List<java.lang.String> allowedHosts,
                                                                           RedundantConnectionEventListener listener,
                                                                           long retryTime,
                                                                           java.util.concurrent.TimeUnit retryUnit,
                                                                           boolean disconnectStandBySessions)
                                                                    throws ConnectorException
        Create new instance of RedundantConnectionManager for handling reverse connections without use of certificate.

        Instance opens socket for listening at specified address and waits for incoming connections. It compares each incoming connection address with list of allowedHosts (resolves the list to IP addresses) and accepts one that is found in the list. Other connections are rejected.

        When request for new D2Session occurs, it tries to create a new session with each of opened connector and returns the one connected to HOT kernel. Other sessions are closed. It repeats its attempts until HOT session is obtained with (retryTime, retryUnit) sleep interval.

        Depending on D2Connector.exe process configuration, change of HOT kernel might end up with:

        • D2Connector.exe keeps the opened sessions alive and connected to (from now on) SBS kernel, although in read-only mode. They might become active again, when kernel becomes HOT sometime in future.
        • D2Connector.exe explicitly terminates all the sessions, since it disconnects from SBS server and tries to find and connect to new HOT kernel itself.
        Parameters:
        localInterface - address of specific interface or null for all interfaces
        localPort - number of port for listening socket from range 1 .. 0xFFFF.
        allowedHosts - list of host names or IP addresses that are allowed to connect
        listener - optional listener that receives events about underlying D2Connectors.
        retryTime - sleep period size
        retryUnit - sleep period time unit
        disconnectStandBySessions - if true RedundantConnectionManager forcibly disconnects sessions that became connected to SBS kernel after redundancy switch.
        Returns:
        new instance of RedundantConnectionManager
        Throws:
        ConnectorException - when unable to open listening socket
      • createRedundantConnectionManager

        public RedundantConnectionManager createRedundantConnectionManager​(java.lang.String localInterface,
                                                                           int localPort,
                                                                           java.lang.String certificatePath,
                                                                           java.util.List<java.lang.String> allowedHosts,
                                                                           RedundantConnectionEventListener listener,
                                                                           long retryTime,
                                                                           java.util.concurrent.TimeUnit retryUnit,
                                                                           boolean disconnectStandBySessions)
                                                                    throws ConnectorException
        Create new instance of RedundantConnectionManager for handling reverse connections using TLS socket.

        Instance opens socket for listening at specified address and waits for incoming connections. It compares each incoming connection address with list of allowedHosts (resolves the list to IP addresses) and accepts one that is found in the list. Other connections are rejected.

        When request for new D2Session occurs, it tries to create a new session with each of opened connector and returns the one connected to HOT kernel. Other sessions are closed. It repeats its attempts until HOT session is obtained with (retryTime, retryUnit) sleep interval.

        Depending on D2Connector.exe process configuration, change of HOT kernel might end up with:

        • D2Connector.exe keeps the opened sessions alive and connected to (from now on) SBS kernel, although in read-only mode. They might become active again, when kernel becomes HOT sometime in future.
        • D2Connector.exe explicitly terminates all the sessions, since it disconnects from SBS server and tries to find and connect to new HOT kernel itself.
        Parameters:
        localInterface - address of specific interface or null for all interfaces
        localPort - number of port for listening socket from range 1 .. 0xFFFF.
        certificatePath - path to file with certificate for TLS connection
        allowedHosts - list of host names or IP addresses that are allowed to connect
        listener - optional listener that receives events about underlying D2Connectors.
        retryTime - sleep period size
        retryUnit - sleep period time unit
        disconnectStandBySessions - if true RedundantConnectionManager forcibly disconnects sessions that became connected to SBS kernel after redundancy switch.
        Returns:
        new instance of RedundantConnectionManager
        Throws:
        ConnectorException - when unable to open listening socket