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 available classes are:
  41
  42 =over 4
  43
  44 =item B<org.collectd.api.OConfigValue>
  45
  46 Corresponds to C<oconfig_value_t>, defined in F<src/liboconfig/oconfig.h>.
  47
  48 =item B<org.collectd.api.OConfigItem>
  49
  50 Corresponds to C<oconfig_item_t>, defined in F<src/liboconfig/oconfig.h>.
  51
  52 =item B<org.collectd.api.DataSource>
  53
  54 Corresponds to C<data_source_t>, defined in F<src/plugin.h>.
  55
  56 =item B<org.collectd.api.DataSet>
  57
  58 Corresponds to C<data_set_t>, defined in F<src/plugin.h>.
  59
  60 =item B<org.collectd.api.ValueList>
  61
  62 Corresponds to C<value_list_t>, defined in F<src/plugin.h>.
  63
  64 =back
  65
  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.
  69
  70 The API functions that are available from Java are implemented as I<static>
  71 functions of the B<org.collectd.api.Collectd> class.
  72 See L<"CALLING API FUNCTIONS"> below for details.
  73
  74 =head1 REGISTERING CALLBACKS
  75
  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<Collectd>,
  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.
  82
  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.
  88
  89 Each callback method is now explained in more detail:
  90
  91 =head2 config callback
  92
  93 Interface: B<org.collectd.api.CollectdConfigInterface>
  94
  95 Signature: I<int> B<config> (I<OConfigItem> ci)
  96
  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.
 102
 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.
 105
 106 =head2 init callback
 107
 108 Interface: B<org.collectd.api.CollectdInitInterface>
 109
 110 Signature: I<int> B<init> ()
 111
 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.
 115
 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.
 118
 119 =head2 read callback
 120
 121 Interface: B<org.collectd.api.CollectdReadInterface>
 122
 123 Signature: I<int> B<read> ()
 124
 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">
 128 below.
 129
 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
 134 "read"-functions.
 135
 136 =head2 write callback
 137
 138 Interface: B<org.collectd.api.CollectdWriteInterface>
 139
 140 Signature: I<int> B<write> (I<ValueList> vl)
 141
 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.
 147
 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.
 150
 151 =head2 flush callback
 152
 153 Interface: B<org.collectd.api.CollectdFlushInterface>
 154
 155 Signature: I<int> B<flush> (I<int> timeout, I<String> identifier)
 156
 157 This method is called when the daemon received a flush command. This can either
 158 be done using the C<USR1> signal (see L<collectd(1)>) or using the I<unixsock>
 159 plugin (see L<collectd-unixsock(5)>).
 160
 161 If I<timeout> is greater than zero, only values older than this number of
 162 seconds should be flushed. To signal that all values should be flushed
 163 regardless of age, this argument is set to a negative number.
 164
 165 The I<identifier> specifies which value should be flushed. If it is not
 166 possible to flush one specific value, flush all values. To signal that all
 167 values should be flushed, this argument is set to I<null>.
 168
 169 To signal success, this method has to return zero. Anything else will be
 170 considered an error condition and cause an appropriate message to be logged.
 171
 172 =head2 shutdown callback
 173
 174 Interface: B<org.collectd.api.CollectdShutdownInterface>
 175
 176 Signature: I<int> B<shutdown> ()
 177
 178 This method is called when the daemon is shutting down. You should not rely on
 179 the destructor to clean up behind the object but use this function instead.
 180
 181 To signal success, this method has to return zero. Anything else will be
 182 considered an error condition and cause an appropriate message to be logged.
 183
 184 =head2 log callback
 185
 186 Interface: B<org.collectd.api.CollectdLogInterface>
 187
 188 Signature: I<void> B<log> (I<int> severity, I<String> message)
 189
 190 This callback can be used to receive log messages from the daemon.
 191
 192 The argument I<severity> is one of:
 193
 194 =over 4
 195
 196 =item *
 197
 198 org.collectd.api.Collectd.LOG_ERR
 199
 200 =item *
 201
 202 org.collectd.api.Collectd.LOG_WARNING
 203
 204 =item *
 205
 206 org.collectd.api.Collectd.LOG_NOTICE
 207
 208 =item *
 209
 210 org.collectd.api.Collectd.LOG_INFO
 211
 212 =item *
 213
 214 org.collectd.api.Collectd.LOG_DEBUG
 215
 216 =back
 217
 218 The function does not return any value.
 219
 220 =head2 Example
 221
 222 This short example demonstrates how to register a read callback with the
 223 daemon:
 224
 225   import org.collectd.api.Collectd;
 226   import org.collectd.api.ValueList;
 227
 228   import org.collectd.api.CollectdReadInterface;
 229
 230   public class Foobar implements CollectdReadInterface
 231   {
 232     public Foobar ()
 233     {
 234       Collectd.registerRead ("Foobar", this);
 235     }
 236
 237     public int read ()
 238     {
 239       ValueList vl;
 240
 241       /* Do something... */
 242
 243       Collectd.dispatchValues (vl);
 244     }
 245   }
 246
 247 =head1 CALLING API FUNCTIONS
 248
 249 All collectd API functions that are available to Java plugins are implemented
 250 as I<publicE<nbsp>static> functions of the B<org.collectd.api.Collectd> class.
 251 This makes calling these functions pretty straight forward.
 252
 253 The following are the currently exported functions. For information on the
 254 interfaces used, please see L<"REGISTERING CALLBACKS"> above.
 255
 256 =head2 registerConfig
 257
 258 Signature: I<int> B<registerConfig> (I<String> name,
 259 I<CollectdConfigInterface> object);
 260
 261 Registers the B<config> function of I<object> with the daemon.
 262
 263 Returns zero upon success and non-zero when an error occurred.
 264
 265 =head2 registerInit
 266
 267 Signature: I<int> B<registerInit> (I<String> name,
 268 I<CollectdInitInterface> object);
 269
 270 Registers the B<init> function of I<object> with the daemon.
 271
 272 Returns zero upon success and non-zero when an error occurred.
 273
 274 =head2 registerRead
 275
 276 Signature: I<int> B<registerRead> (I<String> name,
 277 I<CollectdReadInterface> object)
 278
 279 Registers the B<read> function of I<object> with the daemon.
 280
 281 Returns zero upon success and non-zero when an error occurred.
 282
 283 =head2 registerWrite
 284
 285 Signature: I<int> B<registerWrite> (I<String> name,
 286 I<CollectdWriteInterface> object)
 287
 288 Registers the B<write> function of I<object> with the daemon.
 289
 290 Returns zero upon success and non-zero when an error occurred.
 291
 292 =head2 registerFlush
 293
 294 Signature: I<int> B<registerFlush> (I<String> name,
 295 I<CollectdFlushInterface> object)
 296
 297 Registers the B<flush> function of I<object> with the daemon.
 298
 299 Returns zero upon success and non-zero when an error occurred.
 300
 301 =head2 registerShutdown
 302
 303 Signature: I<int> B<registerShutdown> (I<String> name,
 304 I<CollectdShutdownInterface> object);
 305
 306 Registers the B<shutdown> function of I<object> with the daemon.
 307
 308 Returns zero upon success and non-zero when an error occurred.
 309
 310 =head2 registerLog
 311
 312 Signature: I<int> B<registerLog> (I<String> name,
 313 I<CollectdLogInterface> object);
 314
 315 Registers the B<log> function of I<object> with the daemon.
 316
 317 Returns zero upon success and non-zero when an error occurred.
 318
 319 =head2 dispatchValues
 320
 321 Signature: I<int> B<dispatchValues> (I<ValueList>)
 322
 323 Passes the values represented by the B<ValueList> object to the
 324 C<plugin_dispatch_values> function of the daemon. The "data set" (or list of
 325 "data sources") associated with the object are ignored, because
 326 C<plugin_dispatch_values> will automatically lookup the required data set. It
 327 is therefore absolutely okay to leave this blank.
 328
 329 Returns zero upon success or non-zero upon failure.
 330
 331 =head2 getDS
 332
 333 Signature: I<DataSet> B<getDS> (I<String>)
 334
 335 Returns the approrpate I<type> or B<null> if the type is not defined.
 336
 337 =head2 logError
 338
 339 Signature: I<void> B<logError> (I<String>)
 340
 341 Sends a log message with severity B<ERROR> to the daemon.
 342
 343 =head2 logWarning
 344
 345 Signature: I<void> B<logWarning> (I<String>)
 346
 347 Sends a log message with severity B<WARNING> to the daemon.
 348
 349 =head2 logNotice
 350
 351 Signature: I<void> B<logNotice> (I<String>)
 352
 353 Sends a log message with severity B<NOTICE> to the daemon.
 354
 355 =head2 logInfo
 356
 357 Signature: I<void> B<logInfo> (I<String>)
 358
 359 Sends a log message with severity B<INFO> to the daemon.
 360
 361 =head2 logDebug
 362
 363 Signature: I<void> B<logDebug> (I<String>)
 364
 365 Sends a log message with severity B<DEBUG> to the daemon.
 366
 367 =head1 SEE ALSO
 368
 369 L<collectd(1)>,
 370 L<collectd.conf(5)>,
 371 L<collectd-perl(5)>,
 372 L<types.db(5)>
 373
 374 =head1 AUTHOR
 375
 376 Florian Forster E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt>
 377