From: Florian Forster <octo@leeloo.lan.home.verplant.org>
Date: Tue, 24 Feb 2009 10:24:38 +0000 (+0100)
Subject: collectd.conf(5), collectd-java(5): Updated the documentation for the Java plugin.
X-Git-Tag: collectd-4.7.0~127^2
X-Git-Url: https://git.verplant.org/?a=commitdiff_plain;h=4231dfb2186e7aae17a3d0bc25d915da0b5f9c9c;p=collectd.git

collectd.conf(5), collectd-java(5): Updated the documentation for the Java plugin.
---

diff --git a/src/collectd-java.pod b/src/collectd-java.pod
index 2c621353..f441c82a 100644
--- a/src/collectd-java.pod
+++ b/src/collectd-java.pod
@@ -37,10 +37,20 @@ 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 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>.
@@ -71,16 +81,181 @@ 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 EXPORTED API FUNCTIONS
+
+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:
+
+  Collectd.logError ("That wasn't chicken!");
+
+The following are the currently exported functions.
+
+=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.
+
+See L<"config callback"> below.
+
+=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.
+
+See L<"init callback"> below.
+
+=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.
+
+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);
+
+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<"CALLING API FUNCTIONS"> below. To register a callback, the object being
+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.
 
@@ -107,6 +282,8 @@ 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<org.collectd.api.CollectdInitInterface>
@@ -120,6 +297,8 @@ 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<org.collectd.api.CollectdReadInterface>
@@ -128,8 +307,7 @@ 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.
@@ -137,6 +315,8 @@ 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<org.collectd.api.CollectdWriteInterface>
@@ -152,6 +332,8 @@ 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.
 
+See L<"registerWrite"> above.
+
 =head2 flush callback
 
 Interface: B<org.collectd.api.CollectdFlushInterface>
@@ -173,6 +355,8 @@ 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>
@@ -185,6 +369,8 @@ 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<org.collectd.api.CollectdLogInterface>
@@ -221,6 +407,8 @@ org.collectd.api.Collectd.LOG_DEBUG
 
 The function does not return any value.
 
+See L<"registerLog"> above.
+
 =head2 notification callback
 
 Interface: B<org.collectd.api.CollectdNotificationInterface>
@@ -232,6 +420,8 @@ 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
@@ -240,6 +430,8 @@ 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>
@@ -282,6 +474,8 @@ 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>
@@ -321,7 +515,7 @@ B<Collectd.FC_TARGET_RETURN>
 
 =back
 
-=head2 Example
+=head1 EXAMPLE
 
 This short example demonstrates how to register a read callback with the
 daemon:
@@ -348,157 +542,6 @@ daemon:
     }
   }
 
-=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 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.
-
-=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"> above.
-
-=head2 registerTarget
-
-Signature: I<int> B<registerTarget> (I<String> name,
-I<CollectdTargetFactoryInterface> object);
-
-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"> above.
-
-=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 SEE ALSO
 
 L<collectd(1)>,
diff --git a/src/collectd.conf.pod b/src/collectd.conf.pod
index e8946287..1ab43607 100644
--- a/src/collectd.conf.pod
+++ b/src/collectd.conf.pod
@@ -1101,7 +1101,7 @@ Synopsis:
    </Plugin>
  </Plugin>
 
-Available config options:
+Available configuration options:
 
 =over 4
 
@@ -1111,6 +1111,10 @@ Argument that is to be passed to the I<Java Virtual Machine> (JVM). This works
 exactly the way the arguments to the I<java> binary on the command line work.
 Execute C<javaE<nbsp>--help> for details.
 
+Please note that B<all> these options must appear B<before> (i.E<nbsp>e. above)
+any other options! When another option is found, the JVM will be started and
+later options will have to be ignored!
+
 =item B<LoadPlugin> I<JavaClass>
 
 Instantiates a new I<JavaClass> object. The constructor of this object very
@@ -1118,10 +1122,20 @@ likely then registers one or more callback methods with the server.
 
 See L<collectd-java(5)> for details.
 
-=item B<Plugin> I<JavaClass>
+When the first such option is found, the virtual machine (JVM) is created. This
+means that all B<JVMArg> options must appear before (i.E<nbsp>e. above) all
+B<LoadPlugin> options!
+
+=item B<Plugin> I<Name>
+
+The entire block is passed to the Java plugin as an
+I<org.collectd.api.OConfigItem> object.
 
-The entrie block is passed to the Java plugin as an
-I<org.collectd.api.OConfigItem> object. See L<collectd-java(5)/"config callback">.
+For this to work, the plugin has to register a configuration callback first,
+see L<collectd-java(5)/"config callback">. This means, that the B<Plugin> block
+must appear after the appropriate B<LoadPlugin> block. Also note, that I<Name>
+depends on the (Java) plugin registering the callback and is completely
+independent from the I<JavaClass> argument passed to B<LoadPlugin>.
 
 =back