
=pod

=head1 NAME 

JMX::Jmx4Perl::Manual - Manual for B<jmx4perl>

=head1 DESCRIPTION

JMX (Java Management Extensions) is the standard management solution in the
Java world. Since JDK 1.5 it is available in every Java Virtual Machine and
especially JEE application servers use this technology intensively for exposing
managable entities. In fact, the popular JEE Server JBoss 4 is based on a JMX
kernel.

For the Perl world, it's not that easy to access JMX MBeans. MBeans are is the
Java term for JMX managed entities. The existing solutions are mostly based on
the Java standard JSR-160 (L<http://jcp.org/en/jsr/detail?id=160>), which
defines how JMX can be accessed remotely. The problem of JSR-160 with respect
to Perl is, that the default communication protocols rely on exchanging
serialized Java objects. Hence they require to start a Java Virtual Machine, in
the one way or other. This has quite some implications concerning installation
requirements (you need a Java virtual machine with the proper version
installed) and performance (firing up a JVM is not something you get for free)

The ultimate goal of B<jmx4perl> is to bridge both worlds in the most simplest
way. This is done with an agent based approach as described below. In short,
the building blocks of this bridge are based on standards well known and used
in both worlds: HTTP and JSON.

Another goal is to provide an abstraction for accessing certain, commonly known
MBeans for various supported JEE application server, which differ in naming
from brand to brand. For now, the JEE servers supported are JBoss 4 & 5, Oracle
WebLogic 9 & 10, Glassfish 2, Jonas 4 and Geronimo 2 as well as the pure
servlet containers Jetty 5 and 6, Tomcat 4, 5 & 6. Other platforms might work
as well, however they are not yet tested. Please let me know, whether jmx4perl
works for you on other servers as well (which is highly likely due to the
simplistic nature of the agent webapp). I got reports, that it works on IBM
Websphere 6.1 and 7 as well, but unfortunately I can't verify this on my own
due to the lack of a proper testing environment.

B<jmx4perl> is not an academic exercise. In fact it originates from the need
to let Nagios (a hopefully well known open source monitoring solution, see
L<http://www.nagios.org>) access JEE appliation servers in a painless way. You
can find a nagios check in the scripts directory, which is a prefactored check
directly usable in a Nagios setup.

Additionally, there is a command line tool called (incidentally ;-) L<jmx4perl>
which allows for simple access to JMX MBeans and much more features. 

=head1 MBean Features

JMX is a complex specification, which can not be completely revealed in this
short documentation. Refer to
L<http://java.sun.com/docs/books/tutorial/jmx/index.html> for a JMX
tutorial. But in short, one can distinguish between three kinds of operational
modes:

=over

=item Attribute reading and writing

An MBean can have one or more attributes, which can be read and/or
written. 

=item Execution of operations

A MBean can expose certain operations, which can be executed via JMX
calls. 

=item Notifications

Listeners can register to get notified for certain notifications by the
MBeans. This is not yet supported by jmx4perl and it is technically quite
challenging, since HTTP, our transport protocol, is a typical request-response
based protocol which is unidirectional by nature. However, there are already
ideas how to overcome this limitation, but please don't hold your breath. This
is on the roadmap, but with very low priority only. Tell me your use case if
you want to push it up.

=back

In short, jmx4perl supports only reading of attributes for the moment. In most
cases this is sufficient for monitoring purposes, i.e. Nagios monitoring. 

=head1 AGENT APPROACH

As mentioned above we are using an agent based approach. An agent based
approach requires you to install a small Java Webapplication within your JEE
application server. It registers itself locally to the JMX MBeanServer, and
listens to HTTP requests whose results are translated into a JSON
representation. This reponse can be easily picked up by a Perl module,
L<JMX::Jmx4Perl> in our case. This kind of approach differs from the canonical
approach as suggested by the JMX specification itself quite a bit. It only
works for application servers, where Java web applications can be
deployed. Otherwise, it has also quite some advantages:

=head2 Advantages

=over 4 

=item * 

No special startup options for the JEE server are required for exposing JMX
informations as it would be the case for exporting JMX via JSR-160 connectors. 

=item * 

No Java installation required on the client for using the agent

=item * 

No overhead with regard to startup times of a JVM

=item *

Since the agent is a standard Java Webapplication it can be secured by
standard JEE means like any other Webapplication. 

=item *

Firewall friendly since all HTTP communication goes over a single port. 

=back 

=head2 Disadvantages

=over 4

=item * 

Only applicable for JEE server or servlet container, where a WAR (Java Web
Archive) can be deployed.

=item * 

For now, only reading of MBean attributes is supported. However, support for
writing of attributes and execution of operations are underway. Notifications
are bit more involved, but chances are good that some sort of support will be
incorporated into a future version as well. 

=back 

=head1 INSTALLATION 

The Perl part installs as any other module via Module::Build, which
you need to have installed. Using

  perl Build.PL
  ./Build
  ./Build test
  ./Build install

will install the modules. If you have Java and "ant" (a Java build
tool) installed, the Java agent will be compiled and packaged as
well. However, this is not required. A precompiled F<j4p.war>
can be found in the F<agent> directory.

For the module to work, you need to deploy F<j4p.war> to the JEE Server
to monitor. The concrete steps depend on the specific way for deploying on the
target server, which in most cases is as simple as copying the agent into a
specific directory. Please consult the documentation of your Java application
server for the details (look for "deployment" and "web application" (or "war))) 

To test it, you can use L<jmx4perl> with the URL of the depolyed
agent:

  jmx4perl http://jeeserver:port/j4p
      
Consult L<jmx4perl> for further details. 
 
=head1 FEATURES

=head2 Reading and Writing Attributes

Jmx4Perl knows how to read any attribute and how to write to certain attributes
for whose types are string-to-object conversions are known. Currently, writing
of attributes of type String, int, long and boolean is supported. As a special
features, Jmx4Perl has the notion of an I<inner path> which is a XPath like
expression for pointing into the object returned by a read or write
operation. 

=head2 Execution of JMX operations

It is easy to execute JMX operations, even with arguments. However, they same
restriction for the argument types apply as for writing attributes: There must
be an easy way to deserialize an argument from a string representation. The
same types as for writing attributes are supported.

=head2 Autodetection and Product Support

Jmx4Perl is able to autodectect various application servers. This is done by
querying a certain MBean attribute which is unique for this specific
product. The following application servers can be autodetected:

=over

=item * 

JBoss 4 and 5 (L<http://www.jboss.org/jbossas/>)

=item *

Oracle WebLogic 9 & 10 (L<http://www.oracle.com/appserver/>)

=item *

Glassfish 2 and 3 (L<https://glassfish.dev.java.net/>)

=item *

Apache Geronimo 2 (L<http://geronimo.apache.org/>)

=item * 

Jonas 4 (L<http://jonas.ow2.org/>)

=item * 

Tomcat 4, 5 and 6 (L<http://tomcat.apache.org/>)

=item * 

Jetty 5 and 6 (http://www.mortbay.org/jetty/)

=back 

All these application servers has been tested to work with jmx4perl. The
testing environment is a 64bit Ubuntu 9.04 installation, running in a virtual
machine. However, this should not make any difference for another platform, so
I'm pretty confident that the application servers from the list above will work
with jmx4perl on any OS. Please open a bug at
L<http://rt.cpan.org/Public/Bug/Report.html?Queue=jmx4perl> if you encounter
any problems.

I would like to support IBM Websphere as well, but unfortunately setting up a
testing environment takes to much effort. If someone has a IBM Websphere
testing environment which I could use, I would be glad to setup a Websphere
Handler as well.

Please note, that autodetection is not for free with respect to performance. It
takes some considerable time to probe various servers. So, if you have the
chance to provide the application server id, you should do this. This is only
relevant if you are going to use the aliasing feature.

=head2 Aliasing

L<JMX::Jmx4Perl::Alias> provides a thin abstraction layer about over the JMX
naming scheme so that you can use a single alias value to access the
combination (MBean name,attribute) or (MBean name,operation). It also maps the
differing naming schemes of different application server to unique names, as
far as this is possible. E.g. the alias C<SERVER_VERSION> maps on JBoss to the
attribute C<VersionNumber> of MBean C<jboss.system:type=Server>, whereas for
Jetty it's mapped to MBean C<org.mortbay:jetty=default>, Attribute C<version>. 

Remember, you can always use the the native JMX naming to access your MBeans
without worrying about aliasing at all.  

=head2 History Tracking

The agent C<j4p> can be switched into a history tracking mode, where it
records the values for C<read>, C<write> and C<exec> operations (the return
value for the late mode). You have to call a certain, jmx4perl specific, MBean
to turn it on. If switched on, each request contains an additional history
entry containing the list of historical values along with their timestamps. The
history is stored in a list with fixed length so that the oldes value gets
removed from the list in case of an overflow. 

=head2 Full featured Nagios plugin C<check_jmx4perl> 

A full functional Nagios plugin called C<check_jmx4perl> is provided in the
scripts directory. It can be used to monitor any JMX Mbean's attribute with a
numeric value. Thresholds for warning and critical values can be provided in
the formas as defined by L<Nagios::Plugin>. You can use autodetection and
aliasing here as well.

=head1 WHAT'S NEXT ?

There are several entry points for jmx4perl. The easiest is to start to play
around with F<check_jmx4perl>. This is a complete command lines tool tailored
for usage with Nagios. Read its man page for the usage.

Next, L<JMX::Jmx4Perl> is the entry module. Use it, if you need
programmatically access to JMX. 

Of course, you are free to access the agent servlet directly without the usage
of the provided modules. A description of the request and response format can
be found in the protocol description L<JMX::Jmx4Perl::Agent::Protocol>. 

=head1 FURTHER DIRECTIONS

As an supplement to the provided agent based approach, the more traditional way
of using a JVM for remote communication would be a nice additional option. With
help of modules like C<Java::Import> this should fit nicely in the provided
API. 

Support for attribute writing, execution of operations and (maybe)
notifications.

=head1 ROADMAP

=over

=item *

JSR-77 support

=back


=head1 LICENSE

Copyright (C) 2009 Roland Huss

Jmx4perl is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
(at your option) any later version.

jmx4perl is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with jmx4perl.  If not, see L<http://www.gnu.org/licenses/>.

A commercial license is available as well. You can either apply the GPL or
obtain a commercial license for closed source development. Please contact
roland@cpan.org for further information.

=head1 PROFESSIONAL SERVICES

Just in case you need professional support for jmx4perl (or Nagios or JMX in
general), you might want to have a look at
L<http://www.consol.com/opensource/nagios/>. Contact roland.huss@consol.de for
further information (or use the contact form at L<http://www.consol.com/contact/>)

=head1 AUTHOR

roland@cpan.org

=cut
