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> and I<org.collectd.protocol> namespaces.
+I<org.collectd.api> namespace.
+
+The I<Java> plugin will create one object of each class configured with the
+B<LoadPlugin> option. The constructor of this class can then register "callback
+methods", i.E<nbsp>e. methods that will be called by the daemon when
+appropriate.
The available classes are:
=over 4
+=item B<org.collectd.api.Collectd>
+
+All API functions exported to Java are implemented as static functions of this
+class. See L<"EXPORTED API FUNCTIONS"> below.
+
=item B<org.collectd.api.OConfigValue>
Corresponds to C<oconfig_value_t>, defined in F<src/liboconfig/oconfig.h>.
Corresponds to C<oconfig_item_t>, defined in F<src/liboconfig/oconfig.h>.
-=item B<org.collectd.protocol.DataSource>
+=item B<org.collectd.api.DataSource>
Corresponds to C<data_source_t>, defined in F<src/plugin.h>.
-=item B<java.util.ListE<lt>org.collectd.protocol.DataSourceE<gt>>
+=item B<org.collectd.api.DataSet>
Corresponds to C<data_set_t>, defined in F<src/plugin.h>.
-=item B<org.collectd.protocol.ValueList>
+=item B<org.collectd.api.ValueList>
Corresponds to C<value_list_t>, defined in F<src/plugin.h>.
+=item B<org.collectd.api.Notification>
+
+Corresponds to C<notification_t>, defined in F<src/plugin.h>.
+
=back
-The API functions that are available from Java are implemented as I<static>
-functions of the B<org.collectd.api.CollectdAPI> class.
-See L<"CALLING API FUNCTIONS"> below for details.
+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.
-=head1 CREATING CALLBACKS
+=head1 EXPORTED API FUNCTIONS
-Callback functions, i.E<nbsp>e. functions that are called by collectd, differ
-from their C equivalents in that they don't need to be "registered". Instead,
-they have a fixed name, argument list and return value, usually called
-I<"signature">.
+All collectd API functions that are available to Java plugins are implemented
+as I<publicE<nbsp>static> functions of the B<Collectd> class. This makes
+calling these functions pretty straight forward. For example, to send an error
+message to the daemon, you'd do something like this:
-When starting up, the plugin will instantiate one object of your class, using
-the constructor without arguments. All other functions called by the Java
-plugin are methods of this object.
+ Collectd.logError ("That wasn't chicken!");
-Currently used callback methods are:
+The following are the currently exported functions.
-=over 4
+=head2 registerConfig
-=item Constructor ()
+Signature: I<int> B<registerConfig> (I<String> name,
+I<CollectdConfigInterface> object);
-Used to create an object of the custom class. The name of the constructor
-depends on your classes' name, of course. It must have the signature shown
-above, i.E<nbsp>e. an empty argument list, though.
+Registers the B<config> function of I<object> with the daemon.
-=item I<int> B<Config> (I<org.collectd.api.OConfigItem>)
+Returns zero upon success and non-zero when an error occurred.
-Configuration for the plugin. This is the first method that is called after the
-object has been created.
+See L<"config callback"> below.
-=item I<int> B<Init> ()
+=head2 registerInit
-Initialization of the plugin. This item is called after B<Config> has been
-called.
+Signature: I<int> B<registerInit> (I<String> name,
+I<CollectdInitInterface> object);
-=item I<int> B<Read> ()
+Registers the B<init> function of I<object> with the daemon.
-Called when the plugin should acquire new values.
+Returns zero upon success and non-zero when an error occurred.
-=item I<int> B<Write> (I<org.collectd.protocol.ValueList>)
+See L<"init callback"> below.
-Called to have the plugin store values.
+=head2 registerRead
-=item I<int> B<Shutdown> ()
+Signature: I<int> B<registerRead> (I<String> name,
+I<CollectdReadInterface> object)
-Called when the daemon is shutting down.
+Registers the B<read> function of I<object> with the daemon.
-=back
+Returns zero upon success and non-zero when an error occurred.
+
+See L<"read callback"> below.
+
+=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.
+
+See L<"write callback"> below.
+
+=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.
+
+See L<"flush callback"> below.
+
+=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.
+
+See L<"shutdown callback"> below.
+
+=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.
+
+See L<"log callback"> below.
+
+=head2 registerNotification
+
+Signature: I<int> B<registerNotification> (I<String> name,
+I<CollectdNotificationInterface> object);
+
+Registers the B<notification> function of I<object> with the daemon.
+
+Returns zero upon success and non-zero when an error occurred.
+
+See L<"notification callback"> below.
+
+=head2 registerMatch
+
+Signature: I<int> B<registerMatch> (I<String> name,
+I<CollectdMatchFactoryInterface> object);
+
+Registers the B<createMatch> function of I<object> with the daemon.
+
+Returns zero upon success and non-zero when an error occurred.
+
+See L<"match callback"> below.
+
+=head2 registerTarget
+
+Signature: I<int> B<registerTarget> (I<String> name,
+I<CollectdTargetFactoryInterface> object);
-A plugin may implement any number of these callbacks, from all to none. An
-object without callback methods is never called by collectd, but may still
+Registers the B<createTarget> function of I<object> with the daemon.
+
+Returns zero upon success and non-zero when an error occurred.
+
+See L<"target callback"> below.
+
+=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 appropriate 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 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<"EXPORTED API FUNCTIONS"> above. 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
+=head2 config callback
-Signature: I<int> B<Config> (I<org.collectd.api.OConfigItem>)
+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
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
+See L<"registerConfig"> above.
+
+=head2 init callback
-Signature: I<int> B<Init> ()
+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
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
+See L<"registerInit"> above.
+
+=head2 read callback
+
+Interface: B<org.collectd.api.CollectdReadInterface>
-Signature: I<int> B<Read> ()
+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.
+sent to the daemon using L<dispatchValues|"dispatchValues">.
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.
Java "read"-methods are not suspended for increasing intervals like C
"read"-functions.
-=head2 Write callback
+See L<"registerRead"> above.
+
+=head2 write callback
+
+Interface: B<org.collectd.api.CollectdWriteInterface>
-Signature: I<int> B<Write> (I<org.collectd.protocol.ValueList>)
+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
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
+See L<"registerWrite"> above.
-Signature: I<int> B<Shutdown> ()
+=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(5)>).
+
+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.
+
+See L<"registerFlush"> above.
+
+=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.
-=head1 CALLING API FUNCTIONS
+See L<"registerShutdown"> above.
-All collectd API functions that are available to Java plugins are implemented
-as I<publicE<nbsp>static> functions of the B<org.collectd.api.CollectdAPI>
-class. This makes calling these functions pretty straight forward.
+=head2 log callback
+
+Interface: B<org.collectd.api.CollectdLogInterface>
+
+Signature: I<void> B<log> (I<int> severity, I<String> message)
-The currently exported functions are:
+This callback can be used to receive log messages from the daemon.
+
+The argument I<severity> is one of:
=over 4
-=item I<int> B<DispatchValues> (I<org.collectd.protocol.ValueList>)
+=item *
+
+org.collectd.api.Collectd.LOG_ERR
+
+=item *
+
+org.collectd.api.Collectd.LOG_WARNING
+
+=item *
-Corresponds to C<plugin_dispatch_values>, defined in F<src/plugin.h>.
+org.collectd.api.Collectd.LOG_NOTICE
+
+=item *
+
+org.collectd.api.Collectd.LOG_INFO
+
+=item *
+
+org.collectd.api.Collectd.LOG_DEBUG
=back
-Each API function is now explained in more detail:
+The function does not return any value.
-=head2 DispatchValues
+See L<"registerLog"> above.
-Signature: I<int> B<DispatchValues> (I<org.collectd.protocol.ValueList>)
+=head2 notification callback
-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.
+Interface: B<org.collectd.api.CollectdNotificationInterface>
-Returns zero upon success or non-zero upon failure.
+Signature: I<int> B<notification> (I<Notification> n)
+
+This callback can be used to receive notifications from the daemon.
+
+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.
+
+See L<"registerNotification"> above.
+
+=head2 match callback
+
+The match (and target, see L<"target callback"> below) callbacks work a bit
+different from the other callbacks above: You don't register a match callback
+with the daemon directly, but you register a function which, when called,
+creates an appropriate object. The object creating the "match" objects is
+called "match factory".
+
+See L<"registerMatch"> above.
+
+=head3 Factory object
+
+Interface: B<org.collectd.api.CollectdMatchFactoryInterface>
+
+Signature: I<CollectdMatchInterface> B<createMatch>
+(I<OConfigItem> ci);
+
+Called by the daemon to create "match" objects.
+
+Returns: A new object which implements the B<CollectdMatchInterface> interface.
+
+=head3 Match object
+
+Interface: B<org.collectd.api.CollectdMatchInterface>
+
+Signature: I<int> B<match> (I<DataSet> ds, I<ValueList> vl);
+
+Called when processing a chain to determine whether or not a I<ValueList>
+matches. How values are matches is up to the implementing class.
+
+Has to return one of:
+
+=over 4
+
+=item *
+
+B<Collectd.FC_MATCH_NO_MATCH>
+
+=item *
+
+B<Collectd.FC_MATCH_MATCHES>
+
+=back
+
+=head2 target callback
+
+The target (and match, see L<"match callback"> above) callbacks work a bit
+different from the other callbacks above: You don't register a target callback
+with the daemon directly, but you register a function which, when called,
+creates an appropriate object. The object creating the "target" objects is
+called "target factory".
+
+See L<"registerTarget"> above.
+
+=head3 Factory object
+
+Interface: B<org.collectd.api.CollectdTargetFactoryInterface>
+
+Signature: I<CollectdTargetInterface> B<createTarget>
+(I<OConfigItem> ci);
+
+Called by the daemon to create "target" objects.
+
+Returns: A new object which implements the B<CollectdTargetInterface>
+interface.
+
+=head3 Target object
+
+Interface: B<org.collectd.api.CollectdTargetInterface>
+
+Signature: I<int> B<invoke> (I<DataSet> ds, I<ValueList> vl);
+
+Called when processing a chain to perform some action. The action performed is
+up to the implementing class.
+
+Has to return one of:
+
+=over 4
+
+=item *
+
+B<Collectd.FC_TARGET_CONTINUE>
+
+=item *
+
+B<Collectd.FC_TARGET_STOP>
+
+=item *
+
+B<Collectd.FC_TARGET_RETURN>
+
+=back
+
+=head1 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 SEE ALSO
projects / collectd.git / blobdiff