VisiBroker for Java Developer’s Guide : Using the Smart Agent

Using the Smart Agent
This section describes the Smart Agent (osagent), which client programs register with in order to find object implementations. It explains how to configure your own VisiBroker ORB domain, connect Smart Agents on different local networks, and migrate objects from one host to another.
What is the Smart Agent?
VisiBroker's Smart Agent (osagent) is a dynamic, distributed directory service that provides facilities used by both client programs and object implementations. A Smart Agent must be started on at least one host within your local network. When your client program invokes bind() on an object, the Smart Agent is automatically consulted. The Smart Agent locates the specified implementation so that a connection can be established between the client and the implementation. The communication with the Smart Agent is completely transparent to the client program.
If the PERSISTENT policy is set on the POA, and activate_object_with_id is used, the Smart Agent registers the object or implementation so that it can be used by client programs. When an object or implementation is deactivated, the Smart Agent removes it from the list of available objects. Like client programs, the communication with the Smart Agent is completely transparent to the object implementation. For more information about POAs, see “Using POAs”.
Best practices for Smart Agent configuration and synchronization
While the Smart Agent imposes no hard limits on the numbers and types of objects that it can support, there are reasonable best practices that can be followed when incorporating it into a larger architecture.
The Smart Agent is designed to be a lightweight directory service with a flat, simple namespace, which can support a small number of well known objects within a local network.
Since all objects' registered services are stored in memory, scalability cannot be optimized and be fault tolerant at the same time. Applications should use well known objects to bootstrap to other distributed services so as not to rely on the Smart Agent for all directory needs. If a heavy services lookup load is necessary, it is advisable to use the VisiBroker Naming Service (VisiNaming). VisiNaming provides persistent storage capability and cluster load balancing whereas the Smart Agent only provides a simple round robin on a per osagent basis. Due to the in-memory design of the Smart Agent, if it is terminated by a proper shutdown or an abnormal termination, it does not failover to another Smart Agent in the same ORB domain, that is to the same OSAGENT_PORT number, whereas the VisiNaming Service provides such failover functionality. For more information on the VisiBroker naming service, see “Using the VisiNaming Service”.
General guidelines
The following are some general guidelines for best practice Smart Agent usage.
Note
The GateKeeper counts as one client even though it is acting on behalf of many real clients.
Load balancing/ fault tolerance guidelines
Location service guidelines
The location service is built upon the Smart Agent technology. Therefore, the location service is subject to the same guidelines described above.
For more information about the Location Service, see “Using the Location Service”.
When not to use a Smart Agent
When the ORB domain spans a large number (greater than 5) of subnets. Maintaining the agentaddr files for a large ORB domain spread over a large number of subnets is difficult to manage.
Note
In the above situations an alternative directory, such as the Naming Service, may be more appropriate. See “Using the VisiNaming Service” for more information.
Locating Smart Agents
VisiBroker locates a Smart Agent for use by a client program or object implementation using a broadcast message. The first Smart Agent to respond is used. After a Smart Agent has been located, a point-to-point UDP connection is used for sending registration and look-up requests to the Smart Agent.
The UDP protocol is used because it consumes fewer network resources than a TCP connection. All registration and locate requests are dynamic, so there are no required configuration files or mappings to maintain.
Note
Broadcast messages are used only to locate a Smart Agent. All other communication with the Smart Agent makes use of point-to-point communication. For information on how to override the use of broadcast messages, see “Using point-to-point communications”.
Locating objects through Smart Agent cooperation
When a Smart Agent is started on more than one host in the local network, each Smart Agent will recognize a subset of the objects available and communicate with other Smart Agents to locate objects it cannot find. If one of the Smart Agent processes should terminate unexpectedly, all implementations registered with that Smart Agent discover this event and they will automatically re register with another available Smart Agent.
Cooperating with the OAD to connect with objects
Object implementations may be registered with the Object Activation Daemon (OAD) so they can be started on demand. Such objects are registered with the Smart Agent as if they are actually active and located within the OAD. When a client requests one of these objects, it is directed to the OAD. The OAD then forwards the client request to the actual server. The Smart Agent does not know that the object implementation is not truly active within the OAD. For more information about the OAD, see “Using the Object Activation Daemon (OAD)”.
Starting a Smart Agent (osagent)
At least one instance of the Smart Agent should be running on a host in your local network. Local network refers to a subnetwork in which broadcast messages can be sent.
Windows
To start the Smart Agent:
<install_dir\bin\
or
At the Command Prompt, enter: osagent [options]. For example:
prompt> osagent [options]
UNIX
To start the Smart Agent, enter: osagent &. For example:
prompt> osagent &
Note
Because of signal handling changes, Bourne and Korn shell users need to use the ignoreSignal hup parameter when starting osagent in order to prevent the hangup (hup) signal from terminating the process when the user logs out. For example:
nohup $VBROKERDIR/bin/osagent ignoreSignal hup &
The osagent command accepts the following command line arguments:
-p <UDP_port>
Overrides the setting of OSAGENT_PORT and the registry setting.
-help or -?
Turns off logging if OSAGENT_LOGGING_ON is set.
-ls <size>
+l <options>
o - Turn logging on. This is equivalent to setting logging level i and above (== +1 oi) where messages from “Fatal” to “Informational” will be logged. Alternatively logging can be enabled using the environment variable OSAGENT_LOGGING_ON. Logs are auto-trim and are written to OSAGENT_LOG_DIR or VBROKER_ADM directory if set. Otherwise the default is to /tmp on UNIX and %TEMP% on Windows.
f - Fatal
e - Error
w - Warning
i - Informational
d - Debugging
a - All
s - Suspend logging temporarily. Send the signal SIGUSR1 to toggle between suspend and resume. This option is available on UNIX/Linux platforms only.
Example
The following example of the osagent command specifies a particular UDP port:
osagent -p 17000
Verbose output
UNIX
On UNIX, the verbose output is sent to stdout.
Windows
On Windows, the verbose output is written to a log file stored in either of the following locations:
the directory specified by the VBROKER_ADM environment variable.
Note
To specify a different directory in which to write the log file, use OSAGENT_LOG_DIR. To configure logging options you can right-click the Smart Agent icon and select Log Options.
Disabling the agent
Communication with the Smart Agent can be disabled by passing the VisiBroker ORB the following property at runtime:
prompt> vbj -Dvbroker.agent.enableLocator=false
If using string-to-object references, a naming service, or passing in a URL reference, the Smart Agent is not required and can be disabled. If you pass an object name to the bind() method, you must use the Smart Agent.
Ensuring Smart Agent availability
Starting a Smart Agent on more than one host within the local network allows clients to continually bind to objects, even if one Smart Agent terminates unexpectedly. If a Smart Agent becomes unavailable, all object implementations registered with that Smart Agent will be automatically re-registered with another Smart Agent. If no Smart Agents are running on the local network, object implementations will continue retrying until a new Smart Agent is contacted.
If a Smart Agent terminates, any connections between a client and an object implementation established before the Smart Agent terminated will continue without interruption. However, any new bind() requests issued by a client causes a new Smart Agent to be contacted.
No special coding techniques are required to take advantage of these fault-tolerant features. You only need to be sure a Smart Agent is started on one or more host on the local network.
Checking client existence
A Smart Agent sends an “are you alive” message (often called a heartbeat message) to its clients every two minutes to verify the client is still connected. If the client does not respond, the Smart Agent assumes the client has terminated the connection.
You can not change the interval for polling the client.
Note
The use of the term “client” does not necessarily describe the function of the object or process. Any program that connects to the Smart Agent for object references is a client.
Working within VisiBroker ORB domains
It is often useful to have two or more VisiBroker ORB domains running at the same time. One domain might consist of production versions of client programs and object implementations, while another domain might consist of test versions of the same clients and objects that have not yet been released for general use. If several developers are working on the same local network, each may want to establish their own VisiBroker ORB domain so that their tests do not conflict with one another.
Figure 18
VisiBroker allows you to distinguish between multiple VisiBroker ORB domains on the same network by using unique UDP port numbers for the Smart Agents of each domain. By default, the OSAGENT_PORT variable is set to 14000. If you wish to use a different port number, check with your system administrator to determine what port numbers are available.
To override the default setting, the OSAGENT_PORT variable must be set accordingly before running a Smart Agent, an OAD, object implementations, or client programs assigned to that VisiBroker ORB domain. For example,
prompt> setenv OSAGENT_PORT 5678
prompt> osagent &
prompt> oad &
The Smart Agent uses an additional internal port number for both TCP and UDP protocols, the port number is the same for both. This port number is set by using the OSAGENT_CLIENT_HANDLER_PORT environment variable.
Connecting Smart Agents on different local networks
If you start multiple Smart Agents on your local network, they will discover each other by using UDP broadcast messages. Your network administrator configures a local network by specifying the scope of broadcast messages using the IP subnet mask. The following figure shows two local networks connected by a network link.
Figure 19
To allow the Smart Agent on one network to contact a Smart Agent on another local network, use the OSAGENT_ADDR_FILE environment variable, as shown in the following example:
setenv OSAGENT_ADDR_FILE=<path to agent addr file>
Alternatively, use the vbroker.agent.addrFile property, as shown in the following example:
vbj -Dvbroker.agent.addrFile=<path to agent addr file> ....
The following example shows what the agentaddr file would contain to allow a Smart Agent on Local Network #1 to connect to a Smart Agent on another local network.
101.10.2.6
With the appropriate agentaddr file, a client program on Network #1 locates and uses object implementations on Network #2. For more information on environment variables, see the VisiBroker Installation Guide.
Note
If a remote network has multiple Smart Agents running, you should list all the IP addresses of the Smart Agents on the remote network.
How Smart Agents detect each other
Suppose two agents, Agent 1 and Agent 2, are listening on the same UDP port from two different machines on the same subnet. Agent 1 starts before Agent 2. The following events occur:
If Agent 2 is terminated gracefully (such as killing with Ctrl+C), Agent 1 is notified that Agent 2 is no longer available.
Working with multihomed hosts
When you start the Smart Agent on a host that has more than one IP address (known as a multihomed host), it can provide a powerful mechanism for bridging objects located on separate local networks. All local networks to which the host is connected will be able to communicate with a single Smart Agent, therefore bridging the local networks.
Figure 20
UNIX
On a multihomed UNIX host, the Smart Agent dynamically configures itself to listen and broadcast on all of the host's interfaces which support point-to-point connections or broadcast connections. You can explicitly specify interface settings using the localaddr file as described in “Specifying interface usage for Smart Agents”.
Windows
On a multihomed Windows host, the Smart Agent is not able to dynamically determine the correct subnet mask and broadcast address values. To overcome this limitation, you must explicitly specify the interface settings you want the Smart Agent to use with the localaddr file.
When you start the Smart Agent with the -v (verbose) option, each interface that the Smart Agent uses will be listed at the beginning of the messages produced. The example below shows the sample output from a Smart Agent started with the verbose option on a multihomed host.
Bound to the following interfaces:
Address: 199.10.9.5 Subnet: 255.255.255.0 Broadcast:199.10.9.255
Address: 101.10.2.6 Subnet: 255.255.255.0 Broadcast:101.10.2.255
...
The above output shows the address, subnet mask, and broadcast address for each interface in the machine.
UNIX
The above output should match the results from the UNIX command ifconfig -a.
If you want to override these settings, configure the interface information in the localaddr file. See “Specifying interface usage for Smart Agents” for details.
Specifying interface usage for Smart Agents
Note
It is not necessary to specify interface information on a single-homed host.
You can specify interface information for each interface you wish the Smart Agent to use on your multihomed host in the localaddr file. The localaddr file should have a separate line for each interface that contains the host's IP address, subnet mask, and broadcast address. By default, VisiBroker searches for the localaddr file in the VBROKER_ADM directory. You can override this location by setting the OSAGENT_LOCAL_FILE environment variable to point to this file. Lines in this file that begin with a “#” character, and are treated as comments and ignored.
The code sample below shows the contents of the localaddr file for the multihomed host listed above:
#entries of format <address> <subnet_mask> <broadcast address>
199.10.9.5 255.255.255.0 199.10.9.255
101.10.2.6 255.255.255.0 101.10.2.255
UNIX
Though the Smart Agent can automatically configure itself on a multihomed host on UNIX, you can use the localaddr file to explicitly specify the interfaces that your host contains. You can display all available interface values for the UNIX host by using the following command:
prompt> ifconfig -a
Output from this command appears similar to the following:
lo0: flags=849<UP,LOOPBACK,RUNNING,MULTICAST> mtu 8232
inet 127.0.0.1 netmask ff000000
le0: flags=863<UP,BROADCAST,NOTRAILERS,RUNNING,MULTICAST> mtu 1500
inet 199.10.9.5 netmask ffffff00 broadcast 199.10.9.255
le1: flags=863<UP,BROADCAST,NOTRAILERS,RUNNING,MULTICAST> mtu 1500
inet 101.10.2.6 netmask ffffff00 broadcast 101.10.2.255
Windows
The use of the localaddr file with multihomed hosts is required for hosts running Windows because the Smart Agent is not able to automatically configure itself. You can obtain the appropriate values for this file by accessing the TCP/IP protocol properties from the Network Control Panel. If your host is running Windows, the ipconfig command will provide the needed values. This command is as follows:
prompt> ipconfig
Output from this command appears similar to the following:
Ethernet adapter El90x1:
IP Address. . . . . . . . . : 172.20.30.56
Subnet Mask . . . . . . . . : 255.255.255.0
Default Gateway . . . . . . : 172.20.0.2
Ethernet adapter Elnk32:
IP Address. . . . . . . . . : 101.10.2.6
Subnet Mask . . . . . . . . : 255.255.255.0
Default Gateway. . . . . . . : 101.10.2.1
Using point-to-point communications
VisiBroker provides three different mechanisms for circumventing the use of UDP broadcast messages for locating Smart Agent processes. When a Smart Agent is located with any of these alternate approaches, that Smart Agent will be used for all subsequent interactions. If a Smart Agent cannot be located using any of these alternate approaches, VisiBroker will revert to using the broadcast message scheme to locate a Smart Agent.
Specifying a host as a runtime parameter
The code sample below shows how to specify the IP address where a Smart Agent is running as a runtime parameter for your client program or object implementation. Since specifying an IP address will cause a point-to-point connection to be established, you can even specify an IP address of a host located outside your local network. This mechanism takes precedence over any other host specification.
prompt> vbj -Dvbroker.agent.addr=<ip_address> Server
You can also specify the IP address through the properties file. Look for the vbroker.agent.addr entry.
vbroker.agent.addr=<ip_address>
By default, vbroker.agent.addr in the properties file is set to NULL.
You can also list the host names where the agent might reside and then point to that file with the vbroker.agent.addrFile option in the properties file.
Specifying an IP address with an environment variable
You can specify the IP address of a Smart Agent by setting the OSAGENT_ADDR environment variable prior to starting your client program or object implementation. This environment variable takes precedence if a host is not specified as a runtime parameter.
UNIX
prompt> setenv OSAGENT_ADDR 199.10.9.5
prompt> client
Windows
To set the OSAGENT_ADDR environment variable on a Windows system, you can use the System control panel and edit the environment variables:
1
2
Type OSAGENT_ADDR in the Variable edit box.
3
Specifying hosts with the agentaddr file
Your client program or object implementation can use the agentaddr file to circumvent the use of a UDP broadcast message to locate a Smart Agent. Simply create a file containing the IP addresses or fully qualified hostnames of each host where a Smart Agent is running and then set the OSAGENT_ADDR_FILE environment variable to point to the path of the file. When a client program or object implementation has this environment variable set, VisiBroker will try each address in the file until a Smart Agent is located. This mechanism has the lowest precedence of all the mechanisms for specifying a host. If this file is not specified, the VBROKER_ADM/agentaddr file is used.
Ensuring object availability
You can provide fault tolerance for objects by starting instances of those objects on multiple hosts. If an implementation becomes unavailable, the VisiBroker ORB will detect the loss of the connection between the client program and the object implementation and will automatically contact the Smart Agent to establish a connection with another instance of the object implementation, depending on the effective rebind policy established by the client. For more information on establishing client policies, go to the Client basics, “Using Quality of Service (QoS)”.
Note
The Smart Agent implements load balancing using a simple round-robin algorithm on a per agent basis, not on an ORB domain basis. For load balancing between server replicas, when you have more than one Smart Agent in the ORB domain, make sure all servers are registered with the same Smart Agent.
Important
The rebind option must be enabled if VisiBroker is to attempt reconnecting the client with an instance object implementation. This is the default behavior.
Invoking methods on stateless objects
Your client program can invoke a method on an object implementation which does not maintain state without being concerned if a new instance of the object is being used.
Achieving fault-tolerance for objects that maintain state
Fault tolerance can also be achieved with object implementations that maintain state, but it will not be transparent to the client program. In these cases, your client program must either use the Quality of Service (QoS) policy VB_NOTIFY_REBIND or register an interceptor for the VisiBroker ORB object. For information on using QoS, see “Using Quality of Service (QoS)”.
When the connection to an object implementation fails and VisiBroker reconnects the client to a replica object implementation, the bind method of the bind interceptor will be invoked by VisiBroker. The client must provide an implementation of this bind method to bring the state of the replica up to date. Client interceptors are described in “Client Interceptors”.
Replicating objects registered with the OAD
The OAD ensures greater object availability because if the object goes down, the OAD will restart it. If you want fault tolerance for hosts that may become unavailable, the OAD must be started on multiple hosts and the objects must be registered with each OAD instance.
Note
The type of object replication provided by VisiBroker does not provide a multicast or mirroring facility. At any given time there is always a one-to-one correspondence between a client program and a particular object implementation.
Migrating objects between hosts
Object migration is the process of terminating an object implementation on one host, and then starting it on another host. Object migration can be used to provide load balancing by moving objects from overloaded hosts to hosts that have more resources or processing power (there is no load balancing between servers registered with different Smart Agents.) Object migration can also be used to keep objects available when a host is shutdown for hardware or software maintenance.
Note
The migration of objects that do not maintain state is transparent to the client program. If a client is connected to an object implementation that has migrated, the Smart Agent will detect the loss of the connection and transparently reconnect the client to the new object on the new host.
Migrating objects that maintain state
The migration of objects that maintain state is also possible, but it will not be transparent to a client program that has connected before the migration process begins. In these cases, the client program must register an interceptor for the object.
When the connection to the original object is lost and VisiBroker reconnects the client to the object, the interceptor's rebind_succeeded() member function will be invoked by VisiBroker. The client can implement this function to bring the state of the object up to date.
Refer to “Using Portable Interceptors” for more information about how to use the interceptors.
Migrating instantiated objects
If the objects that you wish to migrate were created by a server process instantiating the implementation's class, you need only start it on a new host and terminate the server process. When the original instance is terminated, it will be unregistered with the Smart Agent. When the new instance is started on the new host, it will register with the Smart Agent. From that point on, client invocations are routed to the object implementation on the new host.
Migrating objects registered with the OAD
If VisiBroker objects that you wish to migrate are registered with the OAD, you must first unregister them with the OAD on the old host. Then, reregister them with the OAD on the new host.
Use the following procedure to migrate objects already registered with the OAD:
1
2
3
See “Using the Object Activation Daemon (OAD)” for detailed information on registering and unregistering object implementations.
Reporting all objects and services
The Smart Finder (osfind) command reports on all VisiBroker related objects and services which are currently available on a given network.
You can use osfind to determine the number of Smart Agent processes running on the network and the exact host on which they are executing. The osfind command also reports on all VisiBroker objects that are active on the network if these objects are registered with the Smart Agent. You can use osfind to monitor the status of the network and locate stray objects during the debugging phase.
The osfind command has the following syntax:
osfind [options]
The following options are valid with osfind. If no options are specified, osfind lists all of the agents, OADs, and implementations in your domain.
-f <agent_address_file_name>
Verifies object existence. This can cause considerable delay on loaded systems. Only objects registered BY_INSTANCE are verified for existence. Objects that are either registered with the OAD, or those registered BY_POA policy are not verified for existence.
-h, -help, -usage, -?
Windows
osfind is a console application. If you start osfind from the Start menu, it runs until completion and exits before you can view the results.
Binding to Objects
Before your client application invokes a method on an interface it must obtain an object reference using the bind() method.
When your client application invokes the bind() method, VisiBroker performs several functions on behalf of your application. These are shown below.
VisiBroker contacts the osagent to locate an object server that is offering the requested interface. If an object name and a host name (or IP address) are specified, they will be used to further qualify the directory service search.
Note
VisiBroker is not a separate process. It is a collection of classes and other resources that allow communication between clients and servers.