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:

• A server (IRR_ObjectServerBase or extension class) object
  (defines the who, what, where, and how of IMPACT message communications).
• A message queue (IA_MessageQueue class) object
  (handles message addressing and synchronization).
• A queue monitor thread (IRR_QMonitor class) object
  (directs the bi-directional message flow).

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:

• parseArgs() -- Parses command-line arguments into IOS initialization parameters. These parameters include:
• "-N" -- IOS Name assignment.
• "-PW" -- IOS Password assignment.
• "-SM" -- Load RMI security manager (on boot-up).
• "-YP" -- IMPACT Yellow-Pages server address setup.
• "-H" -- IOS Host address setup.
• "-MI" -- IOS Monitor interval (milliseconds)
• "-D" -- IOS Debug mode.
• "-EA" -- IOS echo-answer mode.
• "-ES" -- IOS echo-status mode.
• "-LM" -- IOS message logging mode.
• "-LT" -- IOS code-timing mode.
• "-?" -- Dump IOS parameter explaination to console.
• setDefaultFrontEndAgent() -- Registers (associates) a single "agent" as the IOS communications representative (commonly used for simple external client interfaces).
• registerInitialAgents() -- Registers (associates) multiple agents with the IOS (an IMPACT Roost typically uses this on boot-up).
• setQMonitor() -- Installs an alternate IRR_QMonitor class
  (call-back methods are defined there).
• terminateMonitor() -- Prompts the underlying QMonitor to terminate it's monitor loop.
• run() -- A predefined routine which invokes the underlying connect(), registerInitialAgents(), and disconnect() methods.

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.