X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=src%2Fcollectd-java.pod;fp=src%2Fcollectd-java.pod;h=aade08a456b701aff4fdc94f70f1907617de1127;hb=1cf67d3e29da8ce7bdb29bc2fb8b1f0c1ca96e39;hp=0000000000000000000000000000000000000000;hpb=9caf56be59e558bc2fc4eaee3178580910fed869;p=pkg-collectd.git
diff --git a/src/collectd-java.pod b/src/collectd-java.pod
new file mode 100644
index 0000000..aade08a
--- /dev/null
+++ b/src/collectd-java.pod
@@ -0,0 +1,697 @@
+=encoding UTF-8
+
+=head1 NAME
+
+collectd-java - Documentation of collectd's "java plugin"
+
+=head1 SYNOPSIS
+
+ LoadPlugin "java"
+
+ JVMArg "-verbose:jni"
+ JVMArg "-Djava.class.path=/opt/collectd/lib/collectd/bindings/java"
+
+ LoadPlugin "org.collectd.java.Foobar"
+
+ # To be parsed by the plugin
+
+
+
+=head1 DESCRIPTION
+
+The I plugin embeds a I (JVM) into I 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
+plugin by Sebastian Harl, see L 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>.
+
+=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 namespace.
+
+The I plugin will create one object of each class configured with the
+B option. The constructor of this class can then register "callback
+methods", i.Ee. methods that will be called by the daemon when
+appropriate.
+
+The available classes are:
+
+=over 4
+
+=item B
+
+All API functions exported to Java are implemented as static functions of this
+class. See L<"EXPORTED API FUNCTIONS"> below.
+
+=item B
+
+Corresponds to C, defined in F.
+
+=item B
+
+Corresponds to C, defined in F.
+
+=item B
+
+Corresponds to C, defined in F.
+
+=item B
+
+Corresponds to C, defined in F.
+
+=item B
+
+Corresponds to C, defined in F.
+
+=item B
+
+Corresponds to C, defined in F.
+
+=back
+
+In the remainder of this document, we'll use the short form of these names, for
+example B. In order to be able to use these abbreviated names, you
+need to B the classes.
+
+=head1 EXPORTED API FUNCTIONS
+
+All collectd API functions that are available to Java plugins are implemented
+as Istatic> functions of the B 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:
+
+ Collectd.logError ("That wasn't chicken!");
+
+The following are the currently exported functions.
+
+=head2 registerConfig
+
+Signature: I B (I name,
+I object);
+
+Registers the B function of I with the daemon.
+
+Returns zero upon success and non-zero when an error occurred.
+
+See L<"config callback"> below.
+
+=head2 registerInit
+
+Signature: I B (I name,
+I object);
+
+Registers the B function of I with the daemon.
+
+Returns zero upon success and non-zero when an error occurred.
+
+See L<"init callback"> below.
+
+=head2 registerRead
+
+Signature: I B (I name,
+I object)
+
+Registers the B function of I with the daemon.
+
+Returns zero upon success and non-zero when an error occurred.
+
+See L<"read callback"> below.
+
+=head2 registerWrite
+
+Signature: I B (I name,
+I object)
+
+Registers the B function of I with the daemon.
+
+Returns zero upon success and non-zero when an error occurred.
+
+See L<"write callback"> below.
+
+=head2 registerFlush
+
+Signature: I B (I name,
+I object)
+
+Registers the B function of I with the daemon.
+
+Returns zero upon success and non-zero when an error occurred.
+
+See L<"flush callback"> below.
+
+=head2 registerShutdown
+
+Signature: I B (I name,
+I object);
+
+Registers the B function of I with the daemon.
+
+Returns zero upon success and non-zero when an error occurred.
+
+See L<"shutdown callback"> below.
+
+=head2 registerLog
+
+Signature: I B (I name,
+I object);
+
+Registers the B function of I with the daemon.
+
+Returns zero upon success and non-zero when an error occurred.
+
+See L<"log callback"> below.
+
+=head2 registerNotification
+
+Signature: I B (I name,
+I object);
+
+Registers the B function of I with the daemon.
+
+Returns zero upon success and non-zero when an error occurred.
+
+See L<"notification callback"> below.
+
+=head2 registerMatch
+
+Signature: I B (I name,
+I object);
+
+Registers the B function of I with the daemon.
+
+Returns zero upon success and non-zero when an error occurred.
+
+See L<"match callback"> below.
+
+=head2 registerTarget
+
+Signature: I B (I name,
+I object);
+
+Registers the B function of I with the daemon.
+
+Returns zero upon success and non-zero when an error occurred.
+
+See L<"target callback"> below.
+
+=head2 dispatchValues
+
+Signature: I B (I)
+
+Passes the values represented by the B object to the
+C function of the daemon. The "data set" (or list of
+"data sources") associated with the object are ignored, because
+C 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 B (I)
+
+Returns the appropriate I or B if the type is not defined.
+
+=head2 logError
+
+Signature: I B (I)
+
+Sends a log message with severity B to the daemon.
+
+=head2 logWarning
+
+Signature: I B (I)
+
+Sends a log message with severity B to the daemon.
+
+=head2 logNotice
+
+Signature: I B (I)
+
+Sends a log message with severity B to the daemon.
+
+=head2 logInfo
+
+Signature: I B (I)
+
+Sends a log message with severity B to the daemon.
+
+=head2 logDebug
+
+Signature: I B (I)
+
+Sends a log message with severity B 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,
+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 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
+
+Signature: I B (I ci)
+
+This method is passed a B object, if both, method and
+configuration, are available. B is the root of a tree representing
+the configuration for this plugin. The root itself is the representation of the
+BPluginE/E> 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.
+
+See L<"registerConfig"> above.
+
+=head2 init callback
+
+Interface: B
+
+Signature: I B ()
+
+This method is called after the configuration has been handled. It is
+supposed to set up the plugin. e.Eg. 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.
+
+See L<"registerInit"> above.
+
+=head2 read callback
+
+Interface: B
+
+Signature: I B ()
+
+This method is called periodically and is supposed to gather statistics in
+whatever fashion. These statistics are represented as a B object and
+sent to the daemon using L.
+
+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.
+
+See L<"registerRead"> above.
+
+=head2 write callback
+
+Interface: B
+
+Signature: I B (I vl)
+
+This method is called whenever a value is dispatched to the daemon. The
+corresponding C "write"-functions are passed a C, so they can
+decide which values are absolute values (gauge) and which are counter values.
+To get the corresponding CDataSourceE>, call the B
+method of the B 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.
+
+See L<"registerWrite"> above.
+
+=head2 flush callback
+
+Interface: B
+
+Signature: I B (I timeout, I identifier)
+
+This method is called when the daemon received a flush command. This can either
+be done using the C signal (see L) or using the I
+plugin (see L).
+
+If I 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 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.
+
+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
+
+Signature: I B ()
+
+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.
+
+See L<"registerShutdown"> above.
+
+=head2 log callback
+
+Interface: B
+
+Signature: I B (I severity, I message)
+
+This callback can be used to receive log messages from the daemon.
+
+The argument I 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.
+
+See L<"registerLog"> above.
+
+=head2 notification callback
+
+Interface: B
+
+Signature: I B (I 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
+
+Signature: I B
+(I ci);
+
+Called by the daemon to create "match" objects.
+
+Returns: A new object which implements the B interface.
+
+=head3 Match object
+
+Interface: B
+
+Signature: I B (I ds, I vl);
+
+Called when processing a chain to determine whether or not a I
+matches. How values are matches is up to the implementing class.
+
+Has to return one of:
+
+=over 4
+
+=item *
+
+B
+
+=item *
+
+B
+
+=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
+
+Signature: I B
+(I ci);
+
+Called by the daemon to create "target" objects.
+
+Returns: A new object which implements the B
+interface.
+
+=head3 Target object
+
+Interface: B
+
+Signature: I B (I ds, I 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
+
+=item *
+
+B
+
+=item *
+
+B
+
+=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 PLUGINS
+
+The following plugins are implemented in I. Both, the B
+option and the B block must be inside the
+BPluginEjavaE> block (see above).
+
+=head2 GenericJMX plugin
+
+The GenericJMX plugin reads I (MBeans) from an I
+using JMX. JMX is a generic framework to provide and query various management
+information. The interface is used by Java processes to provide internal
+statistics as well as by the I (JVM) to provide
+information about the memory used, threads and so on.
+
+The configuration of the I consists of two blocks: I
+blocks that define a mapping of MBean attributes to the âtypesâ used by
+I, and I blocks which define the parameters needed to
+connect to an I and what data to collect. The configuration of the
+I is similar in nature, in case you know it.
+
+=head3 MBean blocks
+
+I blocks specify what data is retrieved from I and how that data
+is mapped on the I data types. The block requires one string
+argument, a name. This name is used in the I blocks (see below) to
+refer to a specific I block. Therefore, the names must be unique.
+
+The following options are recognized within I blocks:
+
+=over 4
+
+=item B I
+
+Sets the pattern which is used to retrieve I from the I.
+If more than one MBean is returned you should use the B option
+(see below) to make the identifiers unique.
+
+See also:
+L
+
+=item B I
+
+Prefixes the generated I with I. I<(optional)>
+
+=item B I
+
+The I used by JMX to identify I include so called
+I<âpropertiesâ> which are basically key-value-pairs. If the given object name
+is not unique and multiple MBeans are returned, the values of those properties
+usually differ. You can use this option to build the I from
+the appropriate property values. This option is optional and may be repeated to
+generate the I from multiple property values.
+
+=item Bvalue /E> blocks
+
+The I blocks map one or more attributes of an I to a value list
+in I. There must be at least one Value block within each I
+block.
+
+=over 4
+
+=item B type
+
+Sets the data set used within I to handle the values of the I
+attribute.
+
+=item B I
+
+Works like the option of the same name directly beneath the I block, but
+sets the type instance instead. I<(optional)>
+
+=item B I