Perhaps the most stable component of the Visual Panels demo release are
the Java SCF interfaces. By "stable" we don't mean to imply that you
can count on these interfaces staying the same — they may change
significantly (probably based on your feedback or with your help) —
but they aren't something we expect to throw out and replace. At the
moment there is still considerable work to be done (e.g. error handling
is particularly egregious), but the interfaces should be fully
functional: there shouldn't be anything you can do using the
libscf(3lib)
interfaces that you can't do with the Java interfaces.
There is a subtle distinction between SCF, the service configuration
facility, and SMF, the service management facility. The former
represents the underlying mechanism of managing services, instances,
properties, etc. and the latter represent the policies we have
implemented on top of that mechanism. To cite an example, SCF gives us
property groups, SMF defines what a dependency group looks like.
To reflect this division of responsibilities, we have two packages,
org.opensolaris.os.scf for SCF and org.opensolaris.os.smf for SMF.
Both packages can be accessed by including
/opt/OSOL0vpanels/lib/java/scf.jar in your class path, and their
javadoc (albeit sorrowfully incomplete) can be found in
/opt/OSOL0vpanels/lib/java/javdoc/scf.
org.opensolaris.os.scf (o.o.o.scf for short) contains all the
functionality needed to interact with SCF. Though it talks to a native
library behind the scenes, it publishes interfaces which should feel
comfortable to a Java programmer. You can see where things line up,
though: the basic object model presented by the C library is
preserved.
o.o.o.scf has both Java and native components. The Java component
lives in usr/src/java/org/opensolaris/os/scf, and the native
component in usr/src/lib/libscf_jni.
As when using libscf(3lib), all access to the SMF repository starts
with a handle. In this case, a o.o.o.scf.Handle. Unlike when using
the C library, you don't need to create objects that routines can "fill
in". If you want to get the local scope (which you almost always do)
given a handle h, you simply take the result of
h.scope(Scope.SCF_SCOPE_LOCAL()). If you're interested in the
instances of a service svc, svc.instances() will return an iterator
of type Iterator<o.o.o.scf.Instance>. And so on.
Errors are thrown as exceptions. Unfortunately, at the moment we
simply pass on the errno values from the failing libscf calls. If
you plan on playing around with these interfaces, you'll need to use a
combination of the libscf man pages, the javadoc, and possibly the
source until we've made the necessary improvements to both the error
handling and the documentation.
o.o.o.smf will contain all the SMF-specific knowledge, and is
implemented entirely on o.o.o.scf. That is, it contains no non-Java
components. Currently, its scope is very limited; most of our effort
has necessarily been put into getting the underlying support working.
Despite it's limited functionality, you'll find several handy classes
in this package.
o.o.o.smf is found entirely in
usr/src/java/org/opensolaris/os/smf.
The o.o.o.smf class can't be used entirely on their own; they require
input in the form of o.o.o.scf objects. The standard paradigm is for
there to be o.o.o.smf objects which correspond to o.o.o.scf objects
having the same name (currently prepended with "Smf", though that may
change) which take the latter as the argument to their constructors.
As with o.o.o.scf, many of these classes have methods which return
collections f other o.o.o.smf classes in an intuitive way.
e.g. An o.o.o.smf.SmfService is usually constructed using an
o.o.o.scf.Service. An o.o.o.smf.SmfInstance can be created using
an o.o.o.scf.Instance, or by calling SmfService.instances().
Error handling in o.o.o.smf classes is in some places worse than in
o.o.o.scf, as we simply pass through the already confusing underlying
errors. In other places it is better, since we have high-level logic
for which we can use the sensible standard Java exceptions. Your
mileage will vary.
Here's a simple example program which connects to the repository, and
dumps out a list of services and their states:
import org.opensolaris.os.scf.*;
import org.opensolaris.os.smf.*;
public class SvcList
{
public static void main(String[] args)
{
Handle h = new Handle();
try {
h.bind();
Scope s = h.scope(Scope.SCF_SCOPE_LOCAL());
for (Service svc : s.services()) {
SmfService smfsvc = new SmfService(svc);
for (SmfInstance i : smfsvc.instances())
System.out.printf("%-16s%s\n",
i.getState().toString(),
i.toString());
}
} catch (ScfException e) {
System.err.println("Ouch.");
return;
}
}
}
All that is necessary to build and run this, or any other
o.o.o.scf/smf consumer, is to point your classpath at
/opt/OSOL0vpanels/lib/java/scf.jar. There is no need to build or
even extract the source, and no need to set your LD_LIBRARY_PATH to
find the native library. Even if you move the directory tree around,
the native library should be found as long as scf.jar and
libscf_jni.so.1 have the same relative locations.