10.2 Service Location Protocol (SLP) Lookup Service
Java DMK 5.1 specifies how to register RMI connectors or JMXMP connectors with the SLP lookup service.
The purpose of this example is to demonstrate how a connector client can find and connect to a connector server that has registered with the SLP lookup service. This example performs the following operations:
-
The agent:
-
Creates an MBean server
-
Gets a pointer to the SLP lookup service
-
Creates a connector server
-
Registers the connector address with the SLP lookup service
-
-
The client:
-
Gets a pointer to the SLP lookup service
-
Looks for any connector servers registered in the SLP lookup service
-
Creates a JMX Remote API connector
-
Retrieves information about the MBeans in the MBean server
-
Note –
This example assumes that you are already familiar with SLP technology. The code provided for this example conforms to Sun Microsystems' implementation of SLP, as defined by RFC 2614. Sun Microsystems' implementation of SLP is available in the Solaris operating environment in the directory /usr/share/lib/slp. If you are not running the Solaris operating environment, you must obtain a version of SLP that is compliant with RFC 2614, section 5.
The SLP lookup example is contained in the directory examplesDir/current/Lookup/slp. For explanations of the SLP code used in this example, see RFC 2614 and the API documentation for SLP; the explanations below concentrate on the Java DMK implementation.
10.2.1 Registering the Connector Server with SLP
Example 10–1 shows the registration of a connector server's URL with the SLP lookup service's Advertiser. This code is taken from the Server class in the SLP example directory.
Example 10–1 Registering the Connector Server's Address with the SLP Advertiser
public class Server {
public final static int JMX_DEFAULT_LEASE = 300;
public final static String JMX_SCOPE = "DEFAULT";
private final MBeanServer mbs;
public Server() {
mbs = MBeanServerFactory.createMBeanServer();
}
[...]
public static void register(JMXServiceURL jmxUrl, String name)
throws ServiceLocationException {
ServiceURL serviceURL =
new ServiceURL(jmxUrl.toString(),
JMX_DEFAULT_LEASE);
debug("ServiceType is: " + serviceURL.getServiceType());
Vector attributes = new Vector();
Vector attrValues = new Vector();
attrValues.add(JMX_SCOPE);
ServiceLocationAttribute attr1 =
new ServiceLocationAttribute("SCOPE", attrValues);
attributes.add(attr1);
attrValues.removeAllElements();
attrValues.add(name);
ServiceLocationAttribute attr2 =
new ServiceLocationAttribute("AgentName", attrValues);
attributes.add(attr2);
final Advertiser slpAdvertiser =
ServiceLocationManager.getAdvertiser(Locale.US);
slpAdvertiser.register(serviceURL, attributes);
}
[...]
Examining this code excerpt, we see that the SLP lease JMX_DEFAULT_LEASE is set to a default lease of 300 seconds, which corresponds to the length of time the URL will be registered, and the initial creation of the MBean server mbs with a call to MBeanServerFactory.createMBeanServer(). In code that is not shown here, an SLP advertiser slpAdvertiser, and an SLP service URL url are defined. The slpAdvertiser is used to register the service URL in the SLP lookup service.
The service URL jmxUrl is the address of the connector server, and is obtained by a call to the getAddress() method of JMXConnectorServer when the connector server is started.
The SLP lookup attribute, namely the agent name under which the connector server address is to be registered (name), is then specified by the SLP class ServiceLocationAttribute. The AgentName attribute is mandatory, but other optional attributes, such as ProtocolType, AgentHost, and Property can also be registered in the SLP lookup service.
Finally, the JMX connector server address is registered in the SLP advertiser service with a call to the register() method of the Advertiser interface, with the serviceURL and the attributes passed in as parameters.
Now that the connector server's address has been advertised, the connector server itself is created and registered with SLP, as shown in Example 10–2.
Example 10–2 Registering the Connector Server in the SLP Lookup Service
[...]
public JMXConnectorServer rmi(String url) throws
IOException,
JMException,
NamingException,
ClassNotFoundException,
ServiceLocationException {
JMXServiceURL jurl = new JMXServiceURL(url);
final HashMap env = new HashMap();
// Environment map attributes
[...]
JMXConnectorServer rmis =
JMXConnectorServerFactory.newJMXConnectorServer(jurl, env, mbs);
final String agentName = System.getProperty("agent.name",
"DefaultAgent");
start(rmis, agentName);
return rmis;
}
public void start(JMXConnectorServer server, String agentName)
throws IOException, ServiceLocationException {
server.start();
final JMXServiceURL address = server.getAddress();
register(address,agentName);
}
The service URL jurl is constructed from the string url that will be included in the command used to launch the Server at the command line. An RMI connector server named rmis is then created with the system properties defined by the environment map and the address jurl.
The connector server is then started, and the RMI connector server address is registered in the SLP lookup service under the name agentName. Subsequent code not shown here creates a corresponding JMXMP connector server named jmxmp, that is also registered with the SLP service.
10.2.2 Looking up the Connector Server
The following code examples are taken from the Client class in the examplesDir/current/Lookup/slp directory.
Example 10–3 Retrieving the List of Connector Servers
public class Client {
public final static String JMX_SCOPE = "DEFAULT";
public static Locator getLocator() throws ServiceLocationException {
final Locator slpLocator =
ServiceLocationManager.getLocator(Locale.US);
return slpLocator;
}
public static List lookup(Locator slpLocator, String name)
throws IOException, ServiceLocationException {
final ArrayList list = new ArrayList();
Vector scopes = new Vector();
scopes.add(JMX_SCOPE);
String query =
"(&(AgentName=" + ((name!=null)?name:"*") + "))";
ServiceLocationEnumeration result =
slpLocator.findServices(new ServiceType("service:jmx"),
scopes, query);
while(result.hasMoreElements()) {
final ServiceURL surl = (ServiceURL) result.next();
JMXServiceURL jmxUrl = new JMXServiceURL(surl.toString());
try {
JMXConnector client =
JMXConnectorFactory.newJMXConnector(jmxUrl,null);
if (client != null) list.add(client);
} catch (IOException x ) {
[...]
}
}
}
return list;
}
Example 10–3 first of all obtains the SLP service Locator by calling the getLocator method of the SLP class ServiceLocationManager. Client then retrieves all the connector servers registered in the SLP service under a given agent name, or under agent names that match a certain pattern. If no agent name is specified when the Client is started, all agent names will be considered.
A JMX Remote API service URL, jmxUrl, is generated for each of the agents retrieved by SLP, with each agent's SLP service URL, surl, passed as a parameter into the JMXServiceURL instance. The URL jmxUrl is then passed to the newJMXConnector() method of JMXConnectorFactory, to create a new connector client named client for each agent that is registered in the SLP service.
The connector clients retrieved are stored in an array list called list.
Example 10–4 Accessing the MBeans in the Remote MBean Server
public static void listMBeans(MBeanServerConnection server)
throws IOException {
final Set names = server.queryNames(null,null);
for (final Iterator i=names.iterator(); i.hasNext(); ) {
ObjectName name = (ObjectName)i.next();
System.out.println("Got MBean: "+name);
try {
MBeanInfo info =
server.getMBeanInfo((ObjectName)name);
MBeanAttributeInfo[] attrs = info.getAttributes();
if (attrs == null) continue;
for (int j=0; j<attrs.length; j++) {
try {
Object o =
server.getAttribute(name,attrs[j].getName());
System.out.println("\t\t" + attrs[j].getName() +
" = "+o);
} catch (Exception x) {
System.err.println("JmxClient failed to get " +
attrs[j].getName() + x);
x.printStackTrace(System.err);
}
}
}
In Example 10–4, a reference to the MBeanServerConnection is retrieved for every connector client that is created from the connector server address stored in the SLP service. A list of all the MBeans and their attributes is retrieved.
Example 10–5 Connecting to the Remote Agents
public static void main(String[] args) {
try {
final String agentName = System.getProperty("agent.name");
final Locator slpLocator = getLocator();
List l = lookup(slpLocator,agentName);
int j = 1;
for (Iterator i=l.iterator();i.hasNext();j++) {
JMXConnector c1 = (JMXConnector) i.next();
if (c1 != null) {
try {
c1.connect(env);
} catch (IOException x) {
System.err.println ("Connection failed: " + x);
x.printStackTrace(System.err);
continue;
}
MBeanServerConnection conn =
c1.getMBeanServerConnection();
try {
listMBeans(conn);
} catch (IOException x) {
x.printStackTrace(System.err);
}
try {
c1.close();
} catch (IOException x) {
x.printStackTrace(System.err);
}
}
}
} catch (Exception x) {
x.printStackTrace(System.err);
}
}
In Example 10–5, the agent.name property is retrieved by calling the getProperty() method of the System class, and the SLP lookup service is found by calling the getLocator() method of Locator.
All the agents named agentName are then looked up, and connections are made to the agents discovered. If no agent is specified, then all agents are lookup up. Connections are made to the MBean server created by Server, and all the MBeans in it are listed, before the connection is closed down.
10.2.3 Running the SLP Lookup Service Example
In addition to the actions you performed in 10.1 Initial Configuration, before you can run the lookup service examples that use the SLP, you must perform some further set—up actions that are specific to this example. You can then start looking up connectors using SLP in conjunction with the two connectors supported by Java DMK.
When you run the examples, to help you keep track of which agent has been created with which connector and transport, the agent names include a letter suffix. For example, the agent from the example of an RMI connector over JRMP, without an external directory, is called test-server-a.
To Set up the SLP Lookup Service Example
The following steps are required by all of the different connector/transport combinations you can run in this example.
-
For convenience when compiling and running the classes, define an additional environment variable.
In addition to the common environment variables that were set in 10.1 Initial Configuration, you need to add the path to the SLP service. If you are using the Solaris operating environment, add the following variables:
$ SLP_LIB=/usr/share/lib/slp
If you are using another platform, set SLP_LIB appropriately for the platform you are using.
-
Define and export the classp environment variable.
This example requires a classpath that includes the Java archive (JAR) files for SLP, as well as the JARs for Java DMK, the mandatory and optional parts of the JMX Remote API, and the JMX API reference implementation.
classp=$SLP_LIB/slp.jar:classpath:.
-
Start the SLP daemon.
If you are using the Solaris operating environment, type the following command, which requires you to know your superuser password:
$ su root -c "java -cp $SLP_LIB/slpd.jar com.sun.slp.slpd &" Password: [type superuser password]
If you are not running a Solaris system, start the SLP daemon according to the implementation of SLP you are using.
To Run the SLP Lookup Service Example With an RMI Connector
This example demonstrates the use of the SLP lookup service to look up RMI connector servers that use RMI's default transport, JRMP, as well as the IIOP transport. In addition, as described in 10.1 Initial Configuration, different external directories are used to register the RMI connector stubs.
The combinations of transports and external directories demonstrated here are:
-
RMI connector over the JRMP transport, with:
-
No external directory
-
An RMI registry
-
An LDAP registry
-
-
RMI connector over the IIOP transport, with:
-
No external directory
-
A CORBA naming service
-
An LDAP registry
-
Perform the following steps to run the example:
-
Start the Server.
The command you use to start the Server varies according to which external directory you are using. You can start one or more of the following instances of Server with different transports and external registries before starting the Client.
-
RMI connector over JRMP, without an external directory:
$ java -classpath .:$classp -Ddebug=true \ -Dagent.name=test-server-a \ -Durl ="service:jmx:rmi://" \ slp.Server &
In this command:
-
debug is set to true to provide more complete screen output when the Server runs
-
The name of the agent to be created is test-server-a
-
The service URL specifies that the chosen connector is an RMI connector, running over the RMI default transport JRMP.
When Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its URL in the SLP service.
-
-
RMI connector over JRMP, using an RMI registry as an external directory:
$ java -classpath .:$classp -Ddebug=true \ -Dagent.name=test-server-b \ -Durl="service:jmx:rmi:///jndi/${jndirmi}/server" \ slp.Server &In this command:
-
The name of the agent created is test-server-b
-
The service URL specifies the chosen connector as RMI over JRMP, and the external directory in which the RMI connector stub, server, is stored is the RMI registry you identified as jndirmi in 10.1 Initial Configuration.
When Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its URL in the SLP service.
-
-
RMI connector over JRMP, using LDAP as the external directory:
$ java -classpath .:$classp -Ddebug=true \ -Dagent.name=test-server-c \ -Durl="service:jmx:rmi:///jndi/${jndildap}/cn=x,dc=Test" \ -Djava.naming.security.principal="$principal" \ -Djava.naming.security.credentials="$credentials" \ slp.Server &In this command:
-
The name of the agent created is test-server-c
-
The service URL specifies the chosen connector as RMI over JRMP, and the external directory in which the RMI connector stub is stored is the LDAP server you identified as jndildap in 10.1 Initial Configuration
-
The stub is registered in the Test domain component in the LDAP server.
-
The common name attribute principal and password credentials are given to gain access to the LDAP server.
When Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its URL in the SLP service under the agent name test-server-c.
-
-
RMI connector over IIOP, without an external directory:
$ java -classpath .:$classp -Ddebug=true \ -Dagent.name=test-server-d \ -Durl="service:jmx:iiop://" \ slp.Server &In this command:
-
The name of the agent created is test-server-d
-
The service URL specifies the chosen connector as RMI connector over IIOP.
When the Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its automatically generated URL in the SLP service.
-
-
RMI connector over IIOP, using CORBA naming as the external directory.
$ java -classpath .:$classp -Ddebug=true \ -Dagent.name=test-server-e \ -Durl="service:jmx:iiop:///jndi/${jndiiiop}/server" \ slp.Server &In this command:
-
The name of the agent created is test-server-e
-
The service URL specifies the chosen connector as RMI connector over IIOP. The external directory in which the RMI connector stub server is stored is the CORBA naming service you identified as jndiiiop in 10.1 Initial Configuration.
-
-
RMI connector over IIOP, using LDAP as the external directory.
$ java -classpath .:$classp -Ddebug=true \ -Dagent.name=test-server-f \ -Durl="service:jmx:iiop:///jndi/${jndildap}/cn=x,dc=Test" \ -Djava.naming.security.principal="$principal" \ -Djava.naming.security.credentials="$credentials" \ slp.Server &In this command:
-
The name of the agent created is test-server-f
-
The service URL specifies the chosen connector as RMI over IIOP, and the external directory in which the RMI connector stub is stored is the LDAP server you identified as jndildap in 10.1 Initial Configuration.
-
The stub is registered in the Test domain component in the LDAP server.
-
The common name attribute principal and password credentials are given to gain access to the LDAP server.
When Server is launched, you will see confirmation of the creation of the RMI connector, and the registration of its URL in the SLP service under the agent name test-server-f.
-
-
-
Start the Client.
After starting the Server using the transport and external directory of your choice, start the Client:
$ java -classpath .:$classp -Ddebug=true \ -Djava.naming.security.principal="$principal" \ -Djava.naming.security.credentials="$credentials" \ slp.ClientYou will see output confirming the detection of the agents created by the Server and registered in the lookup service. You will also see the identification and confirmation of the connection made to the agents.
To look up a specific agent, type the following command:
$ java -classpath .:$classp -Ddebug=true \ -Djava.naming.security.principal="$principal" \ -Djava.naming.security.credentials="$credentials" \ -Dagent.name="agentName" \ slp.ClientIn the command shown above, agentName is the name of the agent you want to look up. You can also specify a partial agent name by using *; for example, x* for all agent names beginning with the letter x.
To Run the SLP Lookup Service Example With a JMXMP Connector
This example demonstrates the use of the SLP lookup service to look up JMXMP connector servers.
-
Start the Server.
$ java -classpath .:$classp -Ddebug=true \ -Dagent.name=test-server-g \ -Durl="service:jmx:jmxmp://" \ slp.Server &-
The name of the agent created is test-server-g
-
The service URL specifies the chosen connector as the JMXMP connector, running on the first available port.
When the Server is launched, you will see confirmation of the creation of the JMXMP connector, and the registration of its automatically generated URL in the SLP service. JMXMP connector servers can be used alongside RMI connectors, and will be detected by the Client in exactly the same way as RMI connector servers.
-
-
Start the Client.
After starting the Server, start the Client:
$ java -classpath .:$classp -Ddebug=true slp.Client
You will see output confirming the detection of the agents created by the Server and registered in the lookup service. You will also see the identification and confirmation of the connection made to the agents.
To look up a specific agent, type the following command:
$ java -classpath .:$classp -Ddebug=true \ -Dagent.name="agentName" \ slp.Client
In the command shown above, agentName is the name of the agent you want to look up. You can also specify a partial agent name by using *; for example, x* for all agent names beginning with the letter x.
- © 2010, Oracle Corporation and/or its affiliates