com.tivoli.twg.libs
Class ServiceNode

java.lang.Object
  |
  +--com.tivoli.twg.libs.ServiceNode
All Implemented Interfaces:
java.lang.Runnable
Direct Known Subclasses:
SNMPRemoteRequest, TWGConsoleServiceNode, TWGRemoteSNMP, TWGServerServiceNode

public class ServiceNode
extends java.lang.Object
implements java.lang.Runnable

ServiceNode is the base class for defining Director transport interfaces. This class actually abstracts the creation of a environment-specific version of the ServiceNode class, which contains the actual functional components of the class.


Field Summary
static int SVCNODE_DISABLE_TRACING_CMD
           
static int SVCNODE_ENABLE_TRACING_CMD
           
static int SVCNODE_GET_STATUS_CMD
           
static int SVCNODE_KILL_SERVICE_CMD
           
 
Constructor Summary
ServiceNode()
          Constructor for ServiceNode.
ServiceNode(com.tivoli.twg.libs.ServiceNodeImpl imp)
          Deprecated.  
ServiceNode(com.tivoli.twg.libs.ServiceNodeImpl imp, boolean is_raw, boolean make_thrd)
          Deprecated.  
ServiceNode(java.lang.String sn_name)
          Constructor for ServiceNode.
ServiceNode(java.lang.String sn_name, boolean make_thrd)
          Constructor for ServiceNode.
ServiceNode(java.lang.String sn_name, boolean make_thrd, boolean is_raw)
          Constructor for ServiceNode.
 
Method Summary
 boolean Close()
          Close and detach the ServiceNode.
 boolean CommandReceived(Command cmd)
          Callback for processing any Commands received by the ServiceNode (if in cooked mode (default)).
static boolean ConnectionActive(java.lang.String name)
          Test to see if a ServiceNode with the given name is currently active.
 boolean Create()
          Test to see if ServiceNode was created successfully.
 void DeregisterCommandListener(long cmd_code)
          Deregister a command-received listener for a given command code.
 void DeregisterDefaultCommandListener()
          Deregister the default command-received listener.
 void EnqueueCommandFail(long cmd_id, long rc)
          Enqueue command failure reply : used by ServiceNodeImpl to deliver generic command failures with no parameters
 void EnqueueReceiveBuffer(byte[] data, int start, int length)
          Enqueue receive buffer : used by ServiceNodeImpl to deliver data
static java.lang.String formatCommandCode(Command c)
           
static java.lang.String formatReturnCode(Command c)
           
static int GetFeatureFlags()
          Get global feature flags for local (or server) system.
static ServiceNodeImplFactory GetServiceNodeFactory()
          Get default factory object to use for creating our ServiceNodeImpl
static java.lang.String getTS()
           
 boolean IsActive()
          Get active state of ServiceNode.
 boolean IsRawMode()
          Test ServiceNode for Raw mode.
static byte[] LocalMACAddress()
          Return local (or server, if proxy) MAC address, as byte[6]
static byte[][] LocalMacAddressList()
           
static java.lang.String LocalSystemName()
          Return local system's name (or server name, for proxy).
static byte[] LocalUniqueID()
          Return local (or server, if proxy) unique ID, as byte[8].
 java.lang.String Name()
          Return name of service node
 boolean PeriodicCallback()
          Callback method for periodic callback (set using SetPeriodicCallback()) Default does nothing.
 void ProcessCommands()
          Method called to handle processing for the ServiceNode (if a processing thread was not created).
 void ReceiveData(byte[] data, int start, int length)
          Callback for raw-mode data receive.
static void RegisterAsServiceBase()
          Register this process as a "service base" process, which should not be terminated if the user logs off the system (i.e.
 void RegisterCommandListener(long cmd_code, CommandReceivedListener listener)
          Register a command-received listener for a given command code.
 void RegisterDefaultCommandListener(CommandReceivedListener listener)
          Register the default command-received listener.
 void run()
           
 boolean SendAsynchCommand(Command cmd)
          Send command without waiting for command reply.
 boolean SendBuffer(byte[] data, int start, int length)
          Send method for raw-mode ServiceNode.
 boolean SendCommand(Command cmd)
          Send command and wait for reply before returning.
 boolean SendLocalAsyncCommand(Command cmd)
          Send a command to destination ServiceNode that is within the same JVM as the source ServiceNode without waiting for a reply.
 boolean SendLocalCommand(Command cmd)
          Send a command to destination ServiceNode that is within the same JVM as the source ServiceNode and waits for a reply.
 boolean SendPostponedReply(Command cmd)
          Send a postponed Command which is ready to be sent.
 void SetActive(boolean active)
          Set active state of ServiceNode.
 void setCommandDebugString(long cc, java.lang.String debug_str)
          Set command debug string for given command code
static void SetFeatureFlags(int flags)
          Set global feature flags for local (or server) system.
static void SetGlobalNetworkTimeout(int timeout)
          Set global default timeout for Commands.
static void SetLocalSystemName(java.lang.String name)
          Set local system's name (or server name, for proxy).
 void SetPeriodicCallback(int period_msec)
          Sets interval for periodic callback, in msec.
static void SetServiceNodeFactory(ServiceNodeImplFactory factory)
          Set default factory object to use for creating our ServiceNodeImpl
 void ThreadInit()
          Callback method called when processing thread has begun processing Default method does nothing, but ServiceNode subclasses can provide their own version.
 void ThreadTerm()
          Callback method called when processing thread has finished processing Default method does nothing, but ServiceNode subclasses can provide their own version.
 java.lang.String toString()
          Returns a string representation of the object.
 void traceCommandCompleteCall(Command c, int cn, java.lang.String identifier)
           
 void traceCommandReceived(Command c, java.lang.String identifier)
           
 void traceCommandReceivedReturn(Command c, java.lang.String identifier)
           
 void traceCommandSend(Command c, java.lang.String identifier)
           
 void traceError(Command c, java.lang.String message)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

SVCNODE_ENABLE_TRACING_CMD

public static final int SVCNODE_ENABLE_TRACING_CMD

SVCNODE_DISABLE_TRACING_CMD

public static final int SVCNODE_DISABLE_TRACING_CMD

SVCNODE_GET_STATUS_CMD

public static final int SVCNODE_GET_STATUS_CMD

SVCNODE_KILL_SERVICE_CMD

public static final int SVCNODE_KILL_SERVICE_CMD
Constructor Detail

ServiceNode

public ServiceNode(java.lang.String sn_name,
                   boolean make_thrd,
                   boolean is_raw)
            throws BadServiceNodeImplException,
                   ServiceNodeClosedException,
                   ServiceNodeException
Constructor for ServiceNode. Create ServiceNode with given name, and given raw/cooked state. The ServiceNode will optionally create its own processing thread, if requested. Raw ServiceNodes return data using the SendBuffer() and ReceiveData() methods, which cooked ones use SendxxxCommand and CommandReceived().
Parameters:
sn_name - - name string
make_thrd - - true means that ServiceNode will create its own processing thread, false means that the user will call ProcessCommands()
is_raw - - ServiceNode is raw if true, else its cooked mode
Throws:
BadServiceNodeImplException - - if no ServiceNodeImplFactory defined
ServiceNodeClosedException - - if ServiceNode failed to open
ServiceNodeException - if other problem occurs

ServiceNode

public ServiceNode(java.lang.String sn_name,
                   boolean make_thrd)
            throws BadServiceNodeImplException,
                   ServiceNodeClosedException,
                   ServiceNodeException
Constructor for ServiceNode. Create ServiceNode with given name. Optionally, the ServiceNode will create its own processing thread. The ServiceNode will be in cooked mode.
Parameters:
sn_name - - name string
make_thrd - - true means that ServiceNode will create its own processing thread, false means that the user will call ProcessCommands()
Throws:
BadServiceNodeImplException - - if no ServiceNodeImplFactory defined
ServiceNodeClosedException - - if ServiceNode failed to open
ServiceNodeException - if other problem occurs

ServiceNode

public ServiceNode(java.lang.String sn_name)
            throws BadServiceNodeImplException,
                   ServiceNodeClosedException,
                   ServiceNodeException
Constructor for ServiceNode. Create ServiceNode with given name. The ServiceNode will create its own processing thread, and will be in cooked mode.
Parameters:
sn_name - - name string
Throws:
BadServiceNodeImplException - - if no ServiceNodeImplFactory defined
ServiceNodeClosedException - - if ServiceNode failed to open
ServiceNodeException - if other problem occurs

ServiceNode

public ServiceNode()
            throws BadServiceNodeImplException,
                   ServiceNodeClosedException,
                   ServiceNodeException
Constructor for ServiceNode. Name of service node will be a unique generated name. The ServiceNode will create its own processing thread, and will be in cooked mode.
Throws:
BadServiceNodeImplException - - if no ServiceNodeImplFactory defined
ServiceNodeClosedException - - if ServiceNode failed to open
ServiceNodeException - if other problem occurs

ServiceNode

public ServiceNode(com.tivoli.twg.libs.ServiceNodeImpl imp,
                   boolean is_raw,
                   boolean make_thrd)
            throws ServiceNodeClosedException
Deprecated.  

Constructor for ServiceNode. Uses caller-provided ServiceNodeImpl instance ServiceNode will be in specified mode.
Parameters:
imp - - user-provided ServiceNodeImpl
is_raw - - Set to raw (true) or cooked (false) mode
make_thrd - - true means that ServiceNode will create its own processing thread, false means that the user will call ProcessCommands()
Throws:
ServiceNodeClosedException - - if ServiceNode failed to open

ServiceNode

public ServiceNode(com.tivoli.twg.libs.ServiceNodeImpl imp)
            throws ServiceNodeClosedException
Deprecated.  

Constructor for ServiceNode. Uses caller-provided ServiceNodeImpl instance ServiceNode will be in cooked mode.
Parameters:
imp - - user-provided ServiceNodeImpl
Throws:
ServiceNodeClosedException - - if ServiceNode failed to open
Method Detail

Close

public boolean Close()
              throws ServiceNodeException
Close and detach the ServiceNode. This method MUST be called to cause the ServiceNode to delete, as there are non-user references to the ServiceNode object as long as it is opened.
Throws:
ServiceNodeException - if other problem occurs

Name

public java.lang.String Name()
                      throws ServiceNodeClosedException
Return name of service node
Returns:
String service node name
Throws:
ServiceNodeClosedException - - if ServiceNode is closed

toString

public java.lang.String toString()
Returns a string representation of the object.
Overrides:
toString in class java.lang.Object
See Also:
Object.toString()

Create

public boolean Create()
Test to see if ServiceNode was created successfully.
Returns:
true if OK, false if closed

IsRawMode

public boolean IsRawMode()
                  throws ServiceNodeClosedException
Test ServiceNode for Raw mode.
Returns:
true if ServiceNode is in raw mode
Throws:
ServiceNodeClosedException - - if ServiceNode is closed

CommandReceived

public boolean CommandReceived(Command cmd)
Callback for processing any Commands received by the ServiceNode (if in cooked mode (default)). This method does nothing, so any ServiceNode instance which needs to process commands should subclass ServiceNode and provide a custom version of this method. If the method returns false, the ServiceNode will be closed, else processing will continue normally.
Returns:
true if ServiceNode should continue processing, or false if it should be closed.

ProcessCommands

public void ProcessCommands()
                     throws ServiceNodeClosedException,
                            ServiceNodeException,
                            java.lang.InterruptedException
Method called to handle processing for the ServiceNode (if a processing thread was not created). Method doesn't return until the ServiceNode is closed).
Throws:
ServiceNodeClosedException - - if ServiceNode is closed
ServiceNodeException - for processing errors
java.lang.InterruptedException - if thread is interrupted

EnqueueReceiveBuffer

public void EnqueueReceiveBuffer(byte[] data,
                                 int start,
                                 int length)
                          throws ServiceNodeClosedException
Enqueue receive buffer : used by ServiceNodeImpl to deliver data
Parameters:
data - - byte[] containing packet
start - - index in data of start of packet
length - - length of packet
Throws:
ServiceNodeClosedException - if ServiceNode is closed

EnqueueCommandFail

public void EnqueueCommandFail(long cmd_id,
                               long rc)
                        throws ServiceNodeClosedException
Enqueue command failure reply : used by ServiceNodeImpl to deliver generic command failures with no parameters
Parameters:
cmd_id - - command ID of failed command
rc - - return code for failed command
Throws:
ServiceNodeClosedException - if ServiceNode is closed

ConnectionActive

public static boolean ConnectionActive(java.lang.String name)
                                throws BadServiceNodeImplException,
                                       ServiceNodeException
Test to see if a ServiceNode with the given name is currently active.
Parameters:
name - - Name of ServiceNode to check
Returns:
true if ServiceNode exists, or false if it does not exist
Throws:
BadServiceNodeImplException - if no ServiceNodeImplFactory defined.
ServiceNodeException - if other problem occurs

SendAsynchCommand

public boolean SendAsynchCommand(Command cmd)
                          throws ServiceNodeClosedException,
                                 ServiceNodeException,
                                 java.lang.InterruptedException
Send command without waiting for command reply.
Parameters:
cmd - - Command to be sent through ServiceNode
Throws:
ServiceNodeClosedException - if ServiceNode is closed
ServiceNodeException - for other problems
java.lang.InterruptedException - if thread interrupted while waiting

SendCommand

public boolean SendCommand(Command cmd)
                    throws ServiceNodeClosedException,
                           ServiceNodeException,
                           java.lang.InterruptedException
Send command and wait for reply before returning.
Parameters:
cmd - - Command to be sent through ServiceNode
Throws:
ServiceNodeClosedException - if ServiceNode is closed
ServiceNodeException - for other problems
java.lang.InterruptedException - if thread interrupted while waiting

SendLocalAsyncCommand

public boolean SendLocalAsyncCommand(Command cmd)
                              throws ServiceNodeClosedException,
                                     ServiceNodeException,
                                     java.lang.InterruptedException
Send a command to destination ServiceNode that is within the same JVM as the source ServiceNode without waiting for a reply. If the destination ServiceNode is not within the same JVM as the source, then method defaults to SendAsynchCommand(). SendLocalAsyncCommand is faster than SendAsychCommand when sending commands within the same JVM. However, since the actual Command object is enqueued to the destination, the Command should not be modified or resent until after CommandComplete() has finished. If a Command is resent before it has completed, the method returns false.
Parameters:
cmd - - Command to be sent through ServiceNode
Throws:
ServiceNodeClosedException - if ServiceNode is closed
ServiceNodeException - for other problems
java.lang.InterruptedException - if thread interrupted while waiting

SendLocalCommand

public boolean SendLocalCommand(Command cmd)
                         throws ServiceNodeClosedException,
                                ServiceNodeException,
                                java.lang.InterruptedException
Send a command to destination ServiceNode that is within the same JVM as the source ServiceNode and waits for a reply. If the destination ServiceNode is not within the same JVM as the source, then method defaults to SendCommand(). SendLocalCommand is faster than SendCommand when sending commands within the same JVM. However, since the actual Command object is enqueued to the destination, the Command should not be modified or resent until after CommandComplete() has finished. If a Command is resent before it has completed, the method returns false.
Parameters:
cmd - - Command to be sent through ServiceNode
Throws:
ServiceNodeClosedException - if ServiceNode is closed
ServiceNodeException - for other problems
java.lang.InterruptedException - if thread interrupted while waiting

ThreadInit

public void ThreadInit()
Callback method called when processing thread has begun processing Default method does nothing, but ServiceNode subclasses can provide their own version. NOTE: This method may be called more than once per ServiceNode instance. Beware of overriding this method when constructing ServiceNode using make_thrd = true, i.e. letting the ServiceNode construct the processing thread.

ThreadTerm

public void ThreadTerm()
Callback method called when processing thread has finished processing Default method does nothing, but ServiceNode subclasses can provide their own version. NOTE: This method may be called more than once per ServiceNode instance. Beware of overriding this method when constructing ServiceNode using make_thrd = true, i.e. letting the ServiceNode construct the processing thread. For example, it is called each time the ServiceNode-owned thread goes idle. If cleanup is required by the ServiceNode extension when the ServiceNode terminates, override the Close() method.

SendPostponedReply

public boolean SendPostponedReply(Command cmd)
                           throws ServiceNodeClosedException,
                                  ServiceNodeException
Send a postponed Command which is ready to be sent.
Parameters:
cmd - - Postponed Command to be sent
Throws:
ServiceNodeClosedException - if ServiceNode is closed
ServiceNodeException - for other problems

ReceiveData

public void ReceiveData(byte[] data,
                        int start,
                        int length)
Callback for raw-mode data receive. Default method does nothing, but subclasses of ServiceNode can provide versions which handle the received data.
Parameters:
data - - byte[] containing data received
start - - index in 'data' of start of data packet received
length - - number of bytes in data packet received

SendBuffer

public boolean SendBuffer(byte[] data,
                          int start,
                          int length)
                   throws ServiceNodeClosedException,
                          ServiceNodeException
Send method for raw-mode ServiceNode.
Parameters:
data - - byte[] containing data to be sent
start - - index in data of start of data packet to send
length - - number of bytes in data packet to send
Throws:
ServiceNodeClosedException - if ServiceNode is closed
ServiceNodeException - for other problems

SetGlobalNetworkTimeout

public static void SetGlobalNetworkTimeout(int timeout)
                                    throws BadServiceNodeImplException,
                                           ServiceNodeException
Set global default timeout for Commands.
Parameters:
timeout - - default time-out, in milliseconds
Throws:
BadServiceNodeImplException - if no ServiceNodeImplFactory
ServiceNodeException - for other problems

LocalSystemName

public static java.lang.String LocalSystemName()
                                        throws BadServiceNodeImplException,
                                               ServiceNodeException
Return local system's name (or server name, for proxy).
Returns:
string for system's name
Throws:
BadServiceNodeImplException - if no ServiceNodeImplFactory
ServiceNodeException - for other problems

SetLocalSystemName

public static void SetLocalSystemName(java.lang.String name)
                               throws BadServiceNodeImplException,
                                      ServiceNodeException
Set local system's name (or server name, for proxy).
Parameters:
name - - string for system's name
Throws:
BadServiceNodeImplException - if no ServiceNodeImplFactory
ServiceNodeException - for other problems

LocalMACAddress

public static byte[] LocalMACAddress()
                              throws BadServiceNodeImplException,
                                     ServiceNodeException
Return local (or server, if proxy) MAC address, as byte[6]
Returns:
MAC address, as byte[6]. If not available, all bytes will be zero.
Throws:
BadServiceNodeImplException - if no ServiceNodeImplFactory
ServiceNodeException - for other problems

LocalMacAddressList

public static byte[][] LocalMacAddressList()
                                    throws BadServiceNodeImplException,
                                           ServiceNodeException

LocalUniqueID

public static byte[] LocalUniqueID()
                            throws BadServiceNodeImplException,
                                   ServiceNodeException
Return local (or server, if proxy) unique ID, as byte[8]. If not available, null will be returned.
Returns:
byte[8] containing unique ID
Throws:
BadServiceNodeImplException - if no ServiceNodeImplFactory
ServiceNodeException - for other problems

PeriodicCallback

public boolean PeriodicCallback()
Callback method for periodic callback (set using SetPeriodicCallback()) Default does nothing. Subclasses should replace.
Returns:
true if ServiceNode processing should continue, or false to close ServiceNode

SetPeriodicCallback

public void SetPeriodicCallback(int period_msec)
                         throws ServiceNodeClosedException
Sets interval for periodic callback, in msec. Period is approximated to nearest 2 seconds (round up). 0 = disable
Parameters:
period_msec - - period, in msec (0 = disabled)
Throws:
ServiceNodeClosedException - if ServiceNode is closed

RegisterAsServiceBase

public static void RegisterAsServiceBase()
                                  throws BadServiceNodeImplException,
                                         ServiceNodeException
Register this process as a "service base" process, which should not be terminated if the user logs off the system (i.e. Win95) Should be called for any "base" process.
Throws:
BadServiceNodeImplException - if no ServiceNodeImplFactory
ServiceNodeException - for other problems

GetFeatureFlags

public static int GetFeatureFlags()
                           throws BadServiceNodeImplException,
                                  ServiceNodeException
Get global feature flags for local (or server) system.
Returns:
feature flags, as int
Throws:
BadServiceNodeImplException - if no ServiceNodeImplFactory
ServiceNodeException - for other problems

SetFeatureFlags

public static void SetFeatureFlags(int flags)
                            throws BadServiceNodeImplException,
                                   ServiceNodeException
Set global feature flags for local (or server) system.
Parameters:
flags - - feature flags, as int
Throws:
BadServiceNodeImplException - if no ServiceNodeImplFactory
ServiceNodeException - for other problems

SetActive

public void SetActive(boolean active)
               throws ServiceNodeClosedException,
                      ServiceNodeException
Set active state of ServiceNode. When not active, a ServiceNode will not process received Commands.
Parameters:
active - - if true, set to active, else set to inactive
Throws:
ServiceNodeClosedException - if service node is closed
ServiceNodeException - for other problems

IsActive

public boolean IsActive()
                 throws ServiceNodeClosedException
Get active state of ServiceNode.
Returns:
true, if ServiceNode is active
Throws:
ServiceNodeClosedException - if service node is closed

SetServiceNodeFactory

public static void SetServiceNodeFactory(ServiceNodeImplFactory factory)
Set default factory object to use for creating our ServiceNodeImpl
Parameters:
factory - - ServiceNodeImplFactory to use as default

RegisterCommandListener

public void RegisterCommandListener(long cmd_code,
                                    CommandReceivedListener listener)
Register a command-received listener for a given command code. This will replace any existing listener for the given command code.
Parameters:
cmd_code - - command code to be listened for
listener - - CommandReceivedListener to be registered

DeregisterCommandListener

public void DeregisterCommandListener(long cmd_code)
Deregister a command-received listener for a given command code.
Parameters:
cmd_code - - command code to have listener deregistered

RegisterDefaultCommandListener

public void RegisterDefaultCommandListener(CommandReceivedListener listener)
Register the default command-received listener. This will be called when no command-code specific listener matches a received command.
Parameters:
listener - - CommandReceivedListener to be registered

DeregisterDefaultCommandListener

public void DeregisterDefaultCommandListener()
Deregister the default command-received listener.

GetServiceNodeFactory

public static ServiceNodeImplFactory GetServiceNodeFactory()
Get default factory object to use for creating our ServiceNodeImpl
Returns:
ServiceNodeImplFactory used as default

run

public void run()
Specified by:
run in interface java.lang.Runnable

setCommandDebugString

public void setCommandDebugString(long cc,
                                  java.lang.String debug_str)
Set command debug string for given command code
Parameters:
cc - - command code
debug_str - - debug string

getTS

public static java.lang.String getTS()

formatCommandCode

public static java.lang.String formatCommandCode(Command c)

formatReturnCode

public static java.lang.String formatReturnCode(Command c)

traceCommandReceived

public void traceCommandReceived(Command c,
                                 java.lang.String identifier)

traceCommandReceivedReturn

public void traceCommandReceivedReturn(Command c,
                                       java.lang.String identifier)

traceCommandSend

public void traceCommandSend(Command c,
                             java.lang.String identifier)

traceCommandCompleteCall

public void traceCommandCompleteCall(Command c,
                                     int cn,
                                     java.lang.String identifier)

traceError

public void traceError(Command c,
                       java.lang.String message)