NAME

JMX::Jmx4Perl::Product::BaseHandler - Base package for product specific handler

DESCRIPTION

This base class is used for specific JMX::Jmx4Perl::Product in order to provide some common functionality. Extends this package if you want to hook in your own product handler. Any module below JMX::Jmx4Perl::Product:: will be automatically picked up by JMX::Jmx4Perl.

METHODS

$handler = JMX::Jmx4Perl::Product::MyHandler->new($jmx4perl);

Constructor which requires a JMX::Jmx4Perl object as single argument. If you overwrite this method in a subclass, dont forget to call SUPER::new, but normally there is little need for overwritting new.

$id = $handler->id()

Return the id of this handler, which must be unique among all handlers. This method is abstract and must be overwritten by a subclass

$id = $handler->name()

Return this handler's name. This method returns by default the id, but can be overwritten by a subclass to provide something more descriptive.

$vendor = $handler->vendor()

Get the vendor for this product. If the handler support JSR 77 this is extracted directly from the JSR 77 information. Otherwise, as handler is recommended to detect the vendor on its own with a method _try_vendor. Note, that he shoudl query the server for this information and return undef if it could not be extracted from there. The default implementation of "autodetect" relies on the information fetched here.

$version = $handler->version()

Get the version of the underlying application server or return undef if the version can not be determined. Please note, that this method can be only called after autodetect() has been called since this call is normally used to fill in that version number.

$is_product = $handler->autodetect()

Return true, if the appserver to which the given JMX::Jmx4Perl (at construction time) object is connected can be handled by this product handler. If this module detects that it definitely can not handle this application server, it returnd false. If an error occurs during autodectection, this method should return undef.

($what,$pattern) = $handler->autodetect_pattern()

Method returning a pattern which is applied to the vendor or version information provided by the "version" or "vendor" in order to detect, whether this handler matches the server queried. This pattern is used in the default implementation of autodetect to check for a specific product. By default, this method returns (undef,undef) which implies, that autodetect for this handler returns false. Override this with the pattern matching the specific product to detect.

$order = $handler->order()

Return some hint for the ordering of product handlers in the autodetection chain. This default implementation returns undef, which implies no specific ordering. If a subclass returns an negative integer it will be put in front of the chain, if it returns a positive integer it will be put at the end of the chain, in ascending order, respectively. E.g for the autodetection chain, the ordering index of the included handlers looks like

  -10,-5,-3,-1,undef,undef,undef,undef,undef,2,3,10000

The ordering index of the fallback handler (which always fire) is 1000, so it doesn't make sense to return a higher index for a custom producthandler.

$can_jsr77 = $handler->jsr77()

Return true if the app server represented by this handler is an implementation of JSR77, which provides a well defined way how to access deployed applications and other stuff on a JEE Server. I.e. it defines how MBean representing this information has to be named. This base class returns false, but this method can be overwritten by a subclass.

($mbean,$attribute,$path) = $self->alias($alias)

($mbean,$operation) = $self->alias($alias)

Return the mbean and attribute name for an registered attribute alias, for an operation alias, this method returns the mbean and the operation name. A subclass should call this parent method if it doesn't know about a specific alias, since JVM MXBeans are aliased here.

Returns undef if this product handler doesn't know about the provided alias.

$description = $self->info()

Get a textual description of the product handler. By default, it prints out the id, the version and well known properties known by the Java VM

my $aliases = $self->init_aliases()

Method used during construction of a handler for obtaining a translation map of aliases to the real values. Each specific handler can overwrite this method to return is own resolving map. The returned map has two top level keys: attributes and operations. Below these keys are the maps for attribute and operation aliases, respectively. These two maps have alias names as keys (not the alias objects themselves) and a data structure for the getting to the aliased values. This data structure can be written in three variants:

• A arrayref having two or three string values for attributes describing the real MBean's name, the attribute name and an optional path within the value. For operations, it's an arrayref to an array with two elements: The MBean name and the operation name.

• A arrayref to an array with a single value which must be a coderef. This subroutine is called with the handler as single argument and is expected to return an arrayref in the form described above.

• A coderef, which is executed when JMX::Jmx4Perl->get_attribute() or JMX::Jmx4Perl->execute() is called and which is supossed to do the complete lookup. The first argument to the subroutine is the handler which can be used to access the JMX::Jmx4Perl object. The additional argument are either the value to set (for JMX::Jmx4Perl->set_attribute() or the operation's arguments for JMX::Jmx4Perl->execute(). This is the most flexible way for a handler to do anything it likes to do when an attribute value is requested or an operation is about to be executed. You have to return a JMX::Jmx4Perl::Response object.

Example :

  sub init_aliases {
      my $self = shift;
      return {
         attributes => { 
             SERVER_ADDRESS => [ "jboss.system:type=ServerInfo", "HostAddress"],
             SERVER_VERSION => sub { 
                return shift->version();
             },
             SERVER_HOSTNAME => [ sub { return [ "jboss.system:type=ServerInfo", "HostName" ] } ]        
         },
         operations => {
             THREAD_DUMP => [ "jboss.system:type=ServerInfo", "listThreadDump"]
         }
      }
  }

Of course, you are free to overwrite alias or resolve_alias on your own in order to do want you want it to do.

This default implementation returns an empty hashref.

$has_attribute = $handler->try_attribute($jmx4perl,$property,$object,$attribute,$path)

Internal method which tries to request an attribute. If it could not be found, it returns false.

The first arguments $property specifies an property of this object, which is set with the value of the found attribute or 0 if this attribute does not exist.

The server call is cached internally by examing $property. So, never change or set this property on this object manually.

$server_info = $handler->server_info()

Get's a textual description of the server. By default, this includes the id and the version, but can (and should) be overidden by a subclass to contain more specific information

$jvm_info = $handler->jvm_info()

Get information which is based on well known MBeans which are available for every Virtual machine. This is a textual representation of the information.

LICENSE

This file is part of jmx4perl.

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/>.

A commercial license is available as well. Please contact roland@cpan.org for further details.

AUTHOR

roland@cpan.org