Package com.ibm.di.api

Class APIEngine

  • public class APIEngine
extends java.lang.Object
    This is the core class of the Server API. The APIEngine class does all initialization of the Server API. Both the local and the remote APIs are initialized by this class. During the initialization the values of the "api.*" properties in global.properties/solution.properties are used. This class provides methods which give access to a local session needed for using the local API.

    • Field Detail

      • PROP_API_ON

        public static final java.lang.String PROP_API_ON
        Property name used to switch the TDI local API on and off.
        See Also:
        Constant Field Values

      • PROP_API_USER_REGISTRY

        public static final java.lang.String PROP_API_USER_REGISTRY
        Property name used to specify the path to the user registry.
        See Also:
        Constant Field Values

      • PROP_API_USER_REGISTRY_ENCRYPTION_ON

        public static final java.lang.String PROP_API_USER_REGISTRY_ENCRYPTION_ON
        Property name used to switch the user registry's encryption on and off.
        See Also:
        Constant Field Values

      • PROP_API_REMOTE_ON

        public static final java.lang.String PROP_API_REMOTE_ON
        Property name used to switch the TDI remote API on and off.
        See Also:
        Constant Field Values

      • PROP_TP_SERVER_ON

        public static final java.lang.String PROP_TP_SERVER_ON
        Property name used to switch the TDI TP Server on and off.
        See Also:
        Constant Field Values

      • PROP_REST_SERVER_ON

        public static final java.lang.String PROP_REST_SERVER_ON
        Property name used to switch the TDI REST Server API on and off.
        See Also:
        Constant Field Values

      • PROP_API_REMOTE_NAMING_PORT

        public static final java.lang.String PROP_API_REMOTE_NAMING_PORT
        Property name used to set the port the remote server API will listen on.
        See Also:
        Constant Field Values

      • PROP_API_REMOTE_SSL_ON

        public static final java.lang.String PROP_API_REMOTE_SSL_ON
        Property name used to switch the SSL for the remote API on and off.
        See Also:
        Constant Field Values

      • PROP_API_REMOTE_SSL_CLIENT_AUTH_ON

        public static final java.lang.String PROP_API_REMOTE_SSL_CLIENT_AUTH_ON
        Property name used to switch the client authentication on and off.
        See Also:
        Constant Field Values

      • PROP_API_REMOTE_NONSSL_HOSTS

        public static final java.lang.String PROP_API_REMOTE_NONSSL_HOSTS
        Property name used to specify the remote hosts that could use the remote API without SSL. The values could be separated by the characters " ", "," or ";"
        See Also:
        Constant Field Values

      • PROP_API_JMX_ON

        public static final java.lang.String PROP_API_JMX_ON
        Property name used to switch the local JMX interface on and off.
        See Also:
        Constant Field Values

      • PROP_API_JMX_REMOTE_ON

        public static final java.lang.String PROP_API_JMX_REMOTE_ON
        Property name used to switch the remote JMX interface on and off.
        See Also:
        Constant Field Values

      • PROP_TOMBSTONE_MANAGER_ON

        public static final java.lang.String PROP_TOMBSTONE_MANAGER_ON
        Property name used to switch the TombStone manager on and off.
        See Also:
        Constant Field Values

      • PROP_API_CUSTOM_AUTH

        public static final java.lang.String PROP_API_CUSTOM_AUTH
        Property name used to specify the script file path used for the custom authentication.
        See Also:
        Constant Field Values

      • PROP_API_CUSTOM_METHOD_INVOKE

        public static final java.lang.String PROP_API_CUSTOM_METHOD_INVOKE
        Property name used to switch the custom method invocation on and off.
        See Also:
        Constant Field Values

      • PROP_API_CUSTOM_AUTH_LDAP_CRITICAL

        public static final java.lang.String PROP_API_CUSTOM_AUTH_LDAP_CRITICAL
        Property name used to mark the LDAP authentication as critical or not. If its value is true then the error that occurred while authenticating will be thrown as exception, otherwise it will only be logged as an error and no exception will be thrown.
        See Also:
        Constant Field Values

      • PROP_API_CUSTOM_AUTH_LDAP_HOSTNAME

        public static final java.lang.String PROP_API_CUSTOM_AUTH_LDAP_HOSTNAME
        Property name that holds the host name of the LDAP server.
        See Also:
        Constant Field Values

      • PROP_API_CUSTOM_AUTH_LDAP_PORT

        public static final java.lang.String PROP_API_CUSTOM_AUTH_LDAP_PORT
        Property name that holds the port of the LDAP server.
        See Also:
        Constant Field Values

      • PROP_API_CUSTOM_AUTH_LDAP_USE_SSL

        public static final java.lang.String PROP_API_CUSTOM_AUTH_LDAP_USE_SSL
        Property name used to switch the usage of SSL on and off.
        See Also:
        Constant Field Values

      • PROP_API_CUSTOM_AUTH_LDAP_SEARCHBASE

        public static final java.lang.String PROP_API_CUSTOM_AUTH_LDAP_SEARCHBASE
        Property name used to specify the LDAP directory location where user searches will be performed. When this property is not specified user searches will not be performed.
        See Also:
        Constant Field Values

      • PROP_API_CUSTOM_AUTH_LDAP_ADMIN_DN

        public static final java.lang.String PROP_API_CUSTOM_AUTH_LDAP_ADMIN_DN
        Property name used to specify the LDAP Server administrator distinguished name that will be used for user searches. When this property is not specified anonymous bind will be used for user searches.
        See Also:
        Constant Field Values

      • PROP_API_CUSTOM_AUTH_LDAP_ADMIN_PASSWORD

        public static final java.lang.String PROP_API_CUSTOM_AUTH_LDAP_ADMIN_PASSWORD
        Property name used to specify the password for the LDAP Server administrator distinguished name
        See Also:
        Constant Field Values

      • PROP_API_CUSTOM_AUTH_LDAP_USER_ATTRIBUTE

        public static final java.lang.String PROP_API_CUSTOM_AUTH_LDAP_USER_ATTRIBUTE
        Property name used to specify the user id attribute to be used in searches. When this property is not specified user searches will not be performed.
        See Also:
        Constant Field Values

      • PROP_API_CUSTOM_AUTH_LDAP_GROUP_SUPPORT

        public static final java.lang.String PROP_API_CUSTOM_AUTH_LDAP_GROUP_SUPPORT
        Property name used to specify whether LDAP Group authentication is turned on. If it is set to 'true', the group membership of the authenticating user will be resolved and will be taken into account during authorization. If it is missing, the default value 'false' is used.
        See Also:
        Constant Field Values

      • PROP_API_CUSTOM_AUTH_LDAP_USERMEMBERSHIP_ATTRIBUTE

        public static final java.lang.String PROP_API_CUSTOM_AUTH_LDAP_USERMEMBERSHIP_ATTRIBUTE
        Property name used to specify the name of the attribute of a user in LDAP that contains a list of the groups of which the user is a member. It is taken into account only if PROP_API_CUSTOM_AUTH_LDAP_GROUP_SUPPORT is set to true.
        See Also:
        Constant Field Values

      • PROP_API_CUSTOM_AUTH_LDAP_USERMEMBERSHIP_ATTRIBUTE_CONTENT

        public static final java.lang.String PROP_API_CUSTOM_AUTH_LDAP_USERMEMBERSHIP_ATTRIBUTE_CONTENT
        Property name used to specify how groups are named in the membership attribute of a user. For example, if the user's membership attribute contains values, which correspond to the 'objectSID' attributes of groups, set this property to 'objectSID'. If the user's membership attribute contains distinguished names of groups, then set this property to 'dn'. The property is required in case PROP_API_CUSTOM_AUTH_LDAP_GROUP_SUPPORT is set to true.
        See Also:
        Constant Field Values

      • PROP_API_CUSTOM_AUTH_LDAP_GROUPNAME_ATTRIBUTE

        public static final java.lang.String PROP_API_CUSTOM_AUTH_LDAP_GROUPNAME_ATTRIBUTE
        Property name used to specify the name of a group's attribute in LDAP which corresponds to the way the group is named in the TDI User Registry. For example, if LDAP groups are addressed in the TDI registry by their common name, then set this property to 'cn'. If the User Registry contains the distinguished names of the groups, then set this property to 'dn'.
        See Also:
        Constant Field Values

      • PROP_API_CUSTOM_AUTH_LDAP_GROUP_SEARCHBASE

        public static final java.lang.String PROP_API_CUSTOM_AUTH_LDAP_GROUP_SEARCHBASE
        Property name used to specify the LDAP directory context, where groups will be searched. It is required only when LDAP group support is enabled.
        See Also:
        Constant Field Values

      • PROP_API_CUSTOM_AUTH_LDAP_BINARY_ATTRIBUTES

        public static final java.lang.String PROP_API_CUSTOM_AUTH_LDAP_BINARY_ATTRIBUTES
        Property name used to specify a list of space-separated attribute names. These attributes have non-string syntax.
        See Also:
        Constant Field Values

      • PROP_API_CUSTOM_AUTH_LDAP_VALUE

        public static final java.lang.String PROP_API_CUSTOM_AUTH_LDAP_VALUE
        Possible value of the property PROP_API_CUSTOM_AUTH specifying that the build-in LDAP authentication mechanism must be used.
        See Also:
        Constant Field Values

      • PROP_API_CUSTOM_AUTH_JAAS_VALUE

        public static final java.lang.String PROP_API_CUSTOM_AUTH_JAAS_VALUE
        Possible value of the property PROP_API_CUSTOM_AUTH specifying that the build-in JAAS authentication mechanism must be used.
        See Also:
        Constant Field Values

      • PROP_API_NOTIFICATION_SUPPRESSED_TYPES

        public static final java.lang.String PROP_API_NOTIFICATION_SUPPRESSED_TYPES
        Property name used to specify a list of Server notification types, which will be suppressed. Notifications of suppressed types will not be propagated by the notifications framework. The notification types in the list are separated by spaces. Wildcards may be included. Example: api.notification.suppress=di.al.* di.ci.start The above example will suppress all Assembly Line related notifications as well as notifications for starting a configuration instance. If the property is missing or is empty, no notifications will be suppressed.
        Since:
        7.0
        See Also:
        Constant Field Values

      • DEFAULT_REGISTRY_PORT

        public static final int DEFAULT_REGISTRY_PORT
        A constant containing the default port on which the RMI registry runs. This value will be used if the property with name PROP_API_REMOTE_NAMING_PORT is not set.
        See Also:
        Constant Field Values

      • REMOTE_SESSION_FACTORY_NAME

        public static final java.lang.String REMOTE_SESSION_FACTORY_NAME
        This constant contains the name of the used for looking up the remote object required for establishing a session with the remote TDI Server.
        See Also:
        Constant Field Values

    • Constructor Detail

      • APIEngine

        public APIEngine()

    • Method Detail

      • getResHash

        public static ResourceHash getResHash()
        Returns the object logging TMS messages.
        Returns:
        the static object that is responsible for transferring key strings to localized messages.

      • initialize

        public static void initialize()
                       throws DIException
        Initializes the Server API. It creates and initialize the Security Registry, the local Session Factory, the Process Factory, the Config Registry, the Event Notifier. Many of the initializations depends on the global properties values. Depending on the configuration API Authenticator and Tombstone Manager are also created.
        Throws:
        DIException - in case an initialization error occurs.

      • startThreadDetectingIPChange

        public static void startThreadDetectingIPChange​(long time)
        Starts a Thread monitoring the localhost address and calls initializeRemote to register the SessionFactory object anew when the local IP address changes.
        Parameters:
        time - - Number of milliseconds to sleep between each poll.

      • startTombstoneManager

        public static void startTombstoneManager()
                                  throws DIException
        Starts a TombstoneManager unless there is already one running.
        Throws:
        DIException

      • getLocalSessionFactory

        public static SessionFactory getLocalSessionFactory()
                                             throws DIException
        Gets the local SessionFactory created during the initialization of the Local Server API. This method is used by TDI components in order to gain access to the Local Server API.
        Returns:
        an instance object representing the local session factory for creating local sessions to the TDI Server.
        Throws:
        DIException - if the API Engine is not initialized or an error occurs while obtaining the session factory.

      • getLocalSession

        public static Session getLocalSession()
                               throws DIException
        Creates a local Session object using a local SessionFactory created during the initialization. This method is used by TDI components in order to gain access to the Local Server API.
        Returns:
        an instance object representing the local session with the TDI Server.
        Throws:
        DIException - if the API Engine is not initialized or an error occurs while obtaining the session.

      • getLocalSession

        public static Session getLocalSession​(java.lang.String aUserName,
                                      java.lang.String aPassword)
                               throws DIException
        Creates a local Session object using a local SessionFactory created during the initialization. This method is used when creation of the Session object requires authentication. The username and password parameters are used during the authentication process. This method is used by TDI components in order to gain access to the Local Server API.
        Parameters:
        aUserName - the username to use in the authentication process.
        aPassword - the password to use in the authentication process.
        Returns:
        an instance object representing the local session with the TDI Server.
        Throws:
        DIException - if the API Engine is not initialized or an error occurs while obtaining the session.

      • initializeRemote

        public static void initializeRemote()
                             throws DIException,
                                    java.rmi.RemoteException
        Initializes the Server API for remote access. It initializes the RMI Registry and registers the Remote Session Factory that is used to access the Server API.
        Throws:
        DIException - if the initialize() was not called yet or the call did not succeed.
        Or other initialization/authentication error occurs.
        java.rmi.RemoteException - if an error occurs.

      • initializeTPServer

        public static void initializeTPServer()
                               throws DIException
        Initializes the TP Server for remote access. This initializes the OSGi Framework and the TP Service application that is used to provide a REST access to the TDI Connector components.
        Throws:
        DIException - if the initialize() was not called yet or the call did not succeed.
        Or other initialization/authentication error occurs.
        Since:
        7.1

      • initializeRestServer

        public static void initializeRestServer()
                                 throws DIException
        Initializes the TP Server for remote access. This initializes the OSGi Framework and the TP Service application that is used to provide a REST access to the TDI Connector components.
        Throws:
        DIException - if the initialize() was not called yet or the call did not succeed.
        Or other initialization/authentication error occurs.
        Since:
        7.2

      • configInstanceStarted

        public static void configInstanceStarted​(RSInterface aConfigInstance)
                                  throws DIException
        This is a notification method, that notifies the engine that the specified Config Instance has been started. The API Engine updates the Process Registry and sends a notification event. This method is for internal use by the Server API and should not be used elsewhere.
        Parameters:
        aConfigInstance - the started config instance object.
        Throws:
        DIException - if an error while broadcasting the notification occurs.

      • configInstanceStopped

        public static void configInstanceStopped​(RSInterface aConfigInstance)
                                  throws DIException
        This is a notification method, that notifies the engine that the specified Config Instance has been stopped. The API Engine updates the Process Registry and sends a notification event. This method is for internal use by the Server API and should not be used elsewhere.
        Parameters:
        aConfigInstance - the stoped config instance object.
        Throws:
        DIException - if an error while broadcasting the notification occurs.

      • assemblyLineStarted

        public static void assemblyLineStarted​(AssemblyLine aAssemblyLine)
                                throws DIException
        This is a notification method, that notifies the engine that the specified Assembly Line has been started. The API Engine updates the Process Registry and sends a notification event. This method is for internal use by the Server API and should not be used elsewhere.
        Parameters:
        aAssemblyLine - the started AssemblyLine instance.
        Throws:
        DIException

      • assemblyLineTerminated

        public static void assemblyLineTerminated​(AssemblyLine aAssemblyLine)
        This is a notification method, that notifies the engine that the specified Assembly Line has been terminated. The API Engine updates the Process Registry and sends a notification event. This method is for internal use by the Server API and should not be used elsewhere.
        Parameters:
        aAssemblyLine - the stopped AssemblyLine instance.

      • serverStopped

        public static void serverStopped​(long aServerStarted)
                          throws DIException
        This is a notification method, that notifies the engine that server has been stopped. The only parameter specifies the time the server has been started. The API Engine sends a notification event. This method is for internal use by the Server API and should not be used elsewhere.
        Parameters:
        aServerStarted - the time the server was stopped.
        Throws:
        DIException - if an error while broadcasting the notification occurs.

      • getConfigInstances

        public static java.util.Vector<RSInterface> getConfigInstances()
                                                        throws DIException
        Returns a vector containing all configuration instances currently started.
        Returns:
        the list with the running config instance objects.
        Throws:
        DIException - if the API Engine is not initialized correctly or error occurs while retrieving the list.

      • getConfigInstanceIDs

        public static java.util.List<java.lang.String> getConfigInstanceIDs()
                                                             throws DIException
        Returns:
        a list containing the IDs of all the configuration instances currently started.
        Throws:
        DIException - if the API Engine is not initialized correctly or error occurs while retrieving the list.

      • getConfigInstance

        public static RSInterface getConfigInstance​(java.lang.String configId)
                                     throws DIException
        Retrieves config instance.
        Parameters:
        configId - configuration instance id
        Returns:
        configuration instance with the specified config id, or null if there is no such instance
        Throws:
        DIException - if the Server API is not initialized
        Since:
        7.0

      • getAssemblyLines

        public static java.util.Hashtable<RSInterface,​java.util.Vector<AssemblyLine>> getAssemblyLines()
                                                                                              throws DIException
        Returns a hashtable whose key elements are the Configuration Instances currently started, and the values are vectors containing all Assembly Lines currently started in the corresponding Configuration Instance.
        Returns:
        the map between config instances and their AssemblyLines.
        Throws:
        DIException - if the Server API is not initialized, or an error occurs.

      • getIdentity

        public static Identity getIdentity​(java.lang.String aUserId)
                            throws DIException
        Returns the Identity object from the Security Registry corresponding to the user id passes as parameter.
        Parameters:
        aUserId - the user identifier used when obtaining the Identity
        Returns:
        the Identity object
        Throws:
        DIException - if the API Engine is not initialized properly.

      • addEventListener

        public static void addEventListener​(DIEventListener aListener,
                                    java.lang.String aTypeFilter,
                                    java.lang.String aIdFilter)
                             throws DIException
        Adds a new event listener.
        Parameters:
        aListener - this is the concrete object that implements the DIEventListener interface.
        aTypeFilter - a composite filter that matches event type
        aIdFilter - an atomic filter that matches event id
        Throws:
        DIException - if the API Engine is not initialized properly, or other error occurs.

      • removeEventListener

        public static boolean removeEventListener​(DIEventListener aListener)
                                   throws DIException
        Removes existing event listener.
        Parameters:
        aListener - the listener to remove.
        Returns:
        whether the listener was unregistered successfully
        Throws:
        DIException - if the API Engine is not initialized properly, or other error occurs.

      • isDebugEnabled

        public static boolean isDebugEnabled()
        Returns "true" if debug is enabled and "false" otherwise.
        Returns:
        true if the debug is enabled, false otherwise.

      • logDebug

        public static void logDebug​(java.lang.String aMessage)
        Logs a message using the DEBUG log level.
        Parameters:
        aMessage - the message to log.

      • logInfo

        public static void logInfo​(java.lang.String aMessage)
        Logs a message using the INFO log level.
        Parameters:
        aMessage - the message to log.

      • logError

        public static void logError​(java.lang.String aMessage)
        Logs a message using the ERROR log level.
        Parameters:
        aMessage - the message to log.

      • logError

        public static void logError​(java.lang.String message,
                            java.lang.Throwable t)
        Logs a message using the ERROR log level.
        Parameters:
        message - the message to log.
        t - Error object.

      • logWarn

        public static void logWarn​(java.lang.String aMessage)
        Logs a message using the WARN log level.
        Parameters:
        aMessage - the message to log.

      • logFatal

        public static void logFatal​(java.lang.String aMessage)
        Logs a message using the FATAL log level.
        Parameters:
        aMessage - the message to log.

      • logErrorAndThrowException

        public static void logErrorAndThrowException​(java.lang.String aErrorMsg)
                                      throws DIException
        Logs a message using the ERROR log level and then throws a DIException using the same message.
        Parameters:
        aErrorMsg - the error message to output wit the exception.
        Throws:
        DIException - with the specified error message.

      • logErrorAndThrowException

        public static void logErrorAndThrowException​(java.lang.String aErrorMsg,
                                             java.lang.Throwable e)
                                      throws DIException
        Logs a message composed from the message passes as parameter and the message in the Throwable object. The new message is logged using the ERROR log level and then a DIException is thrown containing that message.
        Parameters:
        aErrorMsg - the error message
        e - the Throwable object
        Throws:
        DIException - with the specified error message.

      • getNamingPort

        public static int getNamingPort()
        Retrieves port number.
        Returns:
        the port number used for the connection to the RMI Registry.

      • isSSLon

        public static boolean isSSLon()
        Checks if SSL is on.
        Returns:
        true if SSL has been turned on. Otherwise returns false.

      • isSSLClientAuthenticationOn

        public static boolean isSSLClientAuthenticationOn()
        Checks if SSL client authentication is on.
        Returns:
        true if SSL Client Authentication is on. Otherwise returns false.

      • getServerSF

        public static java.rmi.server.RMIServerSocketFactory getServerSF()
        Retrieves server socket factory.
        Returns:
        the server socket factory used for establishing remote connection with the TDI Server over RMI. This will return null if the remote api is turned off.

      • getClientSF

        public static java.rmi.server.RMIClientSocketFactory getClientSF()
        Retrieves the client socket factory used for establishing remote connection.
        Returns:
        the client socket factory used for establishing remote connection with the TDI Server over RMI. This will return null if the remote api is turned off.

      • initRMIRegistry

        public static java.rmi.registry.Registry initRMIRegistry()
                                                  throws DIException,
                                                         java.rmi.RemoteException
        Creates and initializes the RMI Registry.
        Returns:
        the RMI Registry in use.
        Throws:
        DIException - if an error occurs.
        java.rmi.RemoteException - if an error occurs.

      • getLDAPAuthenticator

        public static LDAPAuthentication getLDAPAuthenticator()
        Retrieves LDAP authenticator.
        Returns:
        the LDAP Authenticator, might be null.

      • isLDAPAuthenticationEnabled

        public static boolean isLDAPAuthenticationEnabled()
        Checks if LDAP authentication is enabled.
        Returns:
        true if LDAP Authentication is enabled, false otherwise.

      • getMethodInvokeEnabled

        public static boolean getMethodInvokeEnabled()
        If method invocation is enabled, then this method returns true.
        Returns:
        true if method invocation is enabled and false otherwise.

      • getConfigId

        public static java.lang.String getConfigId​(RSInterface configInstance)
        Obtain the configuration instance id for a running configuration instance.
        Parameters:
        configInstance - A running configuration instance.
        Returns:
        the configuration id, which corresponds to the specified configuration instance
        Since:
        TDI 6.1.1

      • getJAASAuthenticator

        public static JAASAuthentication getJAASAuthenticator()
        Getter for the member variable mJAASAuthenticator
        Returns:
        JAASAuthentication object

      • isJAASAuthenticationEnabled

        public static boolean isJAASAuthenticationEnabled()
        Checks if the member variable mJAASAuthenticator is initialized
        Returns:
        true if JAAS Authentication is enabled

      • sendNotification

        public static void sendNotification​(java.lang.String type,
                                    java.lang.String id,
                                    java.lang.Object data,
                                    java.lang.String configInstanceId)
                             throws DIException
        Sends a notification event using the API Engine's Event Notifier. Initially introduced to send audit Notifications.
        Parameters:
        type - Type of the notification event.
        id - ID of the notification event.
        data - An Java object containing additional useful information. By audit notification this object is of type com.ibm.di.Entry containing as Attributes specific audit information.
        configInstanceId - The ConfigInstance ID, which the notification is bound to.
        Throws:
        DIException - If an error occurs while the event is transmitted.
        Since:
        7.0

      • sendNotification

        public static void sendNotification​(DIEvent event)
                             throws DIException
        Sends a notification event using the API Engine's Event Notifier. Initially introduced to send audit Notifications.
        Parameters:
        event - The event to publish
        Throws:
        DIException - If an error occurs while the event is transmitted.
        Since:
        7.1.1