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.
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, go to “Using POAs”.
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, go to “Using the VisiNaming Service”.
|
•
|
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.
|
In the above situations an alternative directory, such as the Naming Service, may be more appropriate. Refer to “Using the VisiNaming Service” for more information.
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”.
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)”
|
•
|
Double-click the osagent executable osagent.exe located in:
|
|
•
|
At the Command Prompt, enter: osagent [options]. For example:
|
|
•
|
Enter: osagent &. For example:
|
Due to 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 &
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>
|
|
||||||||||||||||
The following example of the osagent command specifies a particular UDP port:
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.
|
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.
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.
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.
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.
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,
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.
To allow the Smart Agent on one network to contact a Smart Agent on another local network, you must make the IP address of the remote Smart Agent available in a file named agentaddr. This is only necessary if the two Smart Agents can not detect each other through the UDP broadcast. The path to this file is specified by the VBROKER_ADM environment variable that is set for the Smart Agent process. You can override this file name by setting the OSAGENT_ADDR_FILE environment variable.
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.
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.
|
Figure 21
|
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”.
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.
If you want to override these settings, configure the interface information in the localaddr file. See “Specifying interface usage for Smart Agents” for details.
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:
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:
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:
You can also specify the IP address through the properties file. Look for the vbroker.agent.addr entry.
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.
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.
To set the OSAGENT_ADDR environment variable on a Windows system, you can use the System control panel and edit the environment variables:
|
2
|
Type OSAGENT_ADDR in the Variable edit box.
|
|
3
|
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.
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 “Client basics” in “Client basics”.
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 “Client basics”.
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 , “Using VisiBroker Interceptors.”.
When the connection to the original object is lost and VisiBroker reconnects the client to the object, the interceptor's rebind_succeeded() method will be invoked by VisiBroker. The client can implement this method to bring the state of the object up to date.
Refer to “Using Portable Interceptors” for more information about how to use the interceptors.
See “Using the Object Activation Daemon (OAD)” for detailed information on registering and unregistering object implementations.
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:
The following options are valid with osfind. If no options are specified, osfind lists all of the agents, OAD's, 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.
|
|
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.
Before your client application invokes a method on an interface it must first 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.
|