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> and I<org.collectd.protocol> namespaces.
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.protocol.DataSource>
54 Corresponds to C<data_source_t>, defined in F<src/plugin.h>.
56 =item B<java.util.ListE<lt>org.collectd.protocol.DataSourceE<gt>>
58 Corresponds to C<data_set_t>, defined in F<src/plugin.h>.
60 =item B<org.collectd.protocol.ValueList>
62 Corresponds to C<value_list_t>, defined in F<src/plugin.h>.
66 The API functions that are available from Java are implemented as I<static>
67 functions of the B<org.collectd.api.CollectdAPI> class.
68 See L<"CALLING API FUNCTIONS"> below for details.
70 =head1 CREATING CALLBACKS
72 Callback functions, i.E<nbsp>e. functions that are called by collectd, differ
73 from their C equivalents in that they don't need to be "registered". Instead,
74 they have a fixed name, argument list and return value, usually called
77 When starting up, the plugin will instantiate one object of your class, using
78 the constructor without arguments. All other functions called by the Java
79 plugin are methods of this object.
81 Currently used callback methods are:
87 Used to create an object of the custom class. The name of the constructor
88 depends on your classes' name, of course. It must have the signature shown
89 above, i.E<nbsp>e. an empty argument list, though.
91 =item I<int> B<Config> (I<org.collectd.api.OConfigItem>)
93 Configuration for the plugin. This is the first method that is called after the
94 object has been created.
96 =item I<int> B<Init> ()
98 Initialization of the plugin. This item is called after B<Config> has been
101 =item I<int> B<Read> ()
103 Called when the plugin should acquire new values.
105 =item I<int> B<Write> (I<org.collectd.protocol.ValueList>)
107 Called to have the plugin store values.
109 =item I<int> B<Shutdown> ()
111 Called when the daemon is shutting down.
115 A plugin may implement any number of these callbacks, from all to none. An
116 object without callback methods is never called by collectd, but may still
117 call the exported API functions. One could, for example, start a new thread in
118 the constructor and dispatch (submit to the daemon) values asynchronously,
119 whenever one is available.
121 Each callback method is now explained in more detail:
123 =head2 Config callback
125 Signature: I<int> B<Config> (I<org.collectd.api.OConfigItem>)
127 This method is passed a B<OConfigItem> object, if both, method and
128 configuration, are available. B<OConfigItem> is the root of a tree representing
129 the configuration for this plugin. The root itself is the representation of the
130 B<E<lt>PluginE<nbsp>/E<gt>> block, so in next to all cases the children of the
131 root are the first interesting objects.
133 To signal success, this method has to return zero. Anything else will be
134 considered an error condition and the plugin will be disabled entirely.
138 Signature: I<int> B<Init> ()
140 This method is called after the configuration has been handled. It is
141 supposed to set up the plugin. e.E<nbsp>g. start threads, open connections, or
142 check if can do anything useful at all.
144 To signal success, this method has to return zero. Anything else will be
145 considered an error condition and the plugin will be disabled entirely.
149 Signature: I<int> B<Read> ()
151 This method is called periodically and is supposed to gather statistics in
152 whatever fashion. These statistics are represented as a B<ValueList> object and
153 sent to the daemon using B<DispatchValues>, see L<"CALLING API FUNCTIONS">
156 To signal success, this method has to return zero. Anything else will be
157 considered an error condition and cause an appropriate message to be logged.
158 Currently, returning non-zero does not have any other effects. In particular,
159 Java "read"-methods are not suspended for increasing intervals like C
162 =head2 Write callback
164 Signature: I<int> B<Write> (I<org.collectd.protocol.ValueList>)
166 This method is called whenever a value is dispatched to the daemon. The
167 corresponding C "write"-functions are passed a C<data_set_t>, so they can
168 decide which values are absolute values (gauge) and which are counter values.
169 To get the corresponding C<ListE<lt>DataSourceE<gt>>, call the B<getDataSource>
170 method of the B<ValueList> object.
172 To signal success, this method has to return zero. Anything else will be
173 considered an error condition and cause an appropriate message to be logged.
175 =head2 Shutdown callback
177 Signature: I<int> B<Shutdown> ()
179 This method is called when the daemon is shutting down. You should not rely on
180 the destructor to clean up behind the object but use this function instead.
182 To signal success, this method has to return zero. Anything else will be
183 considered an error condition and cause an appropriate message to be logged.
185 =head1 CALLING API FUNCTIONS
187 All collectd API functions that are available to Java plugins are implemented
188 as I<publicE<nbsp>static> functions of the B<org.collectd.api.CollectdAPI>
189 class. This makes calling these functions pretty straight forward.
191 The currently exported functions are:
195 =item I<int> B<DispatchValues> (I<org.collectd.protocol.ValueList>)
197 Corresponds to C<plugin_dispatch_values>, defined in F<src/plugin.h>.
201 Each API function is now explained in more detail:
203 =head2 DispatchValues
205 Signature: I<int> B<DispatchValues> (I<org.collectd.protocol.ValueList>)
207 Passes the values represented by the B<ValueList> object to the
208 C<plugin_dispatch_values> function of the daemon. The "data set" (or list of
209 "data sources") associated with the object are ignored, because
210 C<plugin_dispatch_values> will automatically lookup the required data set. It
211 is therefore absolutely okay to leave this blank.
213 Returns zero upon success or non-zero upon failure.
224 Florian Forster E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt>