AgentDE
Class IRR_ObjectServerBase

java.lang.Object
  |
  +--AgentDE.IRR_ObjectServerBase
Direct Known Subclasses:
IRRServer_MainFE, IRRServer_StubFE, IRRServer_TCPIP_SocketFE

public class IRR_ObjectServerBase
extends java.lang.Object

Overview -- An IMPACT Object Server (IOS) typically consists of three main components:

The IRR_ObjectServerBase class defines the objects and methods necessary to initialize and register a basic IOS (Java RMI protocols), install and run a message queue and monitor, and finally deregister / deinitialize the IOS. Be it an agent "roost" or a specialized client interface, the IRR_ObjectServerBase class defines the IMPACT communications "corner-stone". Some basic methods of note include:
Developers building custom IOS interfaces who need to define alternate capabilities and message "call-back" functionality need only render a class extenstion from this, and the IRR_QMonitor base classes, and overload the applicable methods.

The IRRServer_MainFE class, for example, defines an IMPACT "Roost" by extending the IRR_ObjectServerBase class with additional boot-up parameter parsing, alternate agent registration, and installs a modified IRR_QMonitor which prompts "sleeping" agents to work when messages arrive for them.

The IR_ExampleMsgAPI_Frame class mimics how an external application might use the IRR_ObjectServerBase class, with an altered (extended) QMonitor, to render a simple two-way (Client App <==> IMPACT) message interface.


Inner Class Summary
(package private)  class IRR_ObjectServerBase.VPortThread
          This inner class definition exists solely to allow launching the developers GUI from a separate thread (if necessary).
 
Field Summary
private  boolean bRoostServer
           
private  java.rmi.registry.Registry currRegistry
           
private  IAD_Identity defaultFEAgentID
          The IOS "default" agent representative identity (when used) object.
private  IA_Global gRef
          The underlying IOS "Global" data (IA_Global) reference object.
private  IAD_Location hostRMI_PortLoc
           
private  boolean invokedStandalone
           
private  IRR_RoostHookImpl iosHookServer
          The IOS <--> IOS Java RMI interface module.
private  IA_MessageQueue msgQueue
          The IOS message queue (IA_MessageQueue) object reference.
private  int nMonitorInterval
           
private  IRR_QMonitor qMonitor
          The IOS queue monitor (IRR_QMonitor or extension) object reference.
private  java.lang.SecurityManager securityManager
          The IOS Java security manager object reference.
private static java.lang.String szBASE_HEAD
          A simple class reference string for debug output.
private static java.lang.String szCLP_ECHO_ANSWERS
          Base IOS command-line echo-answer mode argument string constant.
private static java.lang.String szCLP_ECHO_DEBUG
          Base IOS command-line debug mode argument string constant.
private static java.lang.String szCLP_ECHO_STATUS
          Base IOS command-line echo-status mode argument string constant.
private static java.lang.String szCLP_EXPLAIN_PARAMS
          Base IOS command-line explaination prompt argument string constant.
private static java.lang.String szCLP_HOST_SERVER
          Base IOS command-line Local server host argument string constant.
private static java.lang.String szCLP_LOG_MESSAGES
          Base IOS command-line message log mode argument string constant.
private static java.lang.String szCLP_LOG_TIMING
          Base IOS command-line echo-timing mode argument string constant.
private static java.lang.String szCLP_MON_INTERVAL
          Base IOS command-line queue-monitor interval argument string constant.
private static java.lang.String szCLP_PASSWORD
          Base IOS command-line password argument string constant.
private static java.lang.String szCLP_SEC_MANAGER
          Base IOS command-line RMI security-manager argument string constant.
private static java.lang.String szCLP_SERVER_NAME
          Base IOS command-line server-name argument string constant.
private static java.lang.String szCLP_YP_SERVER
          Base IOS command-line Yellow-Pages server host argument string constant.
private  java.lang.String szHostName
           
private  java.lang.String szIOS_Binding
           
private  java.lang.String szIOS_Password
           
private  java.lang.String szLocalHost
           
private  java.lang.String szLocalIP_Address
           
private static java.lang.String szSUFFIX_IOS
          The default IOS host name suffix string constant.
private static java.lang.String szSUFFIX_ROOST
          The Roost IOS host name suffix string constant.
private static java.lang.String szUNNAMED
          Base constant for unnamed IOS instances.
private  IAD_Location ypPortLoc
           
private  IYR_YPHook ypsHook
          The IOS <--> IMPACT Yellow-Pages server Java RMI interface module.
 
Constructor Summary
IRR_ObjectServerBase()
          Build an IRR_ObjectServerBase object.
 
Method Summary
 boolean connect(boolean bValidating, boolean bRunDirect, int nDepth)
          Initializes the entire IOS by invoking the applicable connectExtensions() and connectIOS() methods.
 boolean connectExtensions(boolean bValidating, int nDepth)
          Extension classes overload this method, as necessary, to initialize IOS extension objects.
 boolean connectIOS(boolean bValidating, boolean bRunDirect, int nDepth)
          Initializes the base IOS, typically by launching the underlying Java RMI communication modules and registering with the Yellow-Pages server, installing a message queue (IA_MessageQueue), registering initial IOS agents, and launching the queue monitor (IRR_QMonitor).

(NOTE: Called from base connect method)
Note: For connect() method overloads, we recommend that the extension- class define the desired server connect code, and then call the underlying connect (i.e.
 int deRegisterAgentIDs(IAD_Identity[] agentIDArray, int nDepth)
          DeRegister the agent(s) for message receipt on this IOS.
 boolean disconnect(int nDepth)
          Terminates the entire IOS by invoking the applicable disconnectIOS() and disconnectExtensions() methods.
 boolean disconnectExtensions(int nDepth)
          Extension classes overload this method, as necessary, to terminate the extension server objects.
(NOTE: Called from base disconnect method)
 boolean disconnectIOS(int nDepth)
          Terminates the base IOS by deregistering with the Yellow-Pages server, removing the Java RMI module bindings, and stopping the message-queue logger thread (as applicable).
(NOTE: Called from base disconnect method)
 boolean dropViewPort(int nDepth)
          This over-rideable method is intended to wrap a developers GUI shut-down code.
 void dumpParameterExplaination()
          This method writes a usage explaination of supported command-line arguments to the system console.

Note: Internally it invokes the dumpParamExtensionExplaination() method to also describe developer defined command-line argument parser extentions.
 void dumpParamExtensionExplaination()
          This over-rideable method is intended to wrap developer command-line argument extension descriptions for the base IOS dumpParameterExplaination() method.
 java.lang.String getDefaultFrontEndAgentName()
          Get the default IOS representative agent name.
 IA_Global getGlobalRef()
          Get the IRR_ObjectServerBase "Global" object reference.
 java.lang.String getObjectRMI_SzBinding(IAD_Location tgtLocation, java.lang.String szRMI_BindingLabel)
          Builds an RMI object binding string from the input port location and the Object binding label (the objects RMI look-up string).
NOTE: If the input tgtLocation reference is NULL, then the binding string references the current network local host parameters.
 IRR_QMonitor getQMonitor()
          Get the IOS queue monitor reference.
 IAD_Location getRMI_HostLocation()
          Get the IOS Java RMI host server location (URL and Port wrapper)
 boolean isEchoDebug()
          Return the underlying "Global" (IA_Global) debug flag value.
 boolean isIOSConnected()
          Return the IOS status (IOS running --> open for incoming messages).
 boolean isMessageLogging()
          Return the underlying "Global" (IA_Global) message-logging flag value.
 boolean isMonitored()
          Return the underlying IOS queue monitor status
(monitor running --> in/out going message handling underway).
 boolean launchViewPort(int nDepth)
          This over-rideable method is intended to wrap a developers GUI launch code (wrapping it here allows us to build it in a separate thread if necessary -- see IOS.spawnThreadedViewPort).
 boolean load_RMI_Registry(int nTgtPort, int nDepth)
          Install the RMI registry port
(NOTE: More than one RMI interface can be bound to the same port)
 boolean localizeHostLoc(IAD_Location tgtLocation, java.lang.String szIOPrefix, int nDepth)
          Adjusts the target port location URL to match that of the default local host (where URL string is currently null).
NOTE: This method discovers the network local host setings during its first execution call().
static void main(java.lang.String[] args)
          Default main routine demonstrates the parseArgs() method call and invokes the validates() method to testing the server setup parameters.
 boolean parseArgs(java.lang.String[] szArgArray, boolean bDumpExplainationOnError)
          This base-class method parses the command-line arguments for parameters common to all IOS objects (i.e.
 boolean parseExtensionArg(java.lang.String szArgument)
          This over-rideable method is intended to wrap developer extensions for the base IOS parseArgs() method (when IOS.parseArgs fails, it invokes this method).

Note: If you extend the parser, don't forget to extend the dumpParamExtensionExplaination() method with the corresponding argument usage description.
static IAD_Location parsePortLocation(java.lang.String szTgtArg, int nDefaultPort, java.lang.String szIOPrefix, boolean bDebug, int nDepth)
          Parses input application URL argument into an IAD_Location object.
 int registerAgentIDs(IAD_Identity[] agentIDArray, int nDepth)
          Register the agent(s) for message receipt on this IOS.
 int registerAgentIDs(java.util.Vector vSrcAgentIDs, int nDepth)
          Register the agent(s) for message receipt on this IOS.
 int registerInitialAgents(int nDepth)
          This method gets called just prior to starting the IOS queue monitor thread to register a base agent set for message receipt (at this IOS).
 boolean run(int nDepth)
          This method wraps code necessary for launching a typical IOS; Developers commonly need only invoke the IOS.parseArgs() method, modify additional parameters as necessary (i.e.
 boolean sendMessage(java.lang.String szFrom, java.lang.String szTo, java.lang.String szCommand, int nFlags, java.lang.Object objData, int nDepth)
          Insert an IMPACT message into the IOS message queue (routing handled automatically by the underlying IOS services).
 boolean setDefaultFrontEndAgent(IAD_Identity srcID)
          Set the "default" front-end representative "agent" by identity reference.
 boolean setDefaultFrontEndAgent(java.lang.String szSrcName)
          Set the "default" front-end representative "agent" by name.
 boolean setDefaultFrontEndAgent(java.lang.String szSrcName, java.lang.String szSrcDescription)
          Set the "default" front-end representative "agent" by name and description strings.
 void setEchoDebug(boolean bMode)
          Set the underlying "Global" (IA_Global) debug flag value.
 void setGlobalRef(IA_Global tgtGRef)
          Set the IRR_ObjectServerBase "Global" object reference.
 void setIMPACT_Password(java.lang.String szTargetPW)
          Set the IOS communications password.
 void setMessageLogging(boolean bMode)
          Set the underlying "Global" (IA_Global) message-logging flag value.
 void setMonitorInterval(int nTgtInterval_MS)
          Set the IOS queue monitor loop cycle sleep duration (milliseconds).
 boolean setQMonitor(IRR_QMonitor srcQMonitor, int nDepth)
          Set the IOS queue monitor.
 void setRMI_HostInfo(java.lang.String szTgtServerHost, int nTgtServerPort)
          Set the IOS local host server address and port information.
 void setRMISecurityManager()
          Set the default Java RMISecurityManager as the IOS communications security manager.
 void setRoostMode(boolean bMode)
          Set the IOS "Roost-mode" flag.
 void setSecurityManager(java.lang.SecurityManager tgtSecurityManager)
          Set the IOS communications security manager reference.
 void setServerName(java.lang.String szTgtName)
          Set the name associated with the IOS.
Note: IMPACT will append a name suffix depending on functionality.
 void setStatus(java.lang.String szStatusText)
          Set the IMPACT status JLabel text.
 void setStatusJLabel(javax.swing.JLabel tgtJLabel)
          Set the IMPACT status update JLabel reference.
IMPACT commonly writes process status information to a Java Swing JLabel object (when available).
 void setYPServerInfo(java.lang.String szTgtYPServerHost, int nTgtYPServerPort)
          Set the IOS Yellow-Pages server address and port information.
 boolean spawnThreadedViewPort(int nDepth)
          This method allows us to launch a developers GUI from a separate thread if necessary (useful where the GUI takes a while to appear due to resource loads).
 void terminateMonitor()
          Prompt the IOS queue monitor to terminate its run loop.
static boolean updateSystemSecurityManager(java.lang.SecurityManager tgtSM, boolean bDebug, int nDepth)
          Prompts installation / deinstallation of the System SecurityManager (SSM) object according to the current IOS setting.
 boolean validates(int nDepth)
          An IOS instantiation is valid if it can successfully initialize and shutdown; This method toggles the underlying connect() and disconnect() methods over the current server setup values to determine IOS validity.
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait
 

Field Detail

invokedStandalone

private boolean invokedStandalone

szBASE_HEAD

private static final java.lang.String szBASE_HEAD
A simple class reference string for debug output.

szSUFFIX_IOS

private static final java.lang.String szSUFFIX_IOS
The default IOS host name suffix string constant.

szSUFFIX_ROOST

private static final java.lang.String szSUFFIX_ROOST
The Roost IOS host name suffix string constant.

szUNNAMED

private static final java.lang.String szUNNAMED
Base constant for unnamed IOS instances.

szCLP_SERVER_NAME

private static final java.lang.String szCLP_SERVER_NAME
Base IOS command-line server-name argument string constant.

szCLP_PASSWORD

private static final java.lang.String szCLP_PASSWORD
Base IOS command-line password argument string constant.

szCLP_SEC_MANAGER

private static final java.lang.String szCLP_SEC_MANAGER
Base IOS command-line RMI security-manager argument string constant.

szCLP_YP_SERVER

private static final java.lang.String szCLP_YP_SERVER
Base IOS command-line Yellow-Pages server host argument string constant.

szCLP_HOST_SERVER

private static final java.lang.String szCLP_HOST_SERVER
Base IOS command-line Local server host argument string constant.

szCLP_MON_INTERVAL

private static final java.lang.String szCLP_MON_INTERVAL
Base IOS command-line queue-monitor interval argument string constant.

szCLP_ECHO_DEBUG

private static final java.lang.String szCLP_ECHO_DEBUG
Base IOS command-line debug mode argument string constant.

szCLP_ECHO_ANSWERS

private static final java.lang.String szCLP_ECHO_ANSWERS
Base IOS command-line echo-answer mode argument string constant.

szCLP_ECHO_STATUS

private static final java.lang.String szCLP_ECHO_STATUS
Base IOS command-line echo-status mode argument string constant.

szCLP_LOG_MESSAGES

private static final java.lang.String szCLP_LOG_MESSAGES
Base IOS command-line message log mode argument string constant.

szCLP_LOG_TIMING

private static final java.lang.String szCLP_LOG_TIMING
Base IOS command-line echo-timing mode argument string constant.

szCLP_EXPLAIN_PARAMS

private static final java.lang.String szCLP_EXPLAIN_PARAMS
Base IOS command-line explaination prompt argument string constant.

szHostName

private java.lang.String szHostName

ypPortLoc

private IAD_Location ypPortLoc

hostRMI_PortLoc

private IAD_Location hostRMI_PortLoc

szIOS_Binding

private java.lang.String szIOS_Binding

szIOS_Password

private java.lang.String szIOS_Password

securityManager

private java.lang.SecurityManager securityManager
The IOS Java security manager object reference.

gRef

private IA_Global gRef
The underlying IOS "Global" data (IA_Global) reference object.

iosHookServer

private IRR_RoostHookImpl iosHookServer
The IOS <--> IOS Java RMI interface module.

ypsHook

private IYR_YPHook ypsHook
The IOS <--> IMPACT Yellow-Pages server Java RMI interface module.

msgQueue

private IA_MessageQueue msgQueue
The IOS message queue (IA_MessageQueue) object reference.

qMonitor

private IRR_QMonitor qMonitor
The IOS queue monitor (IRR_QMonitor or extension) object reference.

szLocalHost

private transient java.lang.String szLocalHost

szLocalIP_Address

private transient java.lang.String szLocalIP_Address

nMonitorInterval

private transient int nMonitorInterval

bRoostServer

private boolean bRoostServer

defaultFEAgentID

private IAD_Identity defaultFEAgentID
The IOS "default" agent representative identity (when used) object.

currRegistry

private java.rmi.registry.Registry currRegistry
Constructor Detail

IRR_ObjectServerBase

public IRR_ObjectServerBase()
Build an IRR_ObjectServerBase object.
Method Detail

getRMI_HostLocation

public final IAD_Location getRMI_HostLocation()
Get the IOS Java RMI host server location (URL and Port wrapper)
Returns:
The host server location (IAD_Location) object reference.

setDefaultFrontEndAgent

public final boolean setDefaultFrontEndAgent(java.lang.String szSrcName)
Set the "default" front-end representative "agent" by name. Use this to equate one "agent" representation for the IOS; Upon initialization, IMPACT then knows to route message traffic for this "agent" to this IOS.
Note: Underlying code stores agent identity as an IAD_Identity object.
Parameters:
szSrcName - -- The agent name string.
Returns:
Success -- true.
Failure -- False.

setDefaultFrontEndAgent

public final boolean setDefaultFrontEndAgent(java.lang.String szSrcName,
                                             java.lang.String szSrcDescription)
Set the "default" front-end representative "agent" by name and description strings. Use this to equate one "agent" representation for the IOS; Upon initialization, IMPACT then knows to route message traffic for this "agent" to this IOS. Note: Underlying code stores agent identity as an IAD_Identity object.
Parameters:
szSrcName - -- The agent name string.
szSrcDescription - -- The agent description string.
Returns:
Success -- true.
Failure -- False.

setDefaultFrontEndAgent

public final boolean setDefaultFrontEndAgent(IAD_Identity srcID)
Set the "default" front-end representative "agent" by identity reference. Use this to equate one "agent" representation for the IOS; Upon initialization, IMPACT then knows to route message traffic for this "agent" to this IOS.
Parameters:
srcID - -- The agent identity (IAD_Identity) reference. 8
Returns:
Success -- true.
Failure -- False.

getDefaultFrontEndAgentName

public final java.lang.String getDefaultFrontEndAgentName()
Get the default IOS representative agent name.
Returns:
The IOS representative agent name String object reference.

getGlobalRef

public final IA_Global getGlobalRef()
Get the IRR_ObjectServerBase "Global" object reference.
Returns:
The IRR_ObjectServerBase IA_Global object reference.

setGlobalRef

public final void setGlobalRef(IA_Global tgtGRef)
Set the IRR_ObjectServerBase "Global" object reference.
Parameters:
tgtGRef - -- The target IA_Global object reference.

setYPServerInfo

public final void setYPServerInfo(java.lang.String szTgtYPServerHost,
                                  int nTgtYPServerPort)
Set the IOS Yellow-Pages server address and port information.
Parameters:
szTgtYPServerHost - -- The target Yellow-Pages server host URL.
nTgtYPServerPort - -- The target Yellow-Pages server host port.

setRMI_HostInfo

public final void setRMI_HostInfo(java.lang.String szTgtServerHost,
                                  int nTgtServerPort)
Set the IOS local host server address and port information.
Parameters:
szTgtServerHost - -- The target local server host URL.
nTgtServerPort - -- The target local server host port.

setSecurityManager

public final void setSecurityManager(java.lang.SecurityManager tgtSecurityManager)
Set the IOS communications security manager reference.
Parameters:
tgtSecurityManager - -- The target security manager object reference.

setRMISecurityManager

public final void setRMISecurityManager()
Set the default Java RMISecurityManager as the IOS communications security manager.

setStatusJLabel

public final void setStatusJLabel(javax.swing.JLabel tgtJLabel)
Set the IMPACT status update JLabel reference.
IMPACT commonly writes process status information to a Java Swing JLabel object (when available). Including such a status bar mechanism improves client feedback for the underlying system.
Parameters:
tgtJLabel - -- The target JLabel object reference.

setStatus

public final void setStatus(java.lang.String szStatusText)
Set the IMPACT status JLabel text. Use this to update the status-bar text during IOS initialization, processing, and shutdown.
Parameters:
szStatusText - -- The source text update string.

setServerName

public final void setServerName(java.lang.String szTgtName)
Set the name associated with the IOS.
Note: IMPACT will append a name suffix depending on functionality.
Parameters:
szTgtName - -- The target IOS server name string object reference.

setRoostMode

public final void setRoostMode(boolean bMode)
Set the IOS "Roost-mode" flag.
Parameters:
bMode - -- The target flag boolean value.

setIMPACT_Password

public final void setIMPACT_Password(java.lang.String szTargetPW)
Set the IOS communications password.
Parameters:
szTargetPW - -- The target password string object reference.

setQMonitor

public final boolean setQMonitor(IRR_QMonitor srcQMonitor,
                                 int nDepth)
Set the IOS queue monitor. Use this to install an IRR_QMonitor extension.
Parameters:
srcQMonitor - -- The source IRR_QMonitor extension class object reference.
nDepth - -- The method call stack depth integer for the debug echo display. 8
Returns:
Success -- true.
Failure -- False.

getQMonitor

public final IRR_QMonitor getQMonitor()
Get the IOS queue monitor reference.
Returns:
an IRR_QMonitor (extension) class object.

setMonitorInterval

public final void setMonitorInterval(int nTgtInterval_MS)
Set the IOS queue monitor loop cycle sleep duration (milliseconds).
Parameters:
nInterval_MS - -- The Target sleep interval int value.

terminateMonitor

public final void terminateMonitor()
Prompt the IOS queue monitor to terminate its run loop.

sendMessage

public final boolean sendMessage(java.lang.String szFrom,
                                 java.lang.String szTo,
                                 java.lang.String szCommand,
                                 int nFlags,
                                 java.lang.Object objData,
                                 int nDepth)
Insert an IMPACT message into the IOS message queue (routing handled automatically by the underlying IOS services).
Parameters:
szFrom - -- The message message source agent name string.
szTo - -- The message recipient agent name string.
szCommand - -- The message command prompt string.
nFlags - -- The message handling int flag value
(can be used to cite special IOS handling).
objData - -- The message data object reference.
nDepth - -- The method call stack depth integer for the debug echo display.
Returns:
Success -- true.
Failure -- False.

registerAgentIDs

public final int registerAgentIDs(IAD_Identity[] agentIDArray,
                                  int nDepth)
Register the agent(s) for message receipt on this IOS.
Parameters:
agentIDArray - -- An array of agent identity (IAD_Identity) object references.
nDepth - -- The method call stack depth integer for the debug echo display.
Returns:
nCount -- The number of agent identitys registered.

registerAgentIDs

public final int registerAgentIDs(java.util.Vector vSrcAgentIDs,
                                  int nDepth)
Register the agent(s) for message receipt on this IOS.
Parameters:
vSrcAgentIDs - -- A Vector of agent identity (IAD_Identity) object references.
nDepth - -- The method call stack depth integer for the debug echo display.
Returns:
nCount -- The number of agent identitys registered.

registerInitialAgents

public int registerInitialAgents(int nDepth)
This method gets called just prior to starting the IOS queue monitor thread to register a base agent set for message receipt (at this IOS).

Note 1: A "default" agent representative can be assigned during IOS initialization via the setDefaultFrontEndAgent() method call; In this case the base class method registers the default agent for message message receipt on the IOS.

Note 2: Overload this method in an extension class to alter the default agent initialization schema.
Parameters:
nDepth - -- The method call stack depth integer for the debug echo display.
Returns:
nCount -- The number of agent identitys registered.

deRegisterAgentIDs

public final int deRegisterAgentIDs(IAD_Identity[] agentIDArray,
                                    int nDepth)
DeRegister the agent(s) for message receipt on this IOS.
Parameters:
agentIDArray - -- An array of agent identity (IAD_Identity) object references.
nDepth - -- The method call stack depth integer for the debug echo display.
Returns:
nCount -- The number of agent identitys registered.

validates

public final boolean validates(int nDepth)
An IOS instantiation is valid if it can successfully initialize and shutdown; This method toggles the underlying connect() and disconnect() methods over the current server setup values to determine IOS validity.
Returns:
Success -- true.
Failure -- False.

isIOSConnected

public final boolean isIOSConnected()
Return the IOS status (IOS running --> open for incoming messages).
Returns:
true --> IOS is running.
false --> IOS is Not running.

isMonitored

public final boolean isMonitored()
Return the underlying IOS queue monitor status
(monitor running --> in/out going message handling underway).
Returns:
true --> IOS queue monitor is running.
false --> IOS queue monitor is Not running.

isEchoDebug

public final boolean isEchoDebug()
Return the underlying "Global" (IA_Global) debug flag value.
Returns:
true --> "Echo Debug" is On.
false --> "Echo Debug" is Off.

setEchoDebug

public final void setEchoDebug(boolean bMode)
Set the underlying "Global" (IA_Global) debug flag value.
Parameters:
bMode - -- The target debug boolean mode.

isMessageLogging

public final boolean isMessageLogging()
Return the underlying "Global" (IA_Global) message-logging flag value.
Returns:
true --> Message logging is On.
false --> Message logging is Off.

setMessageLogging

public final void setMessageLogging(boolean bMode)
Set the underlying "Global" (IA_Global) message-logging flag value.
Parameters:
bMode - -- The target message-logging boolean mode.

load_RMI_Registry

public boolean load_RMI_Registry(int nTgtPort,
                                 int nDepth)
Install the RMI registry port
(NOTE: More than one RMI interface can be bound to the same port)
Parameters:
nTgtPort - -- The target RMI registry port.
nDepth - -- The method call stack depth integer for the debug echo display. 8
Returns:
Success -- true.
Failure -- False.

connectIOS

public final boolean connectIOS(boolean bValidating,
                                boolean bRunDirect,
                                int nDepth)
Initializes the base IOS, typically by launching the underlying Java RMI communication modules and registering with the Yellow-Pages server, installing a message queue (IA_MessageQueue), registering initial IOS agents, and launching the queue monitor (IRR_QMonitor).

(NOTE: Called from base connect method)
Note: For connect() method overloads, we recommend that the extension- class define the desired server connect code, and then call the underlying connect (i.e. this) method to invoke the IOS connection.
Parameters:
bValidating - -- Determines the connection "validation" mode.
bValidating == true --> Test mode; Verifies the server setup by launching the Java RMI modules only (after which the method immediately returns). The IOS does NOT register initial agents, nor does it start the queue monitor.
bValidating == false -->Normal mode; Launches the IOS Java RMI modules, installs a message queue, and then starts the queue monitor.
bRunDirect - -- Determines whether the queue monitor thread starts via the "run" or the "start" method invocation; QMonitor.start() returns immediately, whereas QMonitor.run() will cause this method to hang until the monitor is stopped.
nDepth - -- The method call stack depth integer for the debug echo display.
Returns:
Success -- true.
Failure -- False.

connectExtensions

public boolean connectExtensions(boolean bValidating,
                                 int nDepth)
Extension classes overload this method, as necessary, to initialize IOS extension objects. (NOTE: Called from base connect method)
Parameters:
bValidating - -- Determines the connection "validation" mode.
bValidating == true --> Test mode; When true, only class objects necessary for verifying connection parameters be defined.
bValidating == false -->Normal mode (this is not a test -- instantiate everything necessary).
nDepth - -- The method call stack depth integer for the debug echo display.
Returns:
Success -- true.
Failure -- False.

connect

public boolean connect(boolean bValidating,
                       boolean bRunDirect,
                       int nDepth)
Initializes the entire IOS by invoking the applicable connectExtensions() and connectIOS() methods.
Parameters:
bValidating - -- Determines the connection "validation" mode.
bValidating == true --> Test mode; Underlying code verifies the server setup by launching the Java RMI modules only (after which the method immediately returns). The IOS does NOT register initial agents, nor does it start the queue monitor.
bValidating == false -->Normal mode; Launches the complete IOS.
bRunDirect - -- Determines whether the queue monitor thread starts via the "run" or the "start" method invocation; QMonitor.start() returns immediately, whereas QMonitor.run() will cause this method to hang until the monitor is stopped.
nDepth - -- The method call stack depth integer for the debug echo display.
Returns:
Success -- true.
Failure -- False.

disconnect

public boolean disconnect(int nDepth)
Terminates the entire IOS by invoking the applicable disconnectIOS() and disconnectExtensions() methods.
Parameters:
nDepth - -- The method call stack depth integer for the debug echo display.
Returns:
Success -- true.
Failure -- False.

disconnectExtensions

public boolean disconnectExtensions(int nDepth)
Extension classes overload this method, as necessary, to terminate the extension server objects.
(NOTE: Called from base disconnect method)
Parameters:
nDepth - -- The method call stack depth integer for the debug echo display.
Returns:
Success -- true.
Failure -- False.

disconnectIOS

public final boolean disconnectIOS(int nDepth)
Terminates the base IOS by deregistering with the Yellow-Pages server, removing the Java RMI module bindings, and stopping the message-queue logger thread (as applicable).
(NOTE: Called from base disconnect method)
Parameters:
nDepth - -- The method call stack depth integer for the debug echo display.
Returns:
Success -- true.
Failure -- False.

updateSystemSecurityManager

public static final boolean updateSystemSecurityManager(java.lang.SecurityManager tgtSM,
                                                        boolean bDebug,
                                                        int nDepth)
Prompts installation / deinstallation of the System SecurityManager (SSM) object according to the current IOS setting.
Parameters:
tgtSM - -- The target Java SecurityManager object reference. Please Note that there are System/call cases possible as follows:
1: tgtSM == NULL && No SSM is currently loaded --> No action taken.
2: tgtSM == NULL && an SSM is currently loaded --> Removes current security manager.
3: tgtSM != NULL && No SSM is currently loaded --> Installs the tgtSM reference as the current SSM.
4: tgtSM 1= NULL && an SSM is currently loaded --> Replaces the current SSM with the tgtSM reference object.
nDepth - -- The method call stack depth integer for the debug echo display.
Returns:
Success -- true.
Failure -- False.

main

public static void main(java.lang.String[] args)
Default main routine demonstrates the parseArgs() method call and invokes the validates() method to testing the server setup parameters.
Parameters:
args - -- The command line argument string array.

run

public final boolean run(int nDepth)
This method wraps code necessary for launching a typical IOS; Developers commonly need only invoke the IOS.parseArgs() method, modify additional parameters as necessary (i.e. switch the queue monitor), and then invoke the IOS.run() method.
Parameters:
nDepth - -- The method call stack depth integer for the debug echo display.
Returns:
Success -- true.
Failure -- False.

parseArgs

public final boolean parseArgs(java.lang.String[] szArgArray,
                               boolean bDumpExplainationOnError)
This base-class method parses the command-line arguments for parameters common to all IOS objects (i.e. Yellow-Pages and Host server addressing, Security Manager usage, queue monitor intervals, and more).

Note 1: Should this method Not handle a given input argument, it then calls the parseExtensionArg() method for extended parsing capability. In this respect, IOS developers can extend the base command-line parsing by extending the base class, and overloading the parseExtensionArg() method.

Note 2: When the argument is unparseable by both this and the extension method, then it invokes the dumpParameterExplaination() method to render a console explaination of the supported arguments.
Parameters:
szArgArray - -- The input command line argument string array.
bDumpExplainationOnError - --
Returns:
Success -- true.
Failure -- False.

parseExtensionArg

public boolean parseExtensionArg(java.lang.String szArgument)
This over-rideable method is intended to wrap developer extensions for the base IOS parseArgs() method (when IOS.parseArgs fails, it invokes this method).

Note: If you extend the parser, don't forget to extend the dumpParamExtensionExplaination() method with the corresponding argument usage description.
Parameters:
szArgument - -- The target command line argument.
Returns:
Success -- true.
Failure -- False.

dumpParamExtensionExplaination

public void dumpParamExtensionExplaination()
This over-rideable method is intended to wrap developer command-line argument extension descriptions for the base IOS dumpParameterExplaination() method.

dumpParameterExplaination

public final void dumpParameterExplaination()
This method writes a usage explaination of supported command-line arguments to the system console.

Note: Internally it invokes the dumpParamExtensionExplaination() method to also describe developer defined command-line argument parser extentions.

launchViewPort

public boolean launchViewPort(int nDepth)
This over-rideable method is intended to wrap a developers GUI launch code (wrapping it here allows us to build it in a separate thread if necessary -- see IOS.spawnThreadedViewPort).
Parameters:
nDepth - -- The method call stack depth integer for the debug echo display.
Returns:
Success -- true.
Failure -- False.

dropViewPort

public boolean dropViewPort(int nDepth)
This over-rideable method is intended to wrap a developers GUI shut-down code.
Parameters:
nDepth - -- The method call stack depth integer for the debug echo display.
Returns:
Success -- true.
Failure -- False.

spawnThreadedViewPort

public final boolean spawnThreadedViewPort(int nDepth)
This method allows us to launch a developers GUI from a separate thread if necessary (useful where the GUI takes a while to appear due to resource loads).
Parameters:
nDepth - -- The method call stack depth integer for the debug echo display.
Returns:
Success -- true.
Failure -- False.

parsePortLocation

public static IAD_Location parsePortLocation(java.lang.String szTgtArg,
                                             int nDefaultPort,
                                             java.lang.String szIOPrefix,
                                             boolean bDebug,
                                             int nDepth)
Parses input application URL argument into an IAD_Location object.
Parameters:
szTgtArg - -- The input command-line argument.
nDefaultPort - -- The default port number.
szIOPrefix - -- The port ID string echoed to the console (debug).
bDebug - -- The console-echo debug mode.
nDepth - -- The method call stack depth integer for the debug echo display.
Returns:
Success --> an IAD_Location object.
Failure --> NULL.

localizeHostLoc

public boolean localizeHostLoc(IAD_Location tgtLocation,
                               java.lang.String szIOPrefix,
                               int nDepth)
Adjusts the target port location URL to match that of the default local host (where URL string is currently null).
NOTE: This method discovers the network local host setings during its first execution call().
Parameters:
tgtLocation - -- The target port location object reference.
szIOPrefix - -- The port ID string echoed to the console (debug).
nDepth - -- The method call stack depth integer for the debug echo display.
Returns:
Success -- true.
Failure -- False.

getObjectRMI_SzBinding

public java.lang.String getObjectRMI_SzBinding(IAD_Location tgtLocation,
                                               java.lang.String szRMI_BindingLabel)
Builds an RMI object binding string from the input port location and the Object binding label (the objects RMI look-up string).
NOTE: If the input tgtLocation reference is NULL, then the binding string references the current network local host parameters.
Parameters:
tgtLocation - -- The input port location object reference.
szRMI_BindingLabel - -- The input object binding label string reference.
Returns:
An RMI object binding string reference.