Revert "Revert "Merge tag 'upstream/5.5.0'""

[pkg-collectd.git] / src / collectd-java.5

.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "COLLECTD-JAVA 5"
.TH COLLECTD-JAVA 5 "2015-03-10" "5.4.1.805.g42e4d6c" "collectd"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
collectd\-java \- Documentation of collectd's "java plugin"
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\& 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>
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fIJava\fR plugin embeds a \fIJava Virtual Machine\fR (\s-1JVM\s0) into \fIcollectd\fR and
provides a Java interface to part of collectd's \s-1API.\s0 This makes it possible to
write additions to the daemon in Java.
.PP
This plugin is similar in nature to, but shares no code with, the \fIPerl\fR
plugin by Sebastian Harl, see \fIcollectd\-perl\fR\|(5) for details.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
A short outline of this plugin's configuration can be seen in \*(L"\s-1SYNOPSIS\*(R"\s0
above. For a complete list of all configuration options and their semantics
please read "Plugin \f(CW\*(C`java\*(C'\fR" in \fIcollectd.conf\fR\|(5).
.SH "OVERVIEW"
.IX Header "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
\&\fIorg.collectd.api\fR namespace.
.PP
The \fIJava\fR plugin will create one object of each class configured with the
\&\fBLoadPlugin\fR option. The constructor of this class can then register \*(L"callback
methods\*(R", i.\ e. methods that will be called by the daemon when
appropriate.
.PP
The available classes are:
.IP "\fBorg.collectd.api.Collectd\fR" 4
.IX Item "org.collectd.api.Collectd"
All \s-1API\s0 functions exported to Java are implemented as static functions of this
class. See \*(L"\s-1EXPORTED API FUNCTIONS\*(R"\s0 below.
.IP "\fBorg.collectd.api.OConfigValue\fR" 4
.IX Item "org.collectd.api.OConfigValue"
Corresponds to \f(CW\*(C`oconfig_value_t\*(C'\fR, defined in \fIsrc/liboconfig/oconfig.h\fR.
.IP "\fBorg.collectd.api.OConfigItem\fR" 4
.IX Item "org.collectd.api.OConfigItem"
Corresponds to \f(CW\*(C`oconfig_item_t\*(C'\fR, defined in \fIsrc/liboconfig/oconfig.h\fR.
.IP "\fBorg.collectd.api.DataSource\fR" 4
.IX Item "org.collectd.api.DataSource"
Corresponds to \f(CW\*(C`data_source_t\*(C'\fR, defined in \fIsrc/plugin.h\fR.
.IP "\fBorg.collectd.api.DataSet\fR" 4
.IX Item "org.collectd.api.DataSet"
Corresponds to \f(CW\*(C`data_set_t\*(C'\fR, defined in \fIsrc/plugin.h\fR.
.IP "\fBorg.collectd.api.ValueList\fR" 4
.IX Item "org.collectd.api.ValueList"
Corresponds to \f(CW\*(C`value_list_t\*(C'\fR, defined in \fIsrc/plugin.h\fR.
.IP "\fBorg.collectd.api.Notification\fR" 4
.IX Item "org.collectd.api.Notification"
Corresponds to \f(CW\*(C`notification_t\*(C'\fR, defined in \fIsrc/plugin.h\fR.
.PP
In the remainder of this document, we'll use the short form of these names, for
example \fBValueList\fR. In order to be able to use these abbreviated names, you
need to \fBimport\fR the classes.
.SH "EXPORTED API FUNCTIONS"
.IX Header "EXPORTED API FUNCTIONS"
All collectd \s-1API\s0 functions that are available to Java plugins are implemented
as \fIpublic\ static\fR functions of the \fBCollectd\fR 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:
.PP
.Vb 1
\&  Collectd.logError ("That wasn\*(Aqt chicken!");
.Ve
.PP
The following are the currently exported functions.
.SS "registerConfig"
.IX Subsection "registerConfig"
Signature: \fIint\fR \fBregisterConfig\fR (\fIString\fR name,
\&\fICollectdConfigInterface\fR object);
.PP
Registers the \fBconfig\fR function of \fIobject\fR with the daemon.
.PP
Returns zero upon success and non-zero when an error occurred.
.PP
See \*(L"config callback\*(R" below.
.SS "registerInit"
.IX Subsection "registerInit"
Signature: \fIint\fR \fBregisterInit\fR (\fIString\fR name,
\&\fICollectdInitInterface\fR object);
.PP
Registers the \fBinit\fR function of \fIobject\fR with the daemon.
.PP
Returns zero upon success and non-zero when an error occurred.
.PP
See \*(L"init callback\*(R" below.
.SS "registerRead"
.IX Subsection "registerRead"
Signature: \fIint\fR \fBregisterRead\fR (\fIString\fR name,
\&\fICollectdReadInterface\fR object)
.PP
Registers the \fBread\fR function of \fIobject\fR with the daemon.
.PP
Returns zero upon success and non-zero when an error occurred.
.PP
See \*(L"read callback\*(R" below.
.SS "registerWrite"
.IX Subsection "registerWrite"
Signature: \fIint\fR \fBregisterWrite\fR (\fIString\fR name,
\&\fICollectdWriteInterface\fR object)
.PP
Registers the \fBwrite\fR function of \fIobject\fR with the daemon.
.PP
Returns zero upon success and non-zero when an error occurred.
.PP
See \*(L"write callback\*(R" below.
.SS "registerFlush"
.IX Subsection "registerFlush"
Signature: \fIint\fR \fBregisterFlush\fR (\fIString\fR name,
\&\fICollectdFlushInterface\fR object)
.PP
Registers the \fBflush\fR function of \fIobject\fR with the daemon.
.PP
Returns zero upon success and non-zero when an error occurred.
.PP
See \*(L"flush callback\*(R" below.
.SS "registerShutdown"
.IX Subsection "registerShutdown"
Signature: \fIint\fR \fBregisterShutdown\fR (\fIString\fR name,
\&\fICollectdShutdownInterface\fR object);
.PP
Registers the \fBshutdown\fR function of \fIobject\fR with the daemon.
.PP
Returns zero upon success and non-zero when an error occurred.
.PP
See \*(L"shutdown callback\*(R" below.
.SS "registerLog"
.IX Subsection "registerLog"
Signature: \fIint\fR \fBregisterLog\fR (\fIString\fR name,
\&\fICollectdLogInterface\fR object);
.PP
Registers the \fBlog\fR function of \fIobject\fR with the daemon.
.PP
Returns zero upon success and non-zero when an error occurred.
.PP
See \*(L"log callback\*(R" below.
.SS "registerNotification"
.IX Subsection "registerNotification"
Signature: \fIint\fR \fBregisterNotification\fR (\fIString\fR name,
\&\fICollectdNotificationInterface\fR object);
.PP
Registers the \fBnotification\fR function of \fIobject\fR with the daemon.
.PP
Returns zero upon success and non-zero when an error occurred.
.PP
See \*(L"notification callback\*(R" below.
.SS "registerMatch"
.IX Subsection "registerMatch"
Signature: \fIint\fR \fBregisterMatch\fR (\fIString\fR name,
\&\fICollectdMatchFactoryInterface\fR object);
.PP
Registers the \fBcreateMatch\fR function of \fIobject\fR with the daemon.
.PP
Returns zero upon success and non-zero when an error occurred.
.PP
See \*(L"match callback\*(R" below.
.SS "registerTarget"
.IX Subsection "registerTarget"
Signature: \fIint\fR \fBregisterTarget\fR (\fIString\fR name,
\&\fICollectdTargetFactoryInterface\fR object);
.PP
Registers the \fBcreateTarget\fR function of \fIobject\fR with the daemon.
.PP
Returns zero upon success and non-zero when an error occurred.
.PP
See \*(L"target callback\*(R" below.
.SS "dispatchValues"
.IX Subsection "dispatchValues"
Signature: \fIint\fR \fBdispatchValues\fR (\fIValueList\fR)
.PP
Passes the values represented by the \fBValueList\fR object to the
\&\f(CW\*(C`plugin_dispatch_values\*(C'\fR function of the daemon. The \*(L"data set\*(R" (or list of
\&\*(L"data sources\*(R") associated with the object are ignored, because
\&\f(CW\*(C`plugin_dispatch_values\*(C'\fR will automatically lookup the required data set. It
is therefore absolutely okay to leave this blank.
.PP
Returns zero upon success or non-zero upon failure.
.SS "getDS"
.IX Subsection "getDS"
Signature: \fIDataSet\fR \fBgetDS\fR (\fIString\fR)
.PP
Returns the appropriate \fItype\fR or \fBnull\fR if the type is not defined.
.SS "logError"
.IX Subsection "logError"
Signature: \fIvoid\fR \fBlogError\fR (\fIString\fR)
.PP
Sends a log message with severity \fB\s-1ERROR\s0\fR to the daemon.
.SS "logWarning"
.IX Subsection "logWarning"
Signature: \fIvoid\fR \fBlogWarning\fR (\fIString\fR)
.PP
Sends a log message with severity \fB\s-1WARNING\s0\fR to the daemon.
.SS "logNotice"
.IX Subsection "logNotice"
Signature: \fIvoid\fR \fBlogNotice\fR (\fIString\fR)
.PP
Sends a log message with severity \fB\s-1NOTICE\s0\fR to the daemon.
.SS "logInfo"
.IX Subsection "logInfo"
Signature: \fIvoid\fR \fBlogInfo\fR (\fIString\fR)
.PP
Sends a log message with severity \fB\s-1INFO\s0\fR to the daemon.
.SS "logDebug"
.IX Subsection "logDebug"
Signature: \fIvoid\fR \fBlogDebug\fR (\fIString\fR)
.PP
Sends a log message with severity \fB\s-1DEBUG\s0\fR to the daemon.
.SH "REGISTERING CALLBACKS"
.IX Header "REGISTERING CALLBACKS"
When starting up, collectd creates an object of each configured class. The
constructor of this class should then register \*(L"callbacks\*(R" with the daemon,
using the appropriate static functions in \fBCollectd\fR,
see \*(L"\s-1EXPORTED API FUNCTIONS\*(R"\s0 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 \fBorg.collectd.api\fR namespace.
.PP
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 \s-1API\s0 functions. One could, for example, start a new thread in
the constructor and dispatch (submit to the daemon) values asynchronously,
whenever one is available.
.PP
Each callback method is now explained in more detail:
.SS "config callback"
.IX Subsection "config callback"
Interface: \fBorg.collectd.api.CollectdConfigInterface\fR
.PP
Signature: \fIint\fR \fBconfig\fR (\fIOConfigItem\fR ci)
.PP
This method is passed a \fBOConfigItem\fR object, if both, method and
configuration, are available. \fBOConfigItem\fR is the root of a tree representing
the configuration for this plugin. The root itself is the representation of the
\&\fB<Plugin\ />\fR block, so in next to all cases the children of the
root are the first interesting objects.
.PP
To signal success, this method has to return zero. Anything else will be
considered an error condition and the plugin will be disabled entirely.
.PP
See \*(L"registerConfig\*(R" above.
.SS "init callback"
.IX Subsection "init callback"
Interface: \fBorg.collectd.api.CollectdInitInterface\fR
.PP
Signature: \fIint\fR \fBinit\fR ()
.PP
This method is called after the configuration has been handled. It is
supposed to set up the plugin. e.\ g. start threads, open connections, or
check if can do anything useful at all.
.PP
To signal success, this method has to return zero. Anything else will be
considered an error condition and the plugin will be disabled entirely.
.PP
See \*(L"registerInit\*(R" above.
.SS "read callback"
.IX Subsection "read callback"
Interface: \fBorg.collectd.api.CollectdReadInterface\fR
.PP
Signature: \fIint\fR \fBread\fR ()
.PP
This method is called periodically and is supposed to gather statistics in
whatever fashion. These statistics are represented as a \fBValueList\fR object and
sent to the daemon using dispatchValues.
.PP
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 \*(L"read\*(R"\-methods are not suspended for increasing intervals like C
\&\*(L"read\*(R"\-functions.
.PP
See \*(L"registerRead\*(R" above.
.SS "write callback"
.IX Subsection "write callback"
Interface: \fBorg.collectd.api.CollectdWriteInterface\fR
.PP
Signature: \fIint\fR \fBwrite\fR (\fIValueList\fR vl)
.PP
This method is called whenever a value is dispatched to the daemon. The
corresponding C \*(L"write\*(R"\-functions are passed a \f(CW\*(C`data_set_t\*(C'\fR, so they can
decide which values are absolute values (gauge) and which are counter values.
To get the corresponding \f(CW\*(C`List<DataSource>\*(C'\fR, call the \fBgetDataSource\fR
method of the \fBValueList\fR object.
.PP
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.
.PP
See \*(L"registerWrite\*(R" above.
.SS "flush callback"
.IX Subsection "flush callback"
Interface: \fBorg.collectd.api.CollectdFlushInterface\fR
.PP
Signature: \fIint\fR \fBflush\fR (\fIint\fR timeout, \fIString\fR identifier)
.PP
This method is called when the daemon received a flush command. This can either
be done using the \f(CW\*(C`USR1\*(C'\fR signal (see \fIcollectd\fR\|(1)) or using the \fIunixsock\fR
plugin (see \fIcollectd\-unixsock\fR\|(5)).
.PP
If \fItimeout\fR 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.
.PP
The \fIidentifier\fR 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 \fInull\fR.
.PP
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.
.PP
See \*(L"registerFlush\*(R" above.
.SS "shutdown callback"
.IX Subsection "shutdown callback"
Interface: \fBorg.collectd.api.CollectdShutdownInterface\fR
.PP
Signature: \fIint\fR \fBshutdown\fR ()
.PP
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.
.PP
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.
.PP
See \*(L"registerShutdown\*(R" above.
.SS "log callback"
.IX Subsection "log callback"
Interface: \fBorg.collectd.api.CollectdLogInterface\fR
.PP
Signature: \fIvoid\fR \fBlog\fR (\fIint\fR severity, \fIString\fR message)
.PP
This callback can be used to receive log messages from the daemon.
.PP
The argument \fIseverity\fR is one of:
.IP "\(bu" 4
org.collectd.api.Collectd.LOG_ERR
.IP "\(bu" 4
org.collectd.api.Collectd.LOG_WARNING
.IP "\(bu" 4
org.collectd.api.Collectd.LOG_NOTICE
.IP "\(bu" 4
org.collectd.api.Collectd.LOG_INFO
.IP "\(bu" 4
org.collectd.api.Collectd.LOG_DEBUG
.PP
The function does not return any value.
.PP
See \*(L"registerLog\*(R" above.
.SS "notification callback"
.IX Subsection "notification callback"
Interface: \fBorg.collectd.api.CollectdNotificationInterface\fR
.PP
Signature: \fIint\fR \fBnotification\fR (\fINotification\fR n)
.PP
This callback can be used to receive notifications from the daemon.
.PP
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.
.PP
See \*(L"registerNotification\*(R" above.
.SS "match callback"
.IX Subsection "match callback"
The match (and target, see \*(L"target callback\*(R" 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 \*(L"match\*(R" objects is
called \*(L"match factory\*(R".
.PP
See \*(L"registerMatch\*(R" above.
.PP
\fIFactory object\fR
.IX Subsection "Factory object"
.PP
Interface: \fBorg.collectd.api.CollectdMatchFactoryInterface\fR
.PP
Signature: \fICollectdMatchInterface\fR \fBcreateMatch\fR
(\fIOConfigItem\fR ci);
.PP
Called by the daemon to create \*(L"match\*(R" objects.
.PP
Returns: A new object which implements the \fBCollectdMatchInterface\fR interface.
.PP
\fIMatch object\fR
.IX Subsection "Match object"
.PP
Interface: \fBorg.collectd.api.CollectdMatchInterface\fR
.PP
Signature: \fIint\fR \fBmatch\fR (\fIDataSet\fR ds, \fIValueList\fR vl);
.PP
Called when processing a chain to determine whether or not a \fIValueList\fR
matches. How values are matches is up to the implementing class.
.PP
Has to return one of:
.IP "\(bu" 4
\&\fBCollectd.FC_MATCH_NO_MATCH\fR
.IP "\(bu" 4
\&\fBCollectd.FC_MATCH_MATCHES\fR
.SS "target callback"
.IX Subsection "target callback"
The target (and match, see \*(L"match callback\*(R" 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 \*(L"target\*(R" objects is
called \*(L"target factory\*(R".
.PP
See \*(L"registerTarget\*(R" above.
.PP
\fIFactory object\fR
.IX Subsection "Factory object"
.PP
Interface: \fBorg.collectd.api.CollectdTargetFactoryInterface\fR
.PP
Signature: \fICollectdTargetInterface\fR \fBcreateTarget\fR
(\fIOConfigItem\fR ci);
.PP
Called by the daemon to create \*(L"target\*(R" objects.
.PP
Returns: A new object which implements the \fBCollectdTargetInterface\fR
interface.
.PP
\fITarget object\fR
.IX Subsection "Target object"
.PP
Interface: \fBorg.collectd.api.CollectdTargetInterface\fR
.PP
Signature: \fIint\fR \fBinvoke\fR (\fIDataSet\fR ds, \fIValueList\fR vl);
.PP
Called when processing a chain to perform some action. The action performed is
up to the implementing class.
.PP
Has to return one of:
.IP "\(bu" 4
\&\fBCollectd.FC_TARGET_CONTINUE\fR
.IP "\(bu" 4
\&\fBCollectd.FC_TARGET_STOP\fR
.IP "\(bu" 4
\&\fBCollectd.FC_TARGET_RETURN\fR
.SH "EXAMPLE"
.IX Header "EXAMPLE"
This short example demonstrates how to register a read callback with the
daemon:
.PP
.Vb 2
\&  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);
\&    }
\&  }
.Ve
.SH "PLUGINS"
.IX Header "PLUGINS"
The following plugins are implemented in \fIJava\fR. Both, the \fBLoadPlugin\fR
option and the \fBPlugin\fR block must be inside the
\&\fB<Plugin\ java>\fR block (see above).
.SS "GenericJMX plugin"
.IX Subsection "GenericJMX plugin"
The GenericJMX plugin reads \fIManaged Beans\fR (MBeans) from an \fIMBeanServer\fR
using \s-1JMX. JMX\s0 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 \fIJava Virtual Machine\fR (\s-1JVM\s0) to provide
information about the memory used, threads and so on.
.PP
The configuration of the \fIGenericJMX plugin\fR consists of two blocks: \fIMBean\fR
blocks that define a mapping of MBean attributes to the XtypesX used by
\&\fIcollectd\fR, and \fIConnection\fR blocks which define the parameters needed to
connect to an \fIMBeanServer\fR and what data to collect. The configuration of the
\&\fI\s-1SNMP\s0 plugin\fR is similar in nature, in case you know it.
.PP
\fIMBean blocks\fR
.IX Subsection "MBean blocks"
.PP
\&\fIMBean\fR blocks specify what data is retrieved from \fIMBeans\fR and how that data
is mapped on the \fIcollectd\fR data types. The block requires one string
argument, a name. This name is used in the \fIConnection\fR blocks (see below) to
refer to a specific \fIMBean\fR block. Therefore, the names must be unique.
.PP
The following options are recognized within \fIMBean\fR blocks:
.IP "\fBObjectName\fR \fIpattern\fR" 4
.IX Item "ObjectName pattern"
Sets the pattern which is used to retrieve \fIMBeans\fR from the \fIMBeanServer\fR.
If more than one MBean is returned you should use the \fBInstanceFrom\fR option
(see below) to make the identifiers unique.
.Sp
See also:
<http://java.sun.com/javase/6/docs/api/javax/management/ObjectName.html>
.IP "\fBInstancePrefix\fR \fIprefix\fR" 4
.IX Item "InstancePrefix prefix"
Prefixes the generated \fIplugin instance\fR with \fIprefix\fR. \fI(optional)\fR
.IP "\fBInstanceFrom\fR \fIproperty\fR" 4
.IX Item "InstanceFrom property"
The \fIobject names\fR used by \s-1JMX\s0 to identify \fIMBeans\fR include so called
\&\fIXpropertiesX\fR 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 \fIplugin instance\fR from
the appropriate property values. This option is optional and may be repeated to
generate the \fIplugin instance\fR from multiple property values.
.IP "\fB<value />\fR blocks" 4
.IX Item "<value /> blocks"
The \fIvalue\fR blocks map one or more attributes of an \fIMBean\fR to a value list
in \fIcollectd\fR. There must be at least one Value block within each \fIMBean\fR
block.
.RS 4
.IP "\fBType\fR type" 4
.IX Item "Type type"
Sets the data set used within \fIcollectd\fR to handle the values of the \fIMBean\fR
attribute.
.IP "\fBInstancePrefix\fR \fIprefix\fR" 4
.IX Item "InstancePrefix prefix"
Works like the option of the same name directly beneath the \fIMBean\fR block, but
sets the type instance instead. \fI(optional)\fR
.IP "\fBInstanceFrom\fR \fIprefix\fR" 4
.IX Item "InstanceFrom prefix"
Works like the option of the same name directly beneath the \fIMBean\fR block, but
sets the type instance instead. \fI(optional)\fR
.IP "\fBTable\fR \fBtrue\fR|\fBfalse\fR" 4
.IX Item "Table true|false"
Set this to true if the returned attribute is a \fIcomposite type\fR. If set to
true, the keys within the \fIcomposite type\fR is appended to the
\&\fItype instance\fR.
.IP "\fBAttribute\fR \fIpath\fR" 4
.IX Item "Attribute path"
Sets the name of the attribute from which to read the value. You can access the
keys of composite types by using a dot to concatenate the key name to the
attribute name. For example: Xattrib0.key42X. If \fBTable\fR is set to \fBtrue\fR
\&\fIpath\fR must point to a \fIcomposite type\fR, otherwise it must point to a numeric
type.
.RE
.RS 4
.RE
.PP
\fIConnection blocks\fR
.IX Subsection "Connection blocks"
.PP
Connection blocks specify \fIhow\fR to connect to an \fIMBeanServer\fR and what data
to retrieve. The following configuration options are available:
.IP "\fBHost\fR \fIname\fR" 4
.IX Item "Host name"
Host name used when dispatching the values to \fIcollectd\fR. The option sets this
field only, it is \fInot\fR used to connect to anything and doesn't need to be a
real, resolvable name.
.IP "\fBServiceURL\fR \fI\s-1URL\s0\fR" 4
.IX Item "ServiceURL URL"
Specifies how the \fIMBeanServer\fR can be reached. Any string accepted by the
\&\fIJMXServiceURL\fR is valid.
.Sp
See also:
<http://java.sun.com/javase/6/docs/api/javax/management/remote/JMXServiceURL.html>
.IP "\fBUser\fR \fIname\fR" 4
.IX Item "User name"
Use \fIname\fR to authenticate to the server. If not configured, XmonitorRoleX
will be used.
.IP "\fBPassword\fR \fIpassword\fR" 4
.IX Item "Password password"
Use \fIpassword\fR to authenticate to the server. If not given, unauthenticated
access is used.
.IP "\fBInstancePrefix\fR \fIprefix\fR" 4
.IX Item "InstancePrefix prefix"
Prefixes the generated \fIplugin instance\fR with \fIprefix\fR. If a second
\&\fIInstancePrefix\fR is specified in a referenced \fIMBean\fR block, the prefix
specified in the \fIConnection\fR block will appear at the beginning of the
\&\fIplugin instance\fR, the prefix specified in the \fIMBean\fR block will be appended
to it.
.IP "\fBCollect\fR \fImbean_block_name\fR" 4
.IX Item "Collect mbean_block_name"
Configures which of the \fIMBean\fR blocks to use with this connection. May be
repeated to collect multiple \fIMBeans\fR from this server.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIcollectd\fR\|(1),
\&\fIcollectd.conf\fR\|(5),
\&\fIcollectd\-perl\fR\|(5),
\&\fItypes.db\fR\|(5)
.SH "AUTHOR"
.IX Header "AUTHOR"
Florian Forster <octo\ at\ collectd.org>