#!/usr/bin/perl



=head1 jmx4perl 

I<This document is a work in progress. Please send comments and typos to
roland@cpan.org> 

JMX (Java Management Extensions) is the management solution in the Java
World. Since JDK 1.5 it is available in every Java Virtual Machine and
especially JEE Application Server use this technology massively for exposing
manageable entities to the outside. In fact, the very popular JEE Server JBoss
4 is based on a JMX based kernel. 

For the Perl World, it's not that easy to access JMX MBeans (how the managed
entities in JMX are called). The existing solutions (TODO: references to
check_jmx ....)

The goal of C<jmx4perl> is to bridge both worlds in the most simplest way by
using an agent approach.

Another goal is to provide an abstraction to certain, well 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, Weblogic 10 and
Glassfish as well as the pure servlet containers Jetty 6, Tomcat 5 & 6. Other
platform might work as well, however they are not tested. Please let me know,
when it works on other Servers as well, which is highly likely due to the
simplistic nature of the agent webapp.

Initial goal: Nagios (nagios check as an example)

=head1 Agent based Approach

An agent based approach requires you to install a small piece of Java software
within your application server, which exposes the required 

=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 using the agent

=item * 

No overhead with regard to startup times of a JVM

=item *

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

=item *

Firewall friendly since simply HTTP communication over a single port.

=back 

=head2 Disadvantages

=over 4

=item * 

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

=item * 

For now, only reading of MBean attributes is supported

=back 

=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 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 <http://www.gnu.org/licenses/>.

=head1 AUTHOR

roland@cpan.org

=cut
