From 19e04e052462e8803966f288799358ea697f4d59 Mon Sep 17 00:00:00 2001 From: Florian Forster Date: Wed, 18 Feb 2009 23:35:59 +0100 Subject: [PATCH] collectd-java(5): Add a manual page for the java plugin. --- src/Makefile.am | 29 +++++-- src/collectd-java.pod | 225 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 247 insertions(+), 7 deletions(-) create mode 100644 src/collectd-java.pod diff --git a/src/Makefile.am b/src/Makefile.am index 15dbddcf..e159026c 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -916,19 +916,34 @@ collectd_DEPENDENCIES += xmms.la endif -dist_man_MANS = collectd.1 collectd-nagios.1 collectd.conf.5 \ - collectd-email.5 collectd-exec.5 collectd-perl.5 \ - collectd-snmp.5 collectd-unixsock.5 collectdmon.1 \ +dist_man_MANS = collectd.1 \ + collectd.conf.5 \ + collectd-email.5 \ + collectd-exec.5 \ + collectd-java.5 + collectdmon.1 \ + collectd-nagios.1 \ + collectd-perl.5 \ + collectd-snmp.5 \ + collectd-unixsock.5 \ types.db.5 #collectd_1_SOURCES = collectd.pod EXTRA_DIST = types.db -EXTRA_DIST += collectd-email.pod collectd-exec.pod collectd-nagios.pod \ - collectd-perl.pod collectd-snmp.pod collectd-unixsock.pod \ - collectd.conf.pod collectd.pod collectdmon.pod types.db.pod \ - postgresql_default.conf +EXTRA_DIST += collectd.conf.pod \ + collectd-email.pod \ + collectd-exec.pod \ + collectd-java.pod \ + collectdmon.pod \ + collectd-nagios.pod \ + collectd-perl.pod \ + collectd.pod \ + collectd-snmp.pod \ + collectd-unixsock.pod \ + postgresql_default.conf \ + types.db.pod .pod.1: pod2man --release=$(VERSION) --center=$(PACKAGE) $< \ diff --git a/src/collectd-java.pod b/src/collectd-java.pod new file mode 100644 index 00000000..83fb89bd --- /dev/null +++ b/src/collectd-java.pod @@ -0,0 +1,225 @@ +=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 and I namespaces. + +The available classes are: + +=over 4 + +=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 Borg.collectd.protocol.DataSourceE> + +Corresponds to C, defined in F. + +=item B + +Corresponds to C, defined in F. + +=back + +The API functions that are available from Java are implemented as I +functions of the B class. +See L<"CALLING API FUNCTIONS"> below for details. + +=head1 CREATING CALLBACKS + +Callback functions, i.Ee. 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">. + +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. + +Currently used callback methods are: + +=over 4 + +=item Constructor () + +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.Ee. an empty argument list, though. + +=item I B (I) + +Configuration for the plugin. This is the first method that is called after the +object has been created. + +=item I B () + +Initialization of the plugin. This item is called after B has been +called. + +=item I B () + +Called when the plugin should acquire new values. + +=item I B (I) + +Called to have the plugin store values. + +=item I B () + +Called when the daemon is shutting down. + +=back + +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 +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 + +Signature: I B (I) + +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. + +=head2 Init callback + +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. + +=head2 Read callback + +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 B, 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 + +Signature: I B (I) + +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. + +=head2 Shutdown callback + +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. + +=head1 CALLING 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. + +The currently exported functions are: + +=over 4 + +=item I B (I) + +Corresponds to C, defined in F. + +=back + +Each API function is now explained in more detail: + +=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. + +=head1 SEE ALSO + +L, +L, +L, +L + +=head1 AUTHOR + +Florian Forster EoctoEatEverplant.orgE + -- 2.11.0