The NetDB RMI - Simple NetDB Programming

The NetDB RMI is a straightforward, object-oriented, programming interface that makes it easy for NetDB users to write programs to manipulate NetDB data. The RMI comprises a set of simple classes using simple types (mostly string and integer). It is very easy to use, not only from Java, but from any JVM-based language, including scripting languages like Jython and JRuby.

  • The NetDB RMI Classes

    • A simple summary of the new RMI classes with links to their detailed javadoc documentation can be found here.

  • Examples

    • Here's an example program in three different languages to get you started:

  • Java
  • JRuby
  • Jython
    • The NetDB command-line program is written in JRuby and uses the RMI. It contains examples of finding and manipulating virtually all attributes of NetDB node records.

  • Development Environment

    • The example programs above use the netdb-dev development environment. The purpose of the netdb-dev development environment is for NetDB users to develop and test NetDB RMI programs. It's a duplicate of the production NetDB and is refreshed Sunday at 4:42 AM using data from Saturday morning.

    There's a copy of the NetDB web application running on netdb-dev.stanford.edu that uses the same development database. Use it to set up data for testing and to examine the results of tests.

    The development environment is a great resource for recovering data accidentally removed from the production NetDB. In fact the NetDB command-line program includes a subcommand to copy node records from netdb-dev to the production NetDB. For details use the NetDB CLI command "netdb node dev2prod help".

  • Early Access Development Environment

    • When upcoming NetDB updates include significant changes that cannot be deployed in the regular development environment, an early access development environment will be provided. It will be a duplicate of the production NetDB plus all the updates for the next version. It will be refreshed Sunday at 4:42 AM using data from Saturday morning.

    The RMI service name for the early access development environment is netdb-tng.stanford.edu. A copy of the NetDB web application running on netdb-tng.stanford.edu will also be provided.

  • Production Environment

    • Programs specify their NetDB environment using a NetDB service name. The examples above access the development environment using the the name netdb-dev.stanford.edu. The production NetDB service name is netdb.stanford.edu.

  • Getting It

    • A single jar file is all that's needed to use the NetDB RMI. If the NetDB command-line program is installed on your system the jar file is already there in /usr/share/java/netdb_rmi.jar. If not, you can download it here (release notes).

    The NetDB RMI has also been packaged for Debian Linux. Get the package here or from the Stanford Debian repositories.

  • Troubleshooting

    • The NetDB RMI is pretty easy to use. There are, however, a few things folks stumble over once in a while. Here's a short list:

    NetDB Groups are known as Owners in the RMI

    The attribute known as Group in the NetDB web application is known as Owner in the RMI. The method owners() returns the groups associated with a record. The methods add_owners() and remove_owners() are used to change the groups associated with a record.

    The RMI requires stronger encryption than some default Java installations provide

    If your RMI program fails with SSLHandshakeException, your Java installation may be missing the strong encryption package. Here's a page that will help you find and install the appropriate package.

  • Efficient Programming - Working with Lists of Nodes

    • Programs often need to make changes to a set of nodes based on some property or properties of the nodes. The simple solution is to get the nodes one by one, check the condition, and make the change if necessary. A slightly more complex and vastly more efficient solution is to perform a full search on all the nodes and conditions, then loop over the results making the changes. This method replaces the per-node call used to get the nodes with a single full search call. That can translate into tremendous performance improvements, especially when dealing with hundreds or thousands of nodes. Here are examples of the simple and efficient solutions.

    The efficient solution is accomplished with a search string of all the node names joined by or, e.g., argus.stanford.edu or avallone.stanford.edu or atalante.stanford.edu. As the number of elements in the search string increases the search slows down, slowly at first, but there's a critical point where the search slows markedly (as in orders of magnitude slower). Therefore, large sets, say, over 200 elements, should be broken into batches for maximal throughput. Here's an example of how to do that.

    As to batch size, it depends somewhat on the length of the individual elements. Experiments in the development environment suggest a batch size between 100 and 200 is a good starting point. Of course testing with various batch sizes will yield the optimal batch size for a given application.

    In summary, when dealing with sets of nodes, use full search and break large sets into batches of 100-200 using this algorithm. Here are examples in Java, JRuby, and Jython.

  • Mailing List

    • A mailing list has been set up for NetDB RMI users to ask questions and share ideas and programming experiences. It's netdb-rmi-users@lists.stanford.edu and you can join it here.

    Share and enjoy.

    Updated: June 1, 2023