com.ibm.di.server
Class RS

java.lang.Object
  extended by java.lang.Thread
      extended by com.ibm.di.server.RS
All Implemented Interfaces:
AssemblyLine.AssemblyLineListener, Listenable<ConfigInstanceListener>, RSInterface, Runnable

public class RS
extends Thread
implements RSInterface, AssemblyLine.AssemblyLineListener, Listenable<ConfigInstanceListener>

This is the main class for the TDI Server, and represents the primary thread from which all others are launched, including AssemblyLines and Server mode listeners. The pre-registered script variable main gives you JavaScript access to the server-level methods available in this class. For example, if you want to launch a new AssemblyLine then you use the main variable to do so:

 // Start my AL
 var al = main.startAL("myAssemblyLine");
 // Wait for the AL to complete 
 al.join();
 
Just like com.ibm.di.server.AssemblyLine (the task variable in JavaScript), RS also provides a logmsg() method. Note also that in order to load a Connector Interface, like JDBC or LDAP Connector, you use the loadConnector() of the AssemblyLine class:
 task.loadConnector(connectorConfig)
 
. To get the Connector Config, use the getConnector() method in RS. The same goes for Parsers and Function components. RS also provides the commandLineParam() method for retrieving commandline arguments, including the user-defined ones (-0 through -9), that were specified when the TDI Server was started.


Nested Class Summary
static interface RS.ConfigInstanceNamingPolicy
          A policy which defines how configuration instances are named.
static class RS.DefaultConfigInstanceNamingPolicy
          The default naming policy.
 
Nested classes/interfaces inherited from class java.lang.Thread
Thread.State, Thread.UncaughtExceptionHandler
 
Field Summary
static String CL_AL_DEBUG
          Command line switch - B See the parameters' usage.
static String CL_CONFIG
          Command line switch - c See the parameters' usage.
static String CL_CONFIG_DRIVER
          Command line switch - Y See the parameters' usage.
static String CL_CONFIG_ENCODING
          Command line switch - n See the parameters' usage.
static String CL_CONFIG_STDIN
          Command line switch - S See the parameters' usage.
static String CL_CREATE_SOLDIR
          Command line switch - g See the parameter's usage.
static String CL_DEBUG_OPTIONS
          Command line switch - b See the parameters' usage.
static String CL_DEBUG_PORT
          Command line switch - Q See the parameters' usage.
static String CL_DISABLE_REMOTE_API
          Command line switch - R See the parameters' usage.
static String CL_DUMP_PERFPROPS
          Command line switch - T See the parameters' usage.
static String CL_DUMP_PROPS
          Command line switch - p See the parameters' usage.
static String CL_EXECUTE_SCRIPT
          Command line switch - x See the parameters' usage.
static String CL_EXT_PROP_FILE
          Command line switch - f See the parameters' usage.
static String CL_IGNORE_GLOBAL_PROPERTIES
          Command line switch - i

if this option is specified, the server will not read global.properties; solution.properties will still be read if present
static String CL_INTERNAL_ADD_LISTENER
          This is not a command line option but an internal parameter that lets you specify an additional config instance listener.
static String CL_INTERNAL_CONFIG_AS_STRING
          This is not a command line option but an internal parameter that lets you start a Config Instance by providing the configuration XML as a string.
static String CL_INTERNAL_CONFIG_NSTANCE_NAME
          This is not a command line option but an internal parameter that lets you start a Config Instance with a name different than the config file name.
static String CL_LOGFILE
          Command line switch - l See the parameters' usage.
static String CL_NO_AUTOSTART
          Command line switch - D See the parameters' usage.
static String CL_NO_TERMINATE
          Command line switch - W See the parameters' usage.
static String CL_PASSWORD
          Command line switch - P See the parameters' usage.
static String CL_RUN_DAEMON
          Command line switch - d See the parameters' usage.
static String CL_RUN_MODE
          Command line switch - q See the parameters' usage.
static String CL_SECURE_MODE
          Command line switch - e See the parameters' usage.
static String CL_SIMULATION_MODE
          Command line switch - M See the parameters' usage.
static String CL_START_AL
          Command line switch - r See the parameters' usage.
static String CL_USAGE
          Command line switch - ? See the parameters' usage.
static String CL_VERSION_INFO
          Command line switch - v See the parameters' usage.
static String CL_WAIT
          Command line switch - w See the parameters' usage.
static int EXIT_CODE_REST_FAILED
          The exit code returned when REST fails.
static RS gRS
          Global static reference to the master RS object (non-threaded)
static MetamergeConfig gSysConfig
          This is the templates configuration file loaded from the rs.jar file
 long mmReloaded
          Time when the reload() method was called.
 long mmServerStarted
          Time when the master RS started
 long mmStarted
          Time when the threaded RS started
 Hashtable<String,Object> params
          This table holds startup parameters.
static String PROP_CONFIG_ENCODING
          System property that specifies the encoding to be used when reading/writing configuration files.
static String PROP_SECURE_MODE
          System property that specifies whether the Server is run in secure mode.
static String PROPERTY_JVM_SHUTDOWN_HOOK
          The server will look for a property with this name when registering a shutdown hook.
static String PROTECT_PREFIX
          This is the prefix of a property in the global.properties or solution.properties files.
static String PROTECT_VAL_PREFIX
          This is the prefix of the value of a protected property in the global.properties or solution.properties files.
 
Fields inherited from class java.lang.Thread
MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY
 
Constructor Summary
  RS()
          Default constructor
protected RS(String[] args)
           
protected RS(ThreadGroup group, String name)
           
 
Method Summary
 void addListener(ConfigInstanceListener listener)
           This method is for internal use only.
 void assemblyLineCycleEnded(AssemblyLine al, Entry work)
          An AssemblyLine cycle (iteration) is complete.
 void assemblyLineTerminated(AssemblyLine al)
          The AssemblyLine terminated.
static void checkLUM()
          This function checks if a valid license to run the application exists in the nodelock file.
 void checkTask(String name)
          Check for existence of "AssemblyLine" name, or throw an exception
 String commandLineParam(String param)
          Returns the value for a command line parameter
static RS createConfigInstance(String groupName, Hashtable<String,Object> params)
          Create a new config instance but do not start it.
 void dump(Object o)
          Dumps the class and contents of an object to the log file.
 void dumpEntry(Entry e)
          Dumps the contents of an Entry to the log file.
static void encryptPropertiesfile(String path, Log log)
          Loads the properties from the specified file and sets them as system properties.
 AttributeMapConfig getAttributeMap(String name)
          Returns the the "Attribute Map" for a named connector
 String getCommandLineConfigId()
           
static RS.ConfigInstanceNamingPolicy getConfigInstanceNamingPolicy()
           
 String getConfigPath()
          This method returns the current configuration file path
 Object getConfiguration(String key)
          Returns the entire table or a sub-section of the configuration file.
 ConnectorConfig getConnector(String name)
          Returns the "Connector" entry for name
 ConnectorPool getConnectorPool(String connName)
           
 String[] getConnectorPoolNames()
           
 Throwable getExitError()
          Returns the exit error of the instance
 int getExitStatus()
          Gets the exit code of the instance
 FunctionConfig getFunction(String name)
          Returns the "FunctionConfig" entry for name
 LibraryConfig getLibraries()
          Returns all "Libraries"
 Object getLibrary(String name)
          Returns the the "Java Library" entry for name
static com.ibm.it.rome.xslm.ITLMApplicationLicense getLicense()
          Function to retrieve license
 Log getLog()
          Returns the Log for the current instance
 String getLogDirectory(Object owner)
          This method returns the default directory path where log files are stored.
 MetamergeConfig getMetamergeConfig()
          Returns the config object for this instance.
 String getNullBehavior()
          Return the null behavior string from the System.props
 String getNullBehaviorValue()
          Gets the null behavior value.
 String getNullDefinition()
          Return the null definition string from the System.props
 String getNullDefinitionValue()
          Gets the null definition value.
 ParserConfig getParser(String name)
          Returns the the "Parser" entry for name
static ReconnectRuleEngine getReconnectRuleEngine()
          Gets the reconnect engine.
 ScriptConfig getScript(String name)
          Returns the the "Script Library" entry for name
static RS getServer()
          Returns the RS instance associated with the current ThreadGroup.
static RS getServer(String name)
          Returns a named RS instance
static RS getServerByConfig(MetamergeConfig aConfig)
          Gets the server instance that uses the specified by the aConfig configuration.
 ServerSocketFactory getServerSocketFactory(boolean useSSL)
          Gets a Server Socket Factory for creating Server Sockets.
 String getSysProp(String name)
          Returns the value of a system property.
 AssemblyLineConfig getTask(String name)
          Returns the "AssemblyLine" entry
 Object invokeServerHook(String name, Object caller, Object userInfo)
          Invokes a server hook.
static boolean isSecured()
          Check if the server is running in secured mode.
 void limitNumberOfThreads()
          This method is called by the startAL(String, Object, LogInterface) method to check whether a limit of the maximum running threads exists.
 void logerror(String msg)
          Writes an error message to the system log file.
 void logerror(String msg, Throwable error)
          Prints a message to the log, marked as an Error.
 void logmsg(String msg)
          Writes a message to the system log file.
 void logmsg(String level, String msg)
          This method logs a message with the specified level to the log.
static void main(String[] args)
          The main methods creates the Log object and kicks off the main thread.
 void persistConfiguration()
          This method saves the current configuration to disk.
static void prepareSolutionDirectory(Log log)
          Prepare the solution directory (working directory) by ensuring solution.properties is present.
static void registerServer(RS server)
          Registers the config object to be associated with the current ThreadGroup
static void releaseLicense(com.ibm.it.rome.xslm.ITLMApplicationLicense license)
          Function to release license
 void reload()
          This method reloads the configuration file.
 void removeListener(ConfigInstanceListener listener)
           This method is for internal use only.
 AssemblyLine restartAL(String assemblyLine, String checkpointID)
          Deprecated. 
 void run()
          Thread main
 int runServer()
          Used when starting the server instance.
static void setConfigInstanceNamingPolicy(RS.ConfigInstanceNamingPolicy newPolicy)
           
 void setConfigPath(String path)
          This method sets the current configuration file path.
 void setConfiguration(MetamergeConfig config)
          Sets the configuration that will be used by the server.
static void setGlobalProperties()
          This method loads the global.properties/solution.properties and parses their content.
 void setMetamergeConfig(MetamergeConfig config)
          Sets the given configuration to this instance.
static boolean shouldCreateSolutionProps()
          Checks if the solution.properties file should be created.
static void showLogHeader(Log log)
          This method writes a log header to the Log object.
static void shutdownAllServers(int exitCode, boolean master, boolean async)
          This method shuts down all Config Instances.
 void shutdownServer()
          Raise the shutdown request flag and set the exit code to 0.
 void shutdownServer(int aExitCode)
          Raise the shutdown request flag and specify an exit code.
 void shutdownServer(int exitCode, boolean async)
          Raise the shutdown request flag.
 AssemblyLine startAL(String assemblyLine)
          Start a named AssemblyLine.
 AssemblyLine startAL(String assemblyLine, Connector connector, Entry work)
          Start named AssemblyLine providing an initial work entry and a connector
 AssemblyLine startAL(String assemblyLine, int runMode)
          Start named AssemblyLine by providing the run mode.
 AssemblyLine startAL(String assemblyLine, Object io)
          Start a named AssemblyLine providing various objects.
 AssemblyLine startAL(String assemblyLine, Object io, LogInterface logAppender)
          Start named AssemblyLine providing a parameter
 AssemblyLine startAL(TaskCallBlock tcb)
          Start the AssemblyLine named in the TCB
 AssemblyLine startALDebug(String assemblyLine, int port)
          Start named AssemblyLine in debug mode.
static RS startServer(String[] args)
          Starts server using null for the unique name of the server instance and command line parameters parsed to params table.
static RS startServer(String groupName, Hashtable<String,Object> params)
          Starts a new server instance.
static RS startServer(String config, String assemblyLines)
          Starts server using null for the unique name of the server instance.
static RS startServer(String config, String assemblyLines, String passw)
          Starts server using null for the unique name of the server instance.
static RS startServer(String config, String assemblyLines, String passw, boolean dontTerminate)
          Starts server using null for the unique name of the server instance.
static RS startServer(String config, String assemblyLines, String passw, boolean dontTerminate, Hashtable<String,Object> userParams)
          Starts server using null for the unique name of the server instance.
static int stopAL(String name)
          Stop named AssemblyLine in all Config Instances.
static void stopAssemblyLines(String name, int hashCode, boolean recurse, boolean async, RS rs)
          Stops specified running AssemblyLines.
static void stopChildAssemblyLines(AssemblyLine al, boolean async)
          Recursively stop all children of one AssemblyLine.
static void unregisterServer(RS server)
          Registers the config object to be associated with the current ThreadGroup
 boolean waitForInitializationToComplete(long milliseconds)
           This method is for internal use only.
 
Methods inherited from class java.lang.Thread
activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.ibm.di.server.RSInterface
getName
 

Field Detail

CL_USAGE

public static final String CL_USAGE
Command line switch - ? See the parameters' usage.

See Also:
Constant Field Values

CL_START_AL

public static final String CL_START_AL
Command line switch - r See the parameters' usage.

See Also:
Constant Field Values

CL_NO_AUTOSTART

public static final String CL_NO_AUTOSTART
Command line switch - D See the parameters' usage.

See Also:
Constant Field Values

CL_CONFIG

public static final String CL_CONFIG
Command line switch - c See the parameters' usage.

See Also:
Constant Field Values

CL_WAIT

public static final String CL_WAIT
Command line switch - w See the parameters' usage.

See Also:
Constant Field Values

CL_PASSWORD

public static final String CL_PASSWORD
Command line switch - P See the parameters' usage.

See Also:
Constant Field Values

CL_DUMP_PROPS

public static final String CL_DUMP_PROPS
Command line switch - p See the parameters' usage.

See Also:
Constant Field Values

CL_VERSION_INFO

public static final String CL_VERSION_INFO
Command line switch - v See the parameters' usage.

See Also:
Constant Field Values

CL_EXECUTE_SCRIPT

public static final String CL_EXECUTE_SCRIPT
Command line switch - x See the parameters' usage.

See Also:
Constant Field Values

CL_RUN_DAEMON

public static final String CL_RUN_DAEMON
Command line switch - d See the parameters' usage.

See Also:
Constant Field Values

CL_SECURE_MODE

public static final String CL_SECURE_MODE
Command line switch - e See the parameters' usage.

See Also:
Constant Field Values

CL_EXT_PROP_FILE

public static final String CL_EXT_PROP_FILE
Command line switch - f See the parameters' usage.

See Also:
Constant Field Values

CL_DEBUG_OPTIONS

public static final String CL_DEBUG_OPTIONS
Command line switch - b See the parameters' usage.

See Also:
Constant Field Values

CL_AL_DEBUG

public static final String CL_AL_DEBUG
Command line switch - B See the parameters' usage.

See Also:
Constant Field Values

CL_DEBUG_PORT

public static final String CL_DEBUG_PORT
Command line switch - Q See the parameters' usage.

See Also:
Constant Field Values

CL_CONFIG_STDIN

public static final String CL_CONFIG_STDIN
Command line switch - S See the parameters' usage.

See Also:
Constant Field Values

CL_RUN_MODE

public static final String CL_RUN_MODE
Command line switch - q See the parameters' usage.

See Also:
Constant Field Values

CL_CONFIG_DRIVER

public static final String CL_CONFIG_DRIVER
Command line switch - Y See the parameters' usage.

See Also:
Constant Field Values

CL_LOGFILE

public static final String CL_LOGFILE
Command line switch - l See the parameters' usage.

See Also:
Constant Field Values

CL_NO_TERMINATE

public static final String CL_NO_TERMINATE
Command line switch - W See the parameters' usage.

See Also:
Constant Field Values

CL_DISABLE_REMOTE_API

public static final String CL_DISABLE_REMOTE_API
Command line switch - R See the parameters' usage.

See Also:
Constant Field Values

CL_CONFIG_ENCODING

public static final String CL_CONFIG_ENCODING
Command line switch - n See the parameters' usage.

See Also:
Constant Field Values

CL_DUMP_PERFPROPS

public static final String CL_DUMP_PERFPROPS
Command line switch - T See the parameters' usage.

See Also:
Constant Field Values

CL_SIMULATION_MODE

public static final String CL_SIMULATION_MODE
Command line switch - M See the parameters' usage.

See Also:
Constant Field Values

CL_CREATE_SOLDIR

public static final String CL_CREATE_SOLDIR
Command line switch - g See the parameter's usage.

See Also:
Constant Field Values

CL_IGNORE_GLOBAL_PROPERTIES

public static final String CL_IGNORE_GLOBAL_PROPERTIES
Command line switch - i

if this option is specified, the server will not read global.properties; solution.properties will still be read if present

See Also:
Constant Field Values

CL_INTERNAL_CONFIG_NSTANCE_NAME

public static final String CL_INTERNAL_CONFIG_NSTANCE_NAME
This is not a command line option but an internal parameter that lets you start a Config Instance with a name different than the config file name. It is used for starting temporary Config Instances on load for editing.

See Also:
Constant Field Values

CL_INTERNAL_CONFIG_AS_STRING

public static final String CL_INTERNAL_CONFIG_AS_STRING
This is not a command line option but an internal parameter that lets you start a Config Instance by providing the configuration XML as a string.

See Also:
Constant Field Values

CL_INTERNAL_ADD_LISTENER

public static final String CL_INTERNAL_ADD_LISTENER
This is not a command line option but an internal parameter that lets you specify an additional config instance listener. The listener must implement the com.ibm.di.server.ConfigInstanceListener interface.

See Also:
Constant Field Values

PROPERTY_JVM_SHUTDOWN_HOOK

public static final String PROPERTY_JVM_SHUTDOWN_HOOK
The server will look for a property with this name when registering a shutdown hook. A System property with that name could hold a path the an executable file which will be executed when the server shuts down.

See Also:
Constant Field Values

PROTECT_PREFIX

public static final String PROTECT_PREFIX
This is the prefix of a property in the global.properties or solution.properties files.

See Also:
Constant Field Values

PROTECT_VAL_PREFIX

public static final String PROTECT_VAL_PREFIX
This is the prefix of the value of a protected property in the global.properties or solution.properties files.

See Also:
Constant Field Values

PROP_CONFIG_ENCODING

public static final String PROP_CONFIG_ENCODING
System property that specifies the encoding to be used when reading/writing configuration files.

See Also:
Constant Field Values

PROP_SECURE_MODE

public static final String PROP_SECURE_MODE
System property that specifies whether the Server is run in secure mode.

See Also:
Constant Field Values

EXIT_CODE_REST_FAILED

public static final int EXIT_CODE_REST_FAILED
The exit code returned when REST fails.

See Also:
Constant Field Values

gSysConfig

public static MetamergeConfig gSysConfig
This is the templates configuration file loaded from the rs.jar file


params

public Hashtable<String,Object> params
This table holds startup parameters.


mmServerStarted

public long mmServerStarted
Time when the master RS started


mmStarted

public long mmStarted
Time when the threaded RS started


mmReloaded

public long mmReloaded
Time when the reload() method was called.


gRS

public static RS gRS
Global static reference to the master RS object (non-threaded)

Constructor Detail

RS

public RS()
Default constructor


RS

protected RS(String[] args)

RS

protected RS(ThreadGroup group,
             String name)
Method Detail

releaseLicense

public static void releaseLicense(com.ibm.it.rome.xslm.ITLMApplicationLicense license)
Function to release license

Parameters:
license - the license object to release.

getLicense

public static com.ibm.it.rome.xslm.ITLMApplicationLicense getLicense()
                                                              throws Exception
Function to retrieve license

Returns:
ITLMApplicationLicense object representing the retrieved license.
Throws:
Exception - if the ITLM toolkit initialization fails.

main

public static void main(String[] args)
                 throws Exception
The main methods creates the Log object and kicks off the main thread.

Parameters:
args - an array of the command line arguments
Throws:
Exception - if error while preparing the solution directory occurs.

isSecured

public static boolean isSecured()
Check if the server is running in secured mode.

Returns:
true if the server is in secure mode, false otherwise.

getReconnectRuleEngine

public static ReconnectRuleEngine getReconnectRuleEngine()
Gets the reconnect engine.

Returns:
ReconnectRuleEngine object responsible for handling errors.

setConfiguration

public void setConfiguration(MetamergeConfig config)
Sets the configuration that will be used by the server.

Parameters:
config - the configuration object.

getConfiguration

public Object getConfiguration(String key)
Returns the entire table or a sub-section of the configuration file.

Specified by:
getConfiguration in interface RSInterface
Parameters:
key - Name of subsection or null
Returns:
The entire table (name == null) or section in table

getLibrary

public Object getLibrary(String name)
Returns the the "Java Library" entry for name

Specified by:
getLibrary in interface RSInterface
Parameters:
name - The java library name
Returns:
The section for name

getFunction

public FunctionConfig getFunction(String name)
                           throws Exception
Returns the "FunctionConfig" entry for name

Specified by:
getFunction in interface RSInterface
Parameters:
name - The name of the function
Returns:
The function config object
Throws:
Exception - if a lookup error occurs.

getLibraries

public LibraryConfig getLibraries()
Returns all "Libraries"

Specified by:
getLibraries in interface RSInterface
Returns:
The entire list of Libraries

getScript

public ScriptConfig getScript(String name)
Returns the the "Script Library" entry for name

Specified by:
getScript in interface RSInterface
Parameters:
name - The script library name
Returns:
The section for name

getConnector

public ConnectorConfig getConnector(String name)
Returns the "Connector" entry for name

Specified by:
getConnector in interface RSInterface
Parameters:
name - The connector name
Returns:
The section from either the file configuration or the templates configuration

getParser

public ParserConfig getParser(String name)
Returns the the "Parser" entry for name

Specified by:
getParser in interface RSInterface
Parameters:
name - The parser name
Returns:
The section either the file configuration or the templates configuration

getAttributeMap

public AttributeMapConfig getAttributeMap(String name)
Returns the the "Attribute Map" for a named connector

Specified by:
getAttributeMap in interface RSInterface
Parameters:
name - The connector name
Returns:
The attribute map section

getTask

public AssemblyLineConfig getTask(String name)
Returns the "AssemblyLine" entry

Specified by:
getTask in interface RSInterface
Parameters:
name - The AssemblyLine name
Returns:
The configuration for the AssemblyLine

checkTask

public void checkTask(String name)
               throws Exception
Check for existence of "AssemblyLine" name, or throw an exception

Parameters:
name - The AssemblyLine name
Throws:
Exception - in case the AssemblyLine referred by the provided name could not be found.

getSysProp

public String getSysProp(String name)
Returns the value of a system property. The system properties include all Java system properties as well as TDI's own properties.

Specified by:
getSysProp in interface RSInterface
Parameters:
name - The system property name, or null if there is no property with that name
Returns:
The value for the property

runServer

public int runServer()
Used when starting the server instance.

Returns:
the exit code the server ended with.

restartAL

@Deprecated
public AssemblyLine restartAL(String assemblyLine,
                                         String checkpointID)
                       throws Exception
Deprecated. 

Restart the AssemblyLine given by the parameter.

Specified by:
restartAL in interface RSInterface
Parameters:
assemblyLine - The name identifying the AssemblyLine to start
checkpointID - The checkpoint identifier
Returns:
The AssemblyLine Thread object
Throws:
Exception - if assemblyLine is an unknown AssemblyLine or if any of the connectors cannot be re-initialized

startAL

public AssemblyLine startAL(String assemblyLine)
                     throws Exception
Start a named AssemblyLine. See also the introduction to AssemblyLines.

Example:

 var al = main.startAL("ALName");
 var tcb = al.getTCB();
 
 main.logmsg("AL run mode: " + tcb.getRunMode());
 main.logmsg("AL operation: " + tcb.getALOperation());
 main.logmsg("AL settings: ");
 main.dumpEntry(tcb.getALSettings());
 

Specified by:
startAL in interface RSInterface
Parameters:
assemblyLine - The name identifying the AssemblyLine to start
Returns:
The AssemblyLine Thread object
Throws:
Exception - if assemblyLine is an unknown AssemblyLine or if any of the connectors cannot be initialized

startAL

public AssemblyLine startAL(String assemblyLine,
                            int runMode)
                     throws Exception
Start named AssemblyLine by providing the run mode.

Parameters:
assemblyLine - Name of AssemblyLine to start
runMode - the run mode in which the AssemblyLine should start
Returns:
The AssemblyLine Thread object
Throws:
Exception - in case the AssemblyLine initialization fails.
See Also:
AssemblyLine.RUNMODE_I_NORMAL, AssemblyLine.RUNMODE_I_RECORD, AssemblyLine.RUNMODE_I_PLAYBACK, AssemblyLine.RUNMODE_I_MANUAL

startALDebug

public AssemblyLine startALDebug(String assemblyLine,
                                 int port)
                          throws Exception
Start named AssemblyLine in debug mode.

Parameters:
assemblyLine - Name of AssemblyLine to start
port - the port which the debug console will connect to.
Returns:
The AssemblyLine Thread object
Throws:
Exception - if the AssemblyLine initialization fails.

startAL

public AssemblyLine startAL(String assemblyLine,
                            Connector connector,
                            Entry work)
                     throws Exception
Start named AssemblyLine providing an initial work entry and a connector

Example:

 var iwe = new com.ibm.di.entry.Entry();
 iwe.setAttribute("linenumber", "1");
 iwe.setAttribute("line", "Some line with text");
 
 var c = main.getConnector("ConnectorName");
 var al = main.startAL("ALName", c, iwe);
 var tcb = al.getTCB();
 
 main.logmsg("AL run mode: " + tcb.getRunMode());
 main.logmsg("AL initial work entry: ");
 main.dumpEntry(tcb.getInitialWorkEntry());
 

Specified by:
startAL in interface RSInterface
Parameters:
assemblyLine - The name identifying the AssemblyLine to start
connector - The runtime-provided Connector
work - The initial work entry
Returns:
The AssemblyLine Thread object
Throws:
Exception - if assemblyLine is an unknown AssemblyLine or if any of the connectors cannot be initialized

startAL

public AssemblyLine startAL(TaskCallBlock tcb)
                     throws Exception
Start the AssemblyLine named in the TCB

Example:

 var tcb = system.newTCB();
 
 tcb.setAssemblyLineName("ALName");
 tcb.setRunMode(com.ibm.di.server.AssemblyLine.RUNMODE_NORMAL); // "normal"
 
 var al = main.startAL(tcb);
 al.join(); // Wait for called AL to complete
 

Parameters:
tcb - The TaskCallBlock
Returns:
The AssemblyLine Thread object
Throws:
Exception - if the AssemblyLine initialization fails.

startAL

public AssemblyLine startAL(String assemblyLine,
                            Object io)
                     throws Exception
Start a named AssemblyLine providing various objects.

Example:

 var iwe = new com.ibm.di.entry.Entry();
 iwe.setAttribute("linenumber", "1");
 iwe.setAttribute("", "Some line with text");
 
 var c = new com.ibm.di.connectors.FileConnector();
 
 var al = main.startAL("ALName", iwe);
 var tcb = al.getTCB();
 
 main.logmsg("AL run mode: " + tcb.getRunMode());
 main.logmsg("AL connector 'debug' parameter: " + tcb.getConnectorParameter("ConnectorName", "debug"));
 main.logmsg("AL initial work entry: ");
 main.dumpEntry(tcb.getInitialWorkEntry());
 

Specified by:
startAL in interface RSInterface
Parameters:
assemblyLine - The name identifying the AssemblyLine to start
io - This Object could either be
  1. an Entry, used as the initial work entry
  2. a Connector, used as a runtime-provided Connector
  3. a Vector that could contain Entry, Connector(s), TCB or a Log objects, used for configuring the AssemblyLine instance.
  4. a TCB, that holds some special configuration fields read by the AssemblyLine
Returns:
The AssemblyLine Thread object
Throws:
Exception - if assemblyLine is an unknown AssemblyLine or if any of the connectors cannot be initialized

startAL

public AssemblyLine startAL(String assemblyLine,
                            Object io,
                            LogInterface logAppender)
                     throws Exception
Start named AssemblyLine providing a parameter

Parameters:
assemblyLine - Name of AssemblyLine to start
io - Parameter to AssemblyLine (Work Entry, Connector or Vector with both )
logAppender - An additional logger to use with the AssemblyLine
Returns:
The AssemblyLine Thread object
Throws:
Exception - if an error while starting the AL thread occurs.

stopAL

public static int stopAL(String name)
Stop named AssemblyLine in all Config Instances.

Parameters:
name - Name of AssemblyLine to stop
Returns:
The number of AssemblyLines we tried to stop

logmsg

public void logmsg(String msg)
Writes a message to the system log file.

Example:

 main.logmsg("Conn object: ");
 main.dumpEntry(conn);
 

Specified by:
logmsg in interface RSInterface
Parameters:
msg - The message to be output.

logmsg

public void logmsg(String level,
                   String msg)
This method logs a message with the specified level to the log.

Example:

 main.logmsg("INFO", "Reading entry...");
 var entry = input.getConnector().getNextEntry();
 

Specified by:
logmsg in interface RSInterface
Parameters:
level - Level of log. Legal values are FATAL, ERROR, WARN, INFO, DEBUG. Unrecognized keyword means DEBUG.
msg - The message

logerror

public void logerror(String msg,
                     Throwable error)
Prints a message to the log, marked as an Error. This method accepts an instance of the Throwable class which information is also put in the log.

Parameters:
msg - the String message
error - the exception object

logerror

public void logerror(String msg)
Writes an error message to the system log file.

Specified by:
logerror in interface RSInterface
Parameters:
msg - The message to output

dump

public void dump(Object o)
Dumps the class and contents of an object to the log file. If this is an Entry, use the RSInterface.dumpEntry(Entry) method instead.

Specified by:
dump in interface RSInterface
Parameters:
o - The object to dump
See Also:
RSInterface.dumpEntry(Entry)

dumpEntry

public void dumpEntry(Entry e)
Dumps the contents of an Entry to the log file.

Example:

 var ctor = input.getConnector();
 
 for (;;) {
        var entry = ctor.getNextEntry();
        if (entry != null) {
                main.logmsg("Read entry: ");
                main.dumpEntry(entry);
        } else
                break;
 }
 

Specified by:
dumpEntry in interface RSInterface
Parameters:
e - The Entry object to dump
See Also:
Entry

reload

public void reload()
            throws Exception
This method reloads the configuration file.

Specified by:
reload in interface RSInterface
Throws:
Exception - if the operation fails.

getConfigPath

public String getConfigPath()
This method returns the current configuration file path

Specified by:
getConfigPath in interface RSInterface
Returns:
The configuration file path as a string

setConfigPath

public void setConfigPath(String path)
This method sets the current configuration file path. This will be used when a persistConfiguration is requested.

Specified by:
setConfigPath in interface RSInterface
Parameters:
path - The new configuration path

persistConfiguration

public void persistConfiguration()
                          throws Exception
This method saves the current configuration to disk.

Specified by:
persistConfiguration in interface RSInterface
Throws:
Exception - if an error while persisting the configuration occurs.

showLogHeader

public static void showLogHeader(Log log)
This method writes a log header to the Log object.

Parameters:
log - The log output object

getLogDirectory

public String getLogDirectory(Object owner)
This method returns the default directory path where log files are stored. TODO: implement this

Parameters:
owner - The Java class or string denoting the type (e.g. AssemblyLine)
Returns:
The log file directory

shutdownServer

public void shutdownServer()
Raise the shutdown request flag and set the exit code to 0. This method requests controlled shutdown of all assembly lines running on the server at the time of calling.

Specified by:
shutdownServer in interface RSInterface

shutdownServer

public void shutdownServer(int aExitCode)
Raise the shutdown request flag and specify an exit code.

Specified by:
shutdownServer in interface RSInterface
Parameters:
aExitCode - the code to return when the application exits.

shutdownServer

public void shutdownServer(int exitCode,
                           boolean async)
Raise the shutdown request flag. This method requests controlled shutdown of all AssemblyLines running on the server at the time of calling, and waits for the AssemblyLines to stop.

Parameters:
exitCode - the code to return when the application exits.
async - If true, crate new Threads to wait for the AssemblyLines to stop
Since:
7.1

stopAssemblyLines

public static void stopAssemblyLines(String name,
                                     int hashCode,
                                     boolean recurse,
                                     boolean async,
                                     RS rs)
                              throws AbortALException
Stops specified running AssemblyLines.

Parameters:
name - The name of the AssemblyLine, or null for any name.
hashCode - The hashCode for the AssemblyLine, as seen in the log files. -1 is any hashCode.
recurse - If true, recursively stop any AssemblyLines started by the AssemblyLine(s) to stop.
async - If true, crate new Threads to wait for the AssemblyLines to stop
rs - If null, stop AssemblyLines in any RS. If non-null, only stop AssemblyLines in that RS.
Throws:
AbortALException - if this method stops the AssemblyLine that called it.
Since:
7.1

stopChildAssemblyLines

public static void stopChildAssemblyLines(AssemblyLine al,
                                          boolean async)
                                   throws AbortALException
Recursively stop all children of one AssemblyLine. Only the children are stopped, not the AssemblyLine itself.

Parameters:
al - The Assemblyline whose children are to be stopped.
async - If true, crate new Threads to wait for the AssemblyLines to stop
Throws:
AbortALException - if this method shuts down the AssemblyLine that called it.
Since:
7.1

getNullBehavior

public String getNullBehavior()
Return the null behavior string from the System.props

Specified by:
getNullBehavior in interface RSInterface
Returns:
the null behavior string

getNullBehaviorValue

public String getNullBehaviorValue()
Gets the null behavior value.

Specified by:
getNullBehaviorValue in interface RSInterface
Returns:
the null behavior value string or null if it have not been set yet.

getNullDefinition

public String getNullDefinition()
Return the null definition string from the System.props

Specified by:
getNullDefinition in interface RSInterface
Returns:
the null Definition string

getNullDefinitionValue

public String getNullDefinitionValue()
Gets the null definition value.

Specified by:
getNullDefinitionValue in interface RSInterface
Returns:
the null definition value string or null if it have not been set yet.

getServerSocketFactory

public ServerSocketFactory getServerSocketFactory(boolean useSSL)
Gets a Server Socket Factory for creating Server Sockets. The boolean parameter useSSL determines whether a SSL Server Socket Factory is returned or non-SSL one.
This method returns a new instance each time when it is called. The reason for this is that the implementation of the caller may be different. Sometimes SSL Factory may be needed while some other times NOT.
This method is for internal use only and you should not rely on it for any other purpose.

Specified by:
getServerSocketFactory in interface RSInterface
Parameters:
useSSL - Determines if SSL or non-SSL Server Socket Factory is returns for use.
Returns:
Server Socket Factory for obtaining Server Sockets.

limitNumberOfThreads

public void limitNumberOfThreads()
This method is called by the startAL(String, Object, LogInterface) method to check whether a limit of the maximum running threads exists.

The limit is set using the Java property "com.ibm.di.server.maxThreadsRunning". If there is such a property and its value is greater than 3 then the thread that calls this method (usually an AssemblyLine thread) will have to wait until another thread ends. If the value of the Java property is not a string representation of an int then the maximum running threads limit check is not done.

If the thread calling this method is waiting for one of the running threads to end is unable to start in timely fashion then a warning for possible deadlock will be output to the log. In that case the calling thread will start.


setGlobalProperties

public static void setGlobalProperties()
This method loads the global.properties/solution.properties and parses their content.


shouldCreateSolutionProps

public static boolean shouldCreateSolutionProps()
Checks if the solution.properties file should be created.

Returns:
false if the solution.properties file exists, true if the file does not exist and should be created

prepareSolutionDirectory

public static void prepareSolutionDirectory(Log log)
                                     throws Exception
Prepare the solution directory (working directory) by ensuring solution.properties is present.

Parameters:
log - the log object to log in.
Throws:
Exception - if I/O error occurs while working with files.

encryptPropertiesfile

public static void encryptPropertiesfile(String path,
                                         Log log)
Loads the properties from the specified file and sets them as system properties. If the properties file references other properties files, those will be loaded too. Decrypts encrypted properties. If decryption fails, an error message is logged and operation continues. After loading, the method overwrites the file to ensure that all protected properties are encrypted. The file will not be overwritten, if all its protected properties are already encrypted. The file will also not be overwritten, if there is no write-access to it. The method does not throw - all errors are logged in the specified logger.

Parameters:
path - a properties file
log - logger

run

public void run()
Thread main

Specified by:
run in interface Runnable
Overrides:
run in class Thread

commandLineParam

public String commandLineParam(String param)
Returns the value for a command line parameter

Parameters:
param - is switch which value to look for.
Returns:
the value of a switch, or null if it does not exist in the map.

getMetamergeConfig

public MetamergeConfig getMetamergeConfig()
Returns the config object for this instance.

Specified by:
getMetamergeConfig in interface RSInterface
Returns:
the configuration object of this instance.

setMetamergeConfig

public void setMetamergeConfig(MetamergeConfig config)
Sets the given configuration to this instance.

Specified by:
setMetamergeConfig in interface RSInterface
Parameters:
config - The configuration object to assign to the instance.

getLog

public Log getLog()
Returns the Log for the current instance

Specified by:
getLog in interface RSInterface
Returns:
the main thread's Log object

getExitStatus

public int getExitStatus()
Gets the exit code of the instance

Returns:
the exit code.

getExitError

public Throwable getExitError()
Returns the exit error of the instance

Returns:
the exception object of the RS instance (in case it failed)

getServerByConfig

public static RS getServerByConfig(MetamergeConfig aConfig)
Gets the server instance that uses the specified by the aConfig configuration.

Parameters:
aConfig - the configuration object used by the server instance
Returns:
The RS object that correspond to the provided configuration, or null if it couldn't be found.

getServer

public static RS getServer()
Returns the RS instance associated with the current ThreadGroup. Although this method is public, it is meant for internal use. The usual way to get the current RS instance would be to use the main object in JavaScript.

Returns:
the RS instance or null if it couldn't be found, e.g. because the current Thread was not created by the TDI framework.

getServer

public static RS getServer(String name)
Returns a named RS instance

Parameters:
name - the name of the instance
Returns:
the RS if it is found, null otherwise.

registerServer

public static void registerServer(RS server)
Registers the config object to be associated with the current ThreadGroup

Parameters:
server - the server to be registered, should not be null

unregisterServer

public static void unregisterServer(RS server)
Registers the config object to be associated with the current ThreadGroup

Parameters:
server - the server to unregister, should not be null

startServer

public static RS startServer(String[] args)
                      throws Exception
Starts server using null for the unique name of the server instance and command line parameters parsed to params table.

Example:

 var cmdline = "-"+com.ibm.di.server.RS.CL_CONFIG;
 cmdline += " test_config.xml -"
 cmdline += com.ibm.di.server.RS.CL_START_AL+" al1, al2"
 
 var srv = main.startServer(cmdline);
 

Parameters:
args - the "command line arguments" to use when starting.
Returns:
The new RS instance
Throws:
Exception - if an error occurs.

startServer

public static RS startServer(String config,
                             String assemblyLines)
                      throws Exception
Starts server using null for the unique name of the server instance. This method starts specified assembly lines from specified configuration.

The server started with this method shutdowns after the assembly line has finished and it can only start configurations not protected with passwords.

Example:

 var config = "//configs//test_config.xml"
 var srv = main.startServer(config, "al2", null);
 

Parameters:
config - the configuration to load
assemblyLines - the assembly lines to start
Returns:
the new RS instance object
Throws:
Exception - if the server initialization fails

startServer

public static RS startServer(String config,
                             String assemblyLines,
                             String passw)
                      throws Exception
Starts server using null for the unique name of the server instance. This method starts specified assembly lines from specified configuration.

The server started with this method shutdowns after the assembly line has finished.

Example:

 var config = "/configs/test_config.xml"
 var pass = "secret";
 
 var srv = main.startServer(config, "al2", null, pass);
 

Parameters:
config - the configuration to load
assemblyLines - the assembly lines to start
passw - the password used for the configuration file
Returns:
the new RS instance object
Throws:
Exception - if the server initialization fails

startServer

public static RS startServer(String config,
                             String assemblyLines,
                             String passw,
                             boolean dontTerminate)
                      throws Exception
Starts server using null for the unique name of the server instance. This method starts specified assembly lines from specified configuration.

Example:

 var config = "/configs/test_config.xml"
 var pass = "secret";
 
 var srv = main.startServer(config, "al1", null, pass, true);
 srv.startAL("al2");
 

Parameters:
config - the configuration to load
assemblyLines - the assembly lines to start
passw - the password used for the configuration file
dontTerminate - whether to wait instead of shutting down the server after it has finished
Returns:
the new RS instance object
Throws:
Exception - if the server initialization fails

startServer

public static RS startServer(String config,
                             String assemblyLines,
                             String passw,
                             boolean dontTerminate,
                             Hashtable<String,Object> userParams)
                      throws Exception
Starts server using null for the unique name of the server instance. This method includes -D option for autostarting if user has specified it.

Example:

 var config = "/configs/test_config.xml"
 var pass = "secret";
 var userParam = new java.util.Hashtable();
 userParam.put(com.ibm.di.server.CL_NO_AUTOSTART, "true");
 
 var srv = main.startServer(config, "al1", null, pass, true, userParam);
 srv.startAL("al2");
 

Parameters:
config - the configuration to load
assemblyLines - the assembly lines to start
passw - the password used for the configuration file
dontTerminate - whether to wait instead of shutting down the server after it has finished
userParams - checks this map if the CL_NO_AUTOSTART exists.
Returns:
the new RS instance object
Throws:
Exception - if the server initialization fails

startServer

public static RS startServer(String groupName,
                             Hashtable<String,Object> params)
                      throws Exception
Starts a new server instance.

Example:

 var par = new java.util.Hashtable();
 par.put(com.ibm.di.server.RS.CL_CONFIG, "tast_config.xml");
 par.put(com.ibm.di.server.RS.CL_START_AL, "al1");
 par.put(com.ibm.di.server.RS.CL_AL_DEBUG, "true");
 
 var srv = main.startServer(null, par);
 

Parameters:
groupName - The unique name for the server instance
params - Hashtable of assembly lines to start (same syntax as command line)
Returns:
the new RS instance object
Throws:
Exception - if there is another instance using the same groupName

createConfigInstance

public static RS createConfigInstance(String groupName,
                                      Hashtable<String,Object> params)
                               throws Exception
Create a new config instance but do not start it.

Parameters:
groupName - The unique name for the server instance
params - Hashtable of assembly lines to start (same syntax as command line)
Returns:
the new RS instance object
Throws:
Exception - if there is another instance using the same groupName

getCommandLineConfigId

public String getCommandLineConfigId()
Returns:
the identifier of the loaded configuration

invokeServerHook

public Object invokeServerHook(String name,
                               Object caller,
                               Object userInfo)
Invokes a server hook.

Parameters:
name - The name of the hook
caller - The object invoking the hook
userInfo - Arbitrary information to the hook from the caller
Returns:
The result from the function call or null if a hook with that name could not be found.

getConnectorPoolNames

public String[] getConnectorPoolNames()
Returns:
an Array of String objects containing the names of the ConnectorPools

getConnectorPool

public ConnectorPool getConnectorPool(String connName)
Parameters:
connName - the name of the ConnectorPool object
Returns:
the ConnectorPool instance that corresponds of the provided name, if the name is not found null is returned.

getConfigInstanceNamingPolicy

public static RS.ConfigInstanceNamingPolicy getConfigInstanceNamingPolicy()
Returns:
The configuration instance naming policy of the Server.
Since:
7.0

setConfigInstanceNamingPolicy

public static void setConfigInstanceNamingPolicy(RS.ConfigInstanceNamingPolicy newPolicy)
Parameters:
newPolicy - A new configuration instance naming policy for the Server.
Since:
7.0

checkLUM

public static void checkLUM()
This function checks if a valid license to run the application exists in the nodelock file. If no license exists, the license has expired, or an error is encountered, the server will exit.

Since:
7.0

waitForInitializationToComplete

public boolean waitForInitializationToComplete(long milliseconds)
                                        throws InterruptedException

This method is for internal use only. Users must not rely on it.

Wait for the configuration instance (a.k.a RS instance) to complete its initialization. Normally the initialization procedure of a config instance involves activities such as parsing the configuration xml file and preparing internal structures like Connector Pools. You may care about initialization status, because it is not a good idea to start AssemblyLines on the RS instance before initialization is complete. Note that when initialization is complete the RS instance might be in error state.

Parameters:
milliseconds - Timeout in milliseconds to wait for the initialization completion. If the time is less than or equal to zero, the method will not wait at all.
Returns:
true if the count reached zero and false if the waiting time elapsed before the count reached zero.
Throws:
InterruptedException - If the calling thread is interrupted while waiting for initialization status.
Since:
7.0

assemblyLineCycleEnded

public void assemblyLineCycleEnded(AssemblyLine al,
                                   Entry work)
                            throws Exception
An AssemblyLine cycle (iteration) is complete.

Specified by:
assemblyLineCycleEnded in interface AssemblyLine.AssemblyLineListener
Parameters:
al - The AssemblyLine.
work - The work Entry.
Throws:
Exception - Will stop the AssemblyLine, so be careful.

assemblyLineTerminated

public void assemblyLineTerminated(AssemblyLine al)
The AssemblyLine terminated.

Specified by:
assemblyLineTerminated in interface AssemblyLine.AssemblyLineListener
Parameters:
al - The AssemblyLine.

addListener

public void addListener(ConfigInstanceListener listener)

This method is for internal use only. Users must not rely on it.

Register listener to this configuration instance.

Specified by:
addListener in interface Listenable<ConfigInstanceListener>
Parameters:
listener - Listener for configuration instance notifications.
Since:
7.0

removeListener

public void removeListener(ConfigInstanceListener listener)

This method is for internal use only. Users must not rely on it.

Unregister listener from this configuration instance.

Specified by:
removeListener in interface Listenable<ConfigInstanceListener>
Parameters:
listener - Registered listener.
Since:
7.0

shutdownAllServers

public static void shutdownAllServers(int exitCode,
                                      boolean master,
                                      boolean async)
This method shuts down all Config Instances.

Parameters:
exitCode - The exit code to use
master - If true, also stop the master server
async - If true, crate new Threads to wait for the AssemblyLines to stop
Since:
7.1