3 collectd-java - Documentation of collectd's "java plugin"
10 JVMArg "-Djava.class.path=/opt/collectd/lib/collectd/bindings/java"
12 LoadPlugin "org.collectd.java.Foobar"
13 <Plugin "org.collectd.java.Foobar">
14 # To be parsed by the plugin
20 The I<Java> plugin embeds a I<Java Virtual Machine> (JVM) into I<collectd> and
21 provides a Java interface to part of collectd's API. This makes it possible to
22 write additions to the daemon in Java.
24 This plugin is similar in nature to, but shares no code with, the I<Perl>
25 plugin by Sebastian Harl, see L<collectd-perl(5)> for details.
29 A short outline of this plugin's configuration can be seen in L<"SYNOPSIS">
30 above. For a complete list of all configuration options and their semantics
31 please read L<collectd.conf(5)/Plugin C<java>>.
35 When writing additions for collectd in Java, the underlying C base is mostly
36 hidden from you. All complex data types are converted to their Java counterparts
37 before they're passed to your functions. These Java classes reside in the
38 I<org.collectd.api> namespace.
40 The available classes are:
44 =item B<org.collectd.api.OConfigValue>
46 Corresponds to C<oconfig_value_t>, defined in F<src/liboconfig/oconfig.h>.
48 =item B<org.collectd.api.OConfigItem>
50 Corresponds to C<oconfig_item_t>, defined in F<src/liboconfig/oconfig.h>.
52 =item B<org.collectd.api.DataSource>
54 Corresponds to C<data_source_t>, defined in F<src/plugin.h>.
56 =item B<org.collectd.api.DataSet>
58 Corresponds to C<data_set_t>, defined in F<src/plugin.h>.
60 =item B<org.collectd.api.ValueList>
62 Corresponds to C<value_list_t>, defined in F<src/plugin.h>.
66 In the remainder of this document, we'll use the short form of these names, for
67 example B<ValueList>. In order to be able to use these abbreviated names, you
68 need to B<import> the classes.
70 The API functions that are available from Java are implemented as I<static>
71 functions of the B<org.collectd.api.CollectdAPI> class.
72 See L<"CALLING API FUNCTIONS"> below for details.
74 =head1 REGISTERING CALLBACKS
76 When starting up, collectd creates an object of each configured class. The
77 constructor of this class should then register "callbacks" with the daemon,
78 using the appropriate static functions in B<CollectdAPI>,
79 see L<"CALLING API FUNCTIONS"> below. To register a callback, the object being
80 passed to one of the register functions must implement an appropriate
81 interface, which are all in the B<org.collectd.api> namespace.
83 A constructor may register any number of these callbacks, even none. An object
84 without callback methods is never actively called by collectd, but may still
85 call the exported API functions. One could, for example, start a new thread in
86 the constructor and dispatch (submit to the daemon) values asynchronously,
87 whenever one is available.
89 Each callback method is now explained in more detail:
91 =head2 config callback
93 Interface: B<org.collectd.api.CollectdConfigInterface>
95 Signature: I<int> B<config> (I<OConfigItem>)
97 This method is passed a B<OConfigItem> object, if both, method and
98 configuration, are available. B<OConfigItem> is the root of a tree representing
99 the configuration for this plugin. The root itself is the representation of the
100 B<E<lt>PluginE<nbsp>/E<gt>> block, so in next to all cases the children of the
101 root are the first interesting objects.
103 To signal success, this method has to return zero. Anything else will be
104 considered an error condition and the plugin will be disabled entirely.
108 Interface: B<org.collectd.api.CollectdInitInterface>
110 Signature: I<int> B<init> ()
112 This method is called after the configuration has been handled. It is
113 supposed to set up the plugin. e.E<nbsp>g. start threads, open connections, or
114 check if can do anything useful at all.
116 To signal success, this method has to return zero. Anything else will be
117 considered an error condition and the plugin will be disabled entirely.
121 Interface: B<org.collectd.api.CollectdReadInterface>
123 Signature: I<int> B<read> ()
125 This method is called periodically and is supposed to gather statistics in
126 whatever fashion. These statistics are represented as a B<ValueList> object and
127 sent to the daemon using B<dispatchValues>, see L<"CALLING API FUNCTIONS">
130 To signal success, this method has to return zero. Anything else will be
131 considered an error condition and cause an appropriate message to be logged.
132 Currently, returning non-zero does not have any other effects. In particular,
133 Java "read"-methods are not suspended for increasing intervals like C
136 =head2 write callback
138 Interface: B<org.collectd.api.CollectdWriteInterface>
140 Signature: I<int> B<write> (I<ValueList>)
142 This method is called whenever a value is dispatched to the daemon. The
143 corresponding C "write"-functions are passed a C<data_set_t>, so they can
144 decide which values are absolute values (gauge) and which are counter values.
145 To get the corresponding C<ListE<lt>DataSourceE<gt>>, call the B<getDataSource>
146 method of the B<ValueList> object.
148 To signal success, this method has to return zero. Anything else will be
149 considered an error condition and cause an appropriate message to be logged.
151 =head2 shutdown callback
153 Interface: B<org.collectd.api.CollectdShutdownInterface>
155 Signature: I<int> B<shutdown> ()
157 This method is called when the daemon is shutting down. You should not rely on
158 the destructor to clean up behind the object but use this function instead.
160 To signal success, this method has to return zero. Anything else will be
161 considered an error condition and cause an appropriate message to be logged.
165 This short example demonstrates how to register a read callback with the
168 import org.collectd.api.CollectdAPI;
169 import org.collectd.api.ValueList;
171 import org.collectd.api.CollectdReadInterface;
173 public class Foobar implements CollectdReadInterface
177 CollectdAPI.registerRead ("Foobar", this);
184 /* Do something... */
186 CollectdAPI.dispatchValues (vl);
190 =head1 CALLING API FUNCTIONS
192 All collectd API functions that are available to Java plugins are implemented
193 as I<publicE<nbsp>static> functions of the B<org.collectd.api.CollectdAPI>
194 class. This makes calling these functions pretty straight forward.
196 The following are the currently exported functions. For information on the
197 interfaces used, please see L<"REGISTERING CALLBACKS"> above.
199 =head2 registerConfig
201 Signature: I<int> B<registerConfig> (I<String> name,
202 I<CollectdConfigInterface> object);
204 Registers the B<config> function of I<object> with the daemon.
206 Returns zero upon success and non-zero when an error occurred.
210 Signature: I<int> B<registerInit> (I<String> name,
211 I<CollectdInitInterface> object);
213 Registers the B<init> function of I<object> with the daemon.
215 Returns zero upon success and non-zero when an error occurred.
219 Signature: I<int> B<registerRead> (I<String> name,
220 I<CollectdReadInterface> object)
222 Registers the B<read> function of I<object> with the daemon.
224 Returns zero upon success and non-zero when an error occurred.
228 Signature: I<int> B<registerWrite> (I<String> name,
229 I<CollectdWriteInterface> object)
231 Registers the B<write> function of I<object> with the daemon.
233 Returns zero upon success and non-zero when an error occurred.
235 =head2 registerShutdown
237 Signature: I<int> B<registerShutdown> (I<String> name,
238 I<CollectdShutdownInterface> object);
240 Registers the B<shutdown> function of I<object> with the daemon.
242 Returns zero upon success and non-zero when an error occurred.
244 =head2 dispatchValues
246 Signature: I<int> B<dispatchValues> (I<ValueList>)
248 Passes the values represented by the B<ValueList> object to the
249 C<plugin_dispatch_values> function of the daemon. The "data set" (or list of
250 "data sources") associated with the object are ignored, because
251 C<plugin_dispatch_values> will automatically lookup the required data set. It
252 is therefore absolutely okay to leave this blank.
254 Returns zero upon success or non-zero upon failure.
258 Signature: I<DataSet> B<getDS> (I<String>)
260 Returns the approrpate I<type> or B<null> if the type is not defined.
264 Signature: I<void> B<logError> (I<String>)
266 Sends a log message with severity B<ERROR> to the daemon.
270 Signature: I<void> B<logWarning> (I<String>)
272 Sends a log message with severity B<WARNING> to the daemon.
276 Signature: I<void> B<logNotice> (I<String>)
278 Sends a log message with severity B<NOTICE> to the daemon.
282 Signature: I<void> B<logInfo> (I<String>)
284 Sends a log message with severity B<INFO> to the daemon.
288 Signature: I<void> B<logDebug> (I<String>)
290 Sends a log message with severity B<DEBUG> to the daemon.
301 Florian Forster E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt>