Wiki code for The Java SCF interfaces

Hide Line numbers
1: == Java SCF Interfaces ==
2: 
3: Perhaps the most stable component of the Visual Panels demo release are
4: the Java SCF interfaces.  By "stable" we don’t mean to imply that you
5: can count on these interfaces staying the same ~-- they may change
6: significantly (probably based on your feedback or with your help) ~--
7: but they aren’t something we expect to throw out and replace.  At the
8: moment there is still considerable work to be done (e.g. error handling
9: is particularly egregious), but the interfaces should be fully
10: functional: there shouldn’t be anything you can do using the
11: [[{{code}}libscf(3lib){{/code}}>>http://docs.sun.com/app/docs/doc/816-5173/6mbb8adv7?a=view]]
12: interfaces that you can’t do with the Java interfaces.
13: 
14: There is a subtle distinction between SCF, the service configuration
15: facility, and SMF, the service management facility.  The former
16: represents the underlying mechanism of managing services, instances,
17: properties, etc. and the latter represent the policies we have
18: implemented on top of that mechanism.  To cite an example, SCF gives us
19: property groups, SMF defines what a dependency group looks like.
20: 
21: To reflect this division of responsibilities, we have two packages,
22: {{code}}org.opensolaris.os.scf{{/code}} for SCF and {{code}}org.opensolaris.os.smf{{/code}} for SMF.
23: Both packages can be accessed by including
24: {{code}}/opt/OSOL0vpanels/lib/java/scf.jar{{/code}} in your class path, and their
25: javadoc (albeit sorrowfully incomplete) can be found in
26: {{code}}/opt/OSOL0vpanels/lib/java/javdoc/scf{{/code}}.
27: 
28: === {{code}}org.opensolaris.os.scf{{/code}}
29: 
30: {{code}}org.opensolaris.os.scf{{/code}} ({{code}}o.o.o.scf{{/code}} for short) contains all the
31: functionality needed to interact with SCF.  Though it talks to a native
32: library behind the scenes, it publishes interfaces which should feel
33: comfortable to a Java programmer.  You can see where things line up,
34: though: the basic object model presented by the C library is
35: preserved.
36: 
37: ==== Implementation
38: 
39: {{code}}o.o.o.scf{{/code}} has both Java and native components.  The Java component
40: lives in {{code}}usr/src/java/org/opensolaris/os/scf{{/code}}, and the native
41: component in {{code}}usr/src/lib/libscf_jni{{/code}}.
42: 
43: ==== Use
44: 
45: As when using {{code}}libscf(3lib){{/code}}, all access to the SMF repository starts
46: with a handle.  In this case, a {{code}}o.o.o.scf.Handle{{/code}}.  Unlike when using
47: the C library, you don’t need to create objects that routines can "fill
48: in".  If you want to get the local scope (which you almost always do)
49: given a handle {{code}}h{{/code}}, you simply take the result of
50: {{code}}h.scope(Scope.SCF~_SCOPE~_LOCAL()){{/code}}.  If you’re interested in the
51: instances of a service {{code}}svc{{/code}}, {{code}}svc.instances(){{/code}} will return an iterator
52: of type {{code}}Iterator<o.o.o.scf.Instance>{{/code}}.  And so on.
53: 
54: Errors are thrown as exceptions.  Unfortunately, at the moment we
55: simply pass on the errno values from the failing {{code}}libscf{{/code}} calls.  If
56: you plan on playing around with these interfaces, you’ll need to use a
57: 
58: combination of the {{code}}libscf{{/code}} man pages, the javadoc, and possibly the
59: source until we’ve made the necessary improvements to both the error
60: handling and the documentation.
61: 
62: === {{code}}org.opensolaris.os.smf{{/code}}
63: 
64: {{code}}o.o.o.smf{{/code}} will contain all the SMF-specific knowledge, and is
65: implemented entirely on {{code}}o.o.o.scf{{/code}}.  That is, it contains no non-Java
66: components.  Currently, its scope is very limited; most of our effort
67: has necessarily been put into getting the underlying support working.
68: Despite it’s limited functionality, you’ll find several handy classes
69: in this package.
70: 
71: ==== Implementation
72: 
73: {{code}}o.o.o.smf{{/code}} is found entirely in
74: {{code}}usr/src/java/org/opensolaris/os/smf{{/code}}.
75: 
76: ==== Use
77: 
78: The {{code}}o.o.o.smf{{/code}} class can’t be used entirely on their own; they require
79: input in the form of {{code}}o.o.o.scf{{/code}} objects.  The standard paradigm is for
80: there to be {{code}}o.o.o.smf{{/code}} objects which correspond to {{code}}o.o.o.scf{{/code}} objects
81: having the same name (currently prepended with "Smf", though that may
82: change) which take the latter as the argument to their constructors.
83: As with {{code}}o.o.o.scf{{/code}}, many of these classes have methods which return
84: collections f other {{code}}o.o.o.smf{{/code}} classes in an intuitive way.
85: 
86: e.g. An {{code}}o.o.o.smf.SmfService{{/code}} is usually constructed using an
87: {{code}}o.o.o.scf.Service{{/code}}.  An {{code}}o.o.o.smf.SmfInstance{{/code}} can be created using
88: an {{code}}o.o.o.scf.Instance{{/code}}, or by calling {{code}}SmfService.instances(){{/code}}.
89: 
90: Error handling in {{code}}o.o.o.smf{{/code}} classes is in some places worse than in
91: {{code}}o.o.o.scf{{/code}}, as we simply pass through the already confusing underlying
92: errors.  In other places it is better, since we have high-level logic
93: for which we can use the sensible standard Java exceptions.  Your
94: mileage will vary.
95: 
96: === Example
97: 
98: Here’s a simple example program which connects to the repository, and
99: dumps out a list of services and their states:
100: 
101:         import org.opensolaris.os.scf.\*;
102:         import org.opensolaris.os.smf.\*;
103:         public class SvcList
104:         {
105:                 public static void main(String[] args)
106:                 {
107:                         Handle h = new Handle();
108:                         try {
109:                                 h.bind();
110:                                 Scope s = h.scope(Scope.SCF~_SCOPE~_LOCAL());
111:                                 for (Service svc : s.services()) {
112:                                         SmfService smfsvc = new SmfService(svc);
113:                                         for (SmfInstance i : smfsvc.instances())
114:                                                 System.out.printf("%-16s%s\n",
115:                                                     i.getState().toString(),
116:                                                     i.toString());
117:                                 }
118:                         } catch (ScfException e) {
119:                                 System.err.println("Ouch.");
120:                                 return;
121:                         }
122:                 }
123:         }
124: 
125: All that is necessary to build and run this, or any other
126: {{code}}o.o.o.scf{{/code}}/{{code}}smf{{/code}} consumer, is to point your classpath at
127: {{code}}/opt/OSOL0vpanels/lib/java/scf.jar{{/code}}.  There is no need to build or
128: even extract the source, and no need to set your {{code}}LD~_LIBRARY~_PATH{{/code}} to
129: find the native library.  Even if you move the directory tree around,
130: the native library should be found as long as {{code}}scf.jar{{/code}} and
131: {{code}}libscf_jni.so.1{{/code}} have the same relative locations.
OpenSolaris

Top Menu

Wiki code for The Java SCF interfaces

Search

Collectives

Community Group

Project

User Group

Subsites

Project vpanels Pages
