=head1 NAME

collectd-java - Documentation of collectd's "java plugin"

=head1 SYNOPSIS

 LoadPlugin "java"
 <Plugin "java">
   JVMArg "-verbose:jni"
   JVMArg "-Djava.class.path=/opt/collectd/lib/collectd/bindings/java"
   
   LoadPlugin "org.collectd.java.Foobar"
   <Plugin "org.collectd.java.Foobar">
     # To be parsed by the plugin
   </Plugin>
 </Plugin>

=head1 DESCRIPTION

The I<Java> plugin embeds a I<Java Virtual Machine> (JVM) into I<collectd> and
provides a Java interface to part of collectd's API. This makes it possible to
write additions to the daemon in Java.

This plugin is similar in nature to, but shares no code with, the I<Perl>
plugin by Sebastian Harl, see L<collectd-perl(5)> for details.

=head1 CONFIGURATION

A short outline of this plugin's configuration can be seen in L<"SYNOPSIS">
above. For a complete list of all configuration options and their semantics
please read L<collectd.conf(5)/Plugin C<java>>.

=head1 OVERVIEW

When writing additions for collectd in Java, the underlying C base is mostly
hidden from you. All complex data types are converted to their Java counterparts
before they're passed to your functions. These Java classes reside in the
I<org.collectd.api> namespace.

The available classes are:

=over 4

=item B<org.collectd.api.OConfigValue>

Corresponds to C<oconfig_value_t>, defined in F<src/liboconfig/oconfig.h>.

=item B<org.collectd.api.OConfigItem>

Corresponds to C<oconfig_item_t>, defined in F<src/liboconfig/oconfig.h>.

=item B<org.collectd.api.DataSource>

Corresponds to C<data_source_t>, defined in F<src/plugin.h>.

=item B<org.collectd.api.DataSet>

Corresponds to C<data_set_t>, defined in F<src/plugin.h>.

=item B<org.collectd.api.ValueList>

Corresponds to C<value_list_t>, defined in F<src/plugin.h>.

=back

In the remainder of this document, we'll use the short form of these names, for
example B<ValueList>. In order to be able to use these abbreviated names, you
need to B<import> the classes.

The API functions that are available from Java are implemented as I<static>
functions of the B<org.collectd.api.Collectd> class.
See L<"CALLING API FUNCTIONS"> below for details.

=head1 REGISTERING CALLBACKS

When starting up, collectd creates an object of each configured class. The
constructor of this class should then register "callbacks" with the daemon,
using the appropriate static functions in B<Collectd>,
see L<"CALLING API FUNCTIONS"> below. To register a callback, the object being
passed to one of the register functions must implement an appropriate
interface, which are all in the B<org.collectd.api> namespace.

A constructor may register any number of these callbacks, even none. An object
without callback methods is never actively called by collectd, but may still
call the exported API functions. One could, for example, start a new thread in
the constructor and dispatch (submit to the daemon) values asynchronously,
whenever one is available.

Each callback method is now explained in more detail:

=head2 config callback

Interface: B<org.collectd.api.CollectdConfigInterface>

Signature: I<int> B<config> (I<OConfigItem> ci)

This method is passed a B<OConfigItem> object, if both, method and
configuration, are available. B<OConfigItem> is the root of a tree representing
the configuration for this plugin. The root itself is the representation of the
B<E<lt>PluginE<nbsp>/E<gt>> block, so in next to all cases the children of the
root are the first interesting objects.

To signal success, this method has to return zero. Anything else will be
considered an error condition and the plugin will be disabled entirely.

=head2 init callback

Interface: B<org.collectd.api.CollectdInitInterface>

Signature: I<int> B<init> ()

This method is called after the configuration has been handled. It is
supposed to set up the plugin. e.E<nbsp>g. start threads, open connections, or
check if can do anything useful at all.

To signal success, this method has to return zero. Anything else will be
considered an error condition and the plugin will be disabled entirely.

=head2 read callback

Interface: B<org.collectd.api.CollectdReadInterface>

Signature: I<int> B<read> ()

This method is called periodically and is supposed to gather statistics in
whatever fashion. These statistics are represented as a B<ValueList> object and
sent to the daemon using B<dispatchValues>, see L<"CALLING API FUNCTIONS">
below.

To signal success, this method has to return zero. Anything else will be
considered an error condition and cause an appropriate message to be logged.
Currently, returning non-zero does not have any other effects. In particular,
Java "read"-methods are not suspended for increasing intervals like C
"read"-functions.

=head2 write callback

Interface: B<org.collectd.api.CollectdWriteInterface>

Signature: I<int> B<write> (I<ValueList> vl)

This method is called whenever a value is dispatched to the daemon. The
corresponding C "write"-functions are passed a C<data_set_t>, so they can
decide which values are absolute values (gauge) and which are counter values.
To get the corresponding C<ListE<lt>DataSourceE<gt>>, call the B<getDataSource>
method of the B<ValueList> object.

To signal success, this method has to return zero. Anything else will be
considered an error condition and cause an appropriate message to be logged.

=head2 flush callback

Interface: B<org.collectd.api.CollectdFlushInterface>

Signature: I<int> B<flush> (I<int> timeout, I<String> identifier)

This method is called when the daemon received a flush command. This can either
be done using the C<USR1> signal (see L<collectd(1)>) or using the I<unixsock>
plugin (see L<collectd-unixsock(1)>).

If I<timeout> is greater than zero, only values older than this number of
seconds should be flushed. To signal that all values should be flushed
regardless of age, this argument is set to a negative number.

The I<identifier> specifies which value should be flushed. If it is not
possible to flush one specific value, flush all values. To signal that all
values should be flushed, this argument is set to I<null>.

To signal success, this method has to return zero. Anything else will be
considered an error condition and cause an appropriate message to be logged.

=head2 shutdown callback

Interface: B<org.collectd.api.CollectdShutdownInterface>

Signature: I<int> B<shutdown> ()

This method is called when the daemon is shutting down. You should not rely on
the destructor to clean up behind the object but use this function instead.

To signal success, this method has to return zero. Anything else will be
considered an error condition and cause an appropriate message to be logged.

=head2 log callback

Interface: B<org.collectd.api.CollectdLogInterface>

Signature: I<void> B<log> (I<int> severity, I<String> message)

This callback can be used to receive log messages from the daemon.

The argument I<severity> is one of:

=over 4

=item *

org.collectd.api.Collectd.LOG_ERR

=item *

org.collectd.api.Collectd.LOG_WARNING

=item *

org.collectd.api.Collectd.LOG_NOTICE

=item *

org.collectd.api.Collectd.LOG_INFO

=item *

org.collectd.api.Collectd.LOG_DEBUG

=back

The function does not return any value.

=head2 Example

This short example demonstrates how to register a read callback with the
daemon:

  import org.collectd.api.Collectd;
  import org.collectd.api.ValueList;
  
  import org.collectd.api.CollectdReadInterface;
  
  public class Foobar implements CollectdReadInterface
  {
    public Foobar ()
    {
      Collectd.registerRead ("Foobar", this);
    }
    
    public int read ()
    {
      ValueList vl;
      
      /* Do something... */
      
      Collectd.dispatchValues (vl);
    }
  }

=head1 CALLING API FUNCTIONS

All collectd API functions that are available to Java plugins are implemented
as I<publicE<nbsp>static> functions of the B<org.collectd.api.Collectd> class.
This makes calling these functions pretty straight forward.

The following are the currently exported functions. For information on the
interfaces used, please see L<"REGISTERING CALLBACKS"> above.

=head2 registerConfig

Signature: I<int> B<registerConfig> (I<String> name,
I<CollectdConfigInterface> object);

Registers the B<config> function of I<object> with the daemon.

Returns zero upon success and non-zero when an error occurred.

=head2 registerInit

Signature: I<int> B<registerInit> (I<String> name,
I<CollectdInitInterface> object);

Registers the B<init> function of I<object> with the daemon.

Returns zero upon success and non-zero when an error occurred.

=head2 registerRead

Signature: I<int> B<registerRead> (I<String> name,
I<CollectdReadInterface> object)

Registers the B<read> function of I<object> with the daemon.

Returns zero upon success and non-zero when an error occurred.

=head2 registerWrite

Signature: I<int> B<registerWrite> (I<String> name,
I<CollectdWriteInterface> object)

Registers the B<write> function of I<object> with the daemon.

Returns zero upon success and non-zero when an error occurred.

=head2 registerFlush

Signature: I<int> B<registerFlush> (I<String> name,
I<CollectdFlushInterface> object)

Registers the B<flush> function of I<object> with the daemon.

Returns zero upon success and non-zero when an error occurred.

=head2 registerShutdown

Signature: I<int> B<registerShutdown> (I<String> name,
I<CollectdShutdownInterface> object);

Registers the B<shutdown> function of I<object> with the daemon.

Returns zero upon success and non-zero when an error occurred.

=head2 registerLog

Signature: I<int> B<registerLog> (I<String> name,
I<CollectdLogInterface> object);

Registers the B<log> function of I<object> with the daemon.

Returns zero upon success and non-zero when an error occurred.

=head2 dispatchValues

Signature: I<int> B<dispatchValues> (I<ValueList>)

Passes the values represented by the B<ValueList> object to the
C<plugin_dispatch_values> function of the daemon. The "data set" (or list of
"data sources") associated with the object are ignored, because
C<plugin_dispatch_values> will automatically lookup the required data set. It
is therefore absolutely okay to leave this blank.

Returns zero upon success or non-zero upon failure.

=head2 getDS

Signature: I<DataSet> B<getDS> (I<String>)

Returns the approrpate I<type> or B<null> if the type is not defined.

=head2 logError

Signature: I<void> B<logError> (I<String>)

Sends a log message with severity B<ERROR> to the daemon.

=head2 logWarning

Signature: I<void> B<logWarning> (I<String>)

Sends a log message with severity B<WARNING> to the daemon.

=head2 logNotice

Signature: I<void> B<logNotice> (I<String>)

Sends a log message with severity B<NOTICE> to the daemon.

=head2 logInfo

Signature: I<void> B<logInfo> (I<String>)

Sends a log message with severity B<INFO> to the daemon.

=head2 logDebug

Signature: I<void> B<logDebug> (I<String>)

Sends a log message with severity B<DEBUG> to the daemon.

=head1 SEE ALSO

L<collectd(1)>,
L<collectd.conf(5)>,
L<collectd-perl(5)>,
L<types.db(5)>

=head1 AUTHOR

Florian Forster E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt>