[Homepage] | [System overview] | [Clients] | [Services] | [Servers] | [Config options] |
Background
Most Ninja developers will want to use the Berkeley SDS to help locate
services within the network. For example, a Ninja Jukebox client
might want to find all local Ninja Jukebox servers when it starts up.
This can be done easily by using the Berkeley SDS to make a query,
specifying that you want all services with the type
ninja.jukebox.MusicDirectory
.
This tutorial will describe how you can do this.
Using the Berkeley SDS to make queries is fairly easy. The typical routines that a client application will use to make these queries can be found in ninja.sds.SDS. Usually, the steps involved with initializing the Berkeley SDS and making queries are as follow:
First, be sure to import all the needed classes
import ninja.sds.SDS; import ninja.sds.Query; import ninja.sds.SearchResult; import ninja.sds.NoSDSfound; import ninja.ispace.auth.KeyReader; import ninja.ispace.auth.Authenticator; import java.rmi.Remote;
Next, we need the certificate and authenticator associated with the principal that's going to make the query (usually the client's identity). We need this so that we can prove that we are indeed the principal we claim to be, and also that we should have the right to discover whatever services that are available to us.
KeyReader pr = new KeyReader(new File("~/my_private_key")); if (pr.needsDecryption()) pr.decrypt(ninja.utils.PlatformDependent.readPassphrase("Enter passphrase for client's private key:")); Authenticator privateAuthenticator = pr.getAuthenticator();
After we have the authenticator and certificate, we can initialize the SDS help routines in ninja.sds.SDS.
try { SDS.init("czerwin@cs.berkeley.edu.", privateAuthenticator, -1); } catch (NoSDSFound e) { System.err.println("Failed in finding an SDS server"); }
We should point out that there are several variants on the SDS.Init, and you should examine them to see which one is appropriate for you. This variant is probably the easiest to use, since it automates many of the tasks you would have to perform.
The SDS.Init code performs the following actions for the user:
The next step is to create a query object, and passing it to the SDS server. We use the ninja.sds.Query class to compose the query, so that users don't typically have to mess around with XML. However, there are interfaces to bypass this and allow direct XML manipulation if so desired.
Using the ninja.sds.Query class, you can specify which tags you are looking for, and the value you want to match on. In our case, we are looking for a particular type.
Query theQuery = new Query(); theQuery.addTag("TYPE", "ninja.jukebox.MusicDirectory");
Now we submit the query the SDS, indicating that we want to use the #1 hierarchy. This hierarchy is just a place holder for the future wide area system.
Vector result = SDS.Lookup(theQuery, 1); SearchResult first = (SearchResult) result.elementAt(0); Remote aService = SDS.GetServiceRMIref(first.getTag("URL"));
And that's it! We now have a stub to the service we were looking for.
Of course, this is the simplest way to use the SDS system, so you should
look over the API's offered in
ninja.sds.SDS
to see what else you can do. Also, be sure to look over the
cofig options page to see what options you can
specify to change the behavior of the SDS. For example, you might
want to change the multicast channel that is used to publish server
announcements in order to use a private one for your own SDS servers
during development stages.
Making an insecure SDS query
Making an insecure SDS query is even easier, since you don't have to worry
about the client's certificate or private authenticator.
Here's some sample code showing how to make an insecure query:
SDS.init(); Query theQuery = new Query(); theQuery.addTag("TYPE", "ninja.jukebox.MusicDirectory"); Vector result = SDS.Insecure_Lookup(query, 1); SearchResult first = (SearchResult) result.elementAt(0); Remote aService = SDS.GetServiceRMIref(first.getTag("URL")));
Of course, making queries in this manner bypasses all the very nice security features of the Berkeley SDS. We are only offering this service to ease the burden of developers during testing phases. In the future, we might remove this functionality all together.