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> and I<org.collectd.protocol> namespaces.
  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.protocol.DataSource>
  53
  54 Corresponds to C<data_source_t>, defined in F<src/plugin.h>.
  55
  56 =item B<java.util.ListE<lt>org.collectd.protocol.DataSourceE<gt>>
  57
  58 Corresponds to C<data_set_t>, defined in F<src/plugin.h>.
  59
  60 =item B<org.collectd.protocol.ValueList>
  61
  62 Corresponds to C<value_list_t>, defined in F<src/plugin.h>.
  63
  64 =back
  65
  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.
  69
  70 =head1 CREATING CALLBACKS
  71
  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
  75 I<"signature">.
  76
  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.
  80
  81 Currently used callback methods are:
  82
  83 =over 4
  84
  85 =item Constructor ()
  86
  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.
  90
  91 =item I<int> B<Config> (I<org.collectd.api.OConfigItem>)
  92
  93 Configuration for the plugin. This is the first method that is called after the
  94 object has been created.
  95
  96 =item I<int> B<Init> ()
  97
  98 Initialization of the plugin. This item is called after B<Config> has been
  99 called.
 100
 101 =item I<int> B<Read> ()
 102
 103 Called when the plugin should acquire new values.
 104
 105 =item I<int> B<Write> (I<org.collectd.protocol.ValueList>)
 106
 107 Called to have the plugin store values.
 108
 109 =item I<int> B<Shutdown> ()
 110
 111 Called when the daemon is shutting down.
 112
 113 =back
 114
 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.
 120
 121 Each callback method is now explained in more detail:
 122
 123 =head2 Config callback
 124
 125 Signature: I<int> B<Config> (I<org.collectd.api.OConfigItem>)
 126
 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.
 132
 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.
 135
 136 =head2 Init callback
 137
 138 Signature: I<int> B<Init> ()
 139
 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.
 143
 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.
 146
 147 =head2 Read callback
 148
 149 Signature: I<int> B<Read> ()
 150
 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">
 154 below.
 155
 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
 160 "read"-functions.
 161
 162 =head2 Write callback
 163
 164 Signature: I<int> B<Write> (I<org.collectd.protocol.ValueList>)
 165
 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.
 171
 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.
 174
 175 =head2 Shutdown callback
 176
 177 Signature: I<int> B<Shutdown> ()
 178
 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.
 181
 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.
 184
 185 =head1 CALLING API FUNCTIONS
 186
 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.
 190
 191 The currently exported functions are:
 192
 193 =over 4
 194
 195 =item I<int> B<DispatchValues> (I<org.collectd.protocol.ValueList>)
 196
 197 Corresponds to C<plugin_dispatch_values>, defined in F<src/plugin.h>.
 198
 199 =back
 200
 201 Each API function is now explained in more detail:
 202
 203 =head2 DispatchValues
 204
 205 Signature: I<int> B<DispatchValues> (I<org.collectd.protocol.ValueList>)
 206
 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.
 212
 213 Returns zero upon success or non-zero upon failure.
 214
 215 =head1 SEE ALSO
 216
 217 L<collectd(1)>,
 218 L<collectd.conf(5)>,
 219 L<collectd-perl(5)>,
 220 L<types.db(5)>
 221
 222 =head1 AUTHOR
 223
 224 Florian Forster E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt>
 225