Bumped version to 4.7.5; Updated ChangeLog.
[collectd.git] / src / collectd-java.pod
1 =head1 NAME
2
3 collectd-java - Documentation of collectd's "java plugin"
4
5 =head1 SYNOPSIS
6
7  LoadPlugin "java"
8  <Plugin "java">
9    JVMArg "-verbose:jni"
10    JVMArg "-Djava.class.path=/opt/collectd/lib/collectd/bindings/java"
11    
12    LoadPlugin "org.collectd.java.Foobar"
13    <Plugin "org.collectd.java.Foobar">
14      # To be parsed by the plugin
15    </Plugin>
16  </Plugin>
17
18 =head1 DESCRIPTION
19
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.
23
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.
26
27 =head1 CONFIGURATION
28
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>>.
32
33 =head1 OVERVIEW
34
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.
39
40 The I<Java> plugin will create one object of each class configured with the
41 B<LoadPlugin> option. The constructor of this class can then register "callback
42 methods", i.E<nbsp>e. methods that will be called by the daemon when
43 appropriate.
44
45 The available classes are:
46
47 =over 4
48
49 =item B<org.collectd.api.Collectd>
50
51 All API functions exported to Java are implemented as static functions of this
52 class. See L<"EXPORTED API FUNCTIONS"> below.
53
54 =item B<org.collectd.api.OConfigValue>
55
56 Corresponds to C<oconfig_value_t>, defined in F<src/liboconfig/oconfig.h>.
57
58 =item B<org.collectd.api.OConfigItem>
59
60 Corresponds to C<oconfig_item_t>, defined in F<src/liboconfig/oconfig.h>.
61
62 =item B<org.collectd.api.DataSource>
63
64 Corresponds to C<data_source_t>, defined in F<src/plugin.h>.
65
66 =item B<org.collectd.api.DataSet>
67
68 Corresponds to C<data_set_t>, defined in F<src/plugin.h>.
69
70 =item B<org.collectd.api.ValueList>
71
72 Corresponds to C<value_list_t>, defined in F<src/plugin.h>.
73
74 =item B<org.collectd.api.Notification>
75
76 Corresponds to C<notification_t>, defined in F<src/plugin.h>.
77
78 =back
79
80 In the remainder of this document, we'll use the short form of these names, for
81 example B<ValueList>. In order to be able to use these abbreviated names, you
82 need to B<import> the classes.
83
84 =head1 EXPORTED API FUNCTIONS
85
86 All collectd API functions that are available to Java plugins are implemented
87 as I<publicE<nbsp>static> functions of the B<Collectd> class. This makes
88 calling these functions pretty straight forward. For example, to send an error
89 message to the daemon, you'd do something like this:
90
91   Collectd.logError ("That wasn't chicken!");
92
93 The following are the currently exported functions.
94
95 =head2 registerConfig
96
97 Signature: I<int> B<registerConfig> (I<String> name,
98 I<CollectdConfigInterface> object);
99
100 Registers the B<config> function of I<object> with the daemon.
101
102 Returns zero upon success and non-zero when an error occurred.
103
104 See L<"config callback"> below.
105
106 =head2 registerInit
107
108 Signature: I<int> B<registerInit> (I<String> name,
109 I<CollectdInitInterface> object);
110
111 Registers the B<init> function of I<object> with the daemon.
112
113 Returns zero upon success and non-zero when an error occurred.
114
115 See L<"init callback"> below.
116
117 =head2 registerRead
118
119 Signature: I<int> B<registerRead> (I<String> name,
120 I<CollectdReadInterface> object)
121
122 Registers the B<read> function of I<object> with the daemon.
123
124 Returns zero upon success and non-zero when an error occurred.
125
126 See L<"read callback"> below.
127
128 =head2 registerWrite
129
130 Signature: I<int> B<registerWrite> (I<String> name,
131 I<CollectdWriteInterface> object)
132
133 Registers the B<write> function of I<object> with the daemon.
134
135 Returns zero upon success and non-zero when an error occurred.
136
137 See L<"write callback"> below.
138
139 =head2 registerFlush
140
141 Signature: I<int> B<registerFlush> (I<String> name,
142 I<CollectdFlushInterface> object)
143
144 Registers the B<flush> function of I<object> with the daemon.
145
146 Returns zero upon success and non-zero when an error occurred.
147
148 See L<"flush callback"> below.
149
150 =head2 registerShutdown
151
152 Signature: I<int> B<registerShutdown> (I<String> name,
153 I<CollectdShutdownInterface> object);
154
155 Registers the B<shutdown> function of I<object> with the daemon.
156
157 Returns zero upon success and non-zero when an error occurred.
158
159 See L<"shutdown callback"> below.
160
161 =head2 registerLog
162
163 Signature: I<int> B<registerLog> (I<String> name,
164 I<CollectdLogInterface> object);
165
166 Registers the B<log> function of I<object> with the daemon.
167
168 Returns zero upon success and non-zero when an error occurred.
169
170 See L<"log callback"> below.
171
172 =head2 registerNotification
173
174 Signature: I<int> B<registerNotification> (I<String> name,
175 I<CollectdNotificationInterface> object);
176
177 Registers the B<notification> function of I<object> with the daemon.
178
179 Returns zero upon success and non-zero when an error occurred.
180
181 See L<"notification callback"> below.
182
183 =head2 registerMatch
184
185 Signature: I<int> B<registerMatch> (I<String> name,
186 I<CollectdMatchFactoryInterface> object);
187
188 Registers the B<createMatch> function of I<object> with the daemon.
189
190 Returns zero upon success and non-zero when an error occurred.
191
192 See L<"match callback"> below.
193
194 =head2 registerTarget
195
196 Signature: I<int> B<registerTarget> (I<String> name,
197 I<CollectdTargetFactoryInterface> object);
198
199 Registers the B<createTarget> function of I<object> with the daemon.
200
201 Returns zero upon success and non-zero when an error occurred.
202
203 See L<"target callback"> below.
204
205 =head2 dispatchValues
206
207 Signature: I<int> B<dispatchValues> (I<ValueList>)
208
209 Passes the values represented by the B<ValueList> object to the
210 C<plugin_dispatch_values> function of the daemon. The "data set" (or list of
211 "data sources") associated with the object are ignored, because
212 C<plugin_dispatch_values> will automatically lookup the required data set. It
213 is therefore absolutely okay to leave this blank.
214
215 Returns zero upon success or non-zero upon failure.
216
217 =head2 getDS
218
219 Signature: I<DataSet> B<getDS> (I<String>)
220
221 Returns the appropriate I<type> or B<null> if the type is not defined.
222
223 =head2 logError
224
225 Signature: I<void> B<logError> (I<String>)
226
227 Sends a log message with severity B<ERROR> to the daemon.
228
229 =head2 logWarning
230
231 Signature: I<void> B<logWarning> (I<String>)
232
233 Sends a log message with severity B<WARNING> to the daemon.
234
235 =head2 logNotice
236
237 Signature: I<void> B<logNotice> (I<String>)
238
239 Sends a log message with severity B<NOTICE> to the daemon.
240
241 =head2 logInfo
242
243 Signature: I<void> B<logInfo> (I<String>)
244
245 Sends a log message with severity B<INFO> to the daemon.
246
247 =head2 logDebug
248
249 Signature: I<void> B<logDebug> (I<String>)
250
251 Sends a log message with severity B<DEBUG> to the daemon.
252
253 =head1 REGISTERING CALLBACKS
254
255 When starting up, collectd creates an object of each configured class. The
256 constructor of this class should then register "callbacks" with the daemon,
257 using the appropriate static functions in B<Collectd>,
258 see L<"EXPORTED API FUNCTIONS"> above. To register a callback, the object being
259 passed to one of the register functions must implement an appropriate
260 interface, which are all in the B<org.collectd.api> namespace.
261
262 A constructor may register any number of these callbacks, even none. An object
263 without callback methods is never actively called by collectd, but may still
264 call the exported API functions. One could, for example, start a new thread in
265 the constructor and dispatch (submit to the daemon) values asynchronously,
266 whenever one is available.
267
268 Each callback method is now explained in more detail:
269
270 =head2 config callback
271
272 Interface: B<org.collectd.api.CollectdConfigInterface>
273
274 Signature: I<int> B<config> (I<OConfigItem> ci)
275
276 This method is passed a B<OConfigItem> object, if both, method and
277 configuration, are available. B<OConfigItem> is the root of a tree representing
278 the configuration for this plugin. The root itself is the representation of the
279 B<E<lt>PluginE<nbsp>/E<gt>> block, so in next to all cases the children of the
280 root are the first interesting objects.
281
282 To signal success, this method has to return zero. Anything else will be
283 considered an error condition and the plugin will be disabled entirely.
284
285 See L<"registerConfig"> above.
286
287 =head2 init callback
288
289 Interface: B<org.collectd.api.CollectdInitInterface>
290
291 Signature: I<int> B<init> ()
292
293 This method is called after the configuration has been handled. It is
294 supposed to set up the plugin. e.E<nbsp>g. start threads, open connections, or
295 check if can do anything useful at all.
296
297 To signal success, this method has to return zero. Anything else will be
298 considered an error condition and the plugin will be disabled entirely.
299
300 See L<"registerInit"> above.
301
302 =head2 read callback
303
304 Interface: B<org.collectd.api.CollectdReadInterface>
305
306 Signature: I<int> B<read> ()
307
308 This method is called periodically and is supposed to gather statistics in
309 whatever fashion. These statistics are represented as a B<ValueList> object and
310 sent to the daemon using L<dispatchValues|"dispatchValues">.
311
312 To signal success, this method has to return zero. Anything else will be
313 considered an error condition and cause an appropriate message to be logged.
314 Currently, returning non-zero does not have any other effects. In particular,
315 Java "read"-methods are not suspended for increasing intervals like C
316 "read"-functions.
317
318 See L<"registerRead"> above.
319
320 =head2 write callback
321
322 Interface: B<org.collectd.api.CollectdWriteInterface>
323
324 Signature: I<int> B<write> (I<ValueList> vl)
325
326 This method is called whenever a value is dispatched to the daemon. The
327 corresponding C "write"-functions are passed a C<data_set_t>, so they can
328 decide which values are absolute values (gauge) and which are counter values.
329 To get the corresponding C<ListE<lt>DataSourceE<gt>>, call the B<getDataSource>
330 method of the B<ValueList> object.
331
332 To signal success, this method has to return zero. Anything else will be
333 considered an error condition and cause an appropriate message to be logged.
334
335 See L<"registerWrite"> above.
336
337 =head2 flush callback
338
339 Interface: B<org.collectd.api.CollectdFlushInterface>
340
341 Signature: I<int> B<flush> (I<int> timeout, I<String> identifier)
342
343 This method is called when the daemon received a flush command. This can either
344 be done using the C<USR1> signal (see L<collectd(1)>) or using the I<unixsock>
345 plugin (see L<collectd-unixsock(5)>).
346
347 If I<timeout> is greater than zero, only values older than this number of
348 seconds should be flushed. To signal that all values should be flushed
349 regardless of age, this argument is set to a negative number.
350
351 The I<identifier> specifies which value should be flushed. If it is not
352 possible to flush one specific value, flush all values. To signal that all
353 values should be flushed, this argument is set to I<null>.
354
355 To signal success, this method has to return zero. Anything else will be
356 considered an error condition and cause an appropriate message to be logged.
357
358 See L<"registerFlush"> above.
359
360 =head2 shutdown callback
361
362 Interface: B<org.collectd.api.CollectdShutdownInterface>
363
364 Signature: I<int> B<shutdown> ()
365
366 This method is called when the daemon is shutting down. You should not rely on
367 the destructor to clean up behind the object but use this function instead.
368
369 To signal success, this method has to return zero. Anything else will be
370 considered an error condition and cause an appropriate message to be logged.
371
372 See L<"registerShutdown"> above.
373
374 =head2 log callback
375
376 Interface: B<org.collectd.api.CollectdLogInterface>
377
378 Signature: I<void> B<log> (I<int> severity, I<String> message)
379
380 This callback can be used to receive log messages from the daemon.
381
382 The argument I<severity> is one of:
383
384 =over 4
385
386 =item *
387
388 org.collectd.api.Collectd.LOG_ERR
389
390 =item *
391
392 org.collectd.api.Collectd.LOG_WARNING
393
394 =item *
395
396 org.collectd.api.Collectd.LOG_NOTICE
397
398 =item *
399
400 org.collectd.api.Collectd.LOG_INFO
401
402 =item *
403
404 org.collectd.api.Collectd.LOG_DEBUG
405
406 =back
407
408 The function does not return any value.
409
410 See L<"registerLog"> above.
411
412 =head2 notification callback
413
414 Interface: B<org.collectd.api.CollectdNotificationInterface>
415
416 Signature: I<int> B<notification> (I<Notification> n)
417
418 This callback can be used to receive notifications from the daemon.
419
420 To signal success, this method has to return zero. Anything else will be
421 considered an error condition and cause an appropriate message to be logged.
422
423 See L<"registerNotification"> above.
424
425 =head2 match callback
426
427 The match (and target, see L<"target callback"> below) callbacks work a bit
428 different from the other callbacks above: You don't register a match callback
429 with the daemon directly, but you register a function which, when called,
430 creates an appropriate object. The object creating the "match" objects is
431 called "match factory".
432
433 See L<"registerMatch"> above.
434
435 =head3 Factory object
436
437 Interface: B<org.collectd.api.CollectdMatchFactoryInterface>
438
439 Signature: I<CollectdMatchInterface> B<createMatch>
440 (I<OConfigItem> ci);
441
442 Called by the daemon to create "match" objects.
443
444 Returns: A new object which implements the B<CollectdMatchInterface> interface.
445
446 =head3 Match object
447
448 Interface: B<org.collectd.api.CollectdMatchInterface>
449
450 Signature: I<int> B<match> (I<DataSet> ds, I<ValueList> vl);
451
452 Called when processing a chain to determine whether or not a I<ValueList>
453 matches. How values are matches is up to the implementing class.
454
455 Has to return one of:
456
457 =over 4
458
459 =item *
460
461 B<Collectd.FC_MATCH_NO_MATCH>
462
463 =item *
464
465 B<Collectd.FC_MATCH_MATCHES>
466
467 =back
468
469 =head2 target callback
470
471 The target (and match, see L<"match callback"> above) callbacks work a bit
472 different from the other callbacks above: You don't register a target callback
473 with the daemon directly, but you register a function which, when called,
474 creates an appropriate object. The object creating the "target" objects is
475 called "target factory".
476
477 See L<"registerTarget"> above.
478
479 =head3 Factory object
480
481 Interface: B<org.collectd.api.CollectdTargetFactoryInterface>
482
483 Signature: I<CollectdTargetInterface> B<createTarget>
484 (I<OConfigItem> ci);
485
486 Called by the daemon to create "target" objects.
487
488 Returns: A new object which implements the B<CollectdTargetInterface>
489 interface.
490
491 =head3 Target object
492
493 Interface: B<org.collectd.api.CollectdTargetInterface>
494
495 Signature: I<int> B<invoke> (I<DataSet> ds, I<ValueList> vl);
496
497 Called when processing a chain to perform some action. The action performed is
498 up to the implementing class.
499
500 Has to return one of:
501
502 =over 4
503
504 =item *
505
506 B<Collectd.FC_TARGET_CONTINUE>
507
508 =item *
509
510 B<Collectd.FC_TARGET_STOP>
511
512 =item *
513
514 B<Collectd.FC_TARGET_RETURN>
515
516 =back
517
518 =head1 EXAMPLE
519
520 This short example demonstrates how to register a read callback with the
521 daemon:
522
523   import org.collectd.api.Collectd;
524   import org.collectd.api.ValueList;
525   
526   import org.collectd.api.CollectdReadInterface;
527   
528   public class Foobar implements CollectdReadInterface
529   {
530     public Foobar ()
531     {
532       Collectd.registerRead ("Foobar", this);
533     }
534     
535     public int read ()
536     {
537       ValueList vl;
538       
539       /* Do something... */
540       
541       Collectd.dispatchValues (vl);
542     }
543   }
544
545 =head1 SEE ALSO
546
547 L<collectd(1)>,
548 L<collectd.conf(5)>,
549 L<collectd-perl(5)>,
550 L<types.db(5)>
551
552 =head1 AUTHOR
553
554 Florian Forster E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt>
555