GenericMBeanException (Java Platform SE 7 b76)

Please note that this documentation is not final and is subject to change.

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Java™ Platform
Standard Ed. 7
DRAFT ea-b76

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.management
Class GenericMBeanException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          javax.management.JMException
              javax.management.MBeanException
                  javax.management.GenericMBeanException

All Implemented Interfaces:: Serializable

public class GenericMBeanException
extends MBeanException

A customizable exception that has an optional error code string and payload. By using this exception in an MBean, you can avoid requiring clients of the MBean to have custom exception classes.

An instance of this class has an optional error code, and an optional payload known as userData. This allows you to distinguish between different sorts of exception while still using this class for all of them.

To produce a suitable userData, it is often simplest to use the MXBean framework. For example, suppose you want to convey a severity and a subsystem with your exception, which are respectively an int and a String. You could define a class like this:

 public class ExceptionDetails {
     private final int severity;
     private final String subsystem;

     @ConstructorProperties({"severity", "subsystem"})
     public ExceptionDetails(int severity, String subsystem) {
         this.severity = severity;
         this.subsystem = subsystem;
     }

     public int getSeverity() {
         return severity;
     }

     public String getSubsystem() {
         return subsystem;
     }
 }

Then you can get the MXBean framework to transform ExceptionDetails into CompositeData like this:

 static final MXBeanMapping exceptionDetailsMapping = MXBeanMappingFactory.DEFAULT.mappingForType(
         ExceptionDetails.class, MXBeanMappingFactory.DEFAULT);

 public static GenericMBeanException newGenericMBeanException(
         String message, String errorCode, int severity, String subsystem) {
     ExceptionDetails details = new ExceptionDetails(severity, subsystem);
     CompositeData userData = (CompositeData)
             exceptionDetailsMapping.toOpenValue(details);
     return new GenericMBeanException(
             message, errorCode, userData, (Throwable) null);
 }

 ...
     throw newGenericMBeanException(message, errorCode, 25, "foosystem");

A client that knows the ExceptionDetails class can convert back from the userData of a GenericMBeanException that was generated as above:

 ...
     try {
         mbeanProxy.foo();
     } catch (GenericMBeanException e) {
         CompositeData userData = e.getUserData();
         ExceptionDetails details = (ExceptionDetails)
                 exceptionDetailsMapping.fromOpenValue(userData);
         System.out.println("Exception Severity: " + details.getSeverity());
     }
 ...

The Descriptor field exceptionErrorCodes can be used to specify in the MBeanOperationInfo for an operation what the possible error codes are when that operation throws GenericMBeanException. It can also be used in an MBeanConstructorInfo or MBeanAttributeInfo to specify what the possible error codes are for GenericMBeanException when invoking that constructor or getting that attribute, respectively. The field setExceptionErrorCodes can be used to specify what the possible error codes are when setting an attribute.

You may want to use the @DescriptorKey facility to define annotations that allow you to specify the error codes. If you define...

 @Documented
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface ErrorCodes {
     @DescriptorKey("exceptionErrorCodes")
     String[] value();
 }

...then you can write MBean interfaces like this...

 public interface FooMBean {  // or FooMXBean
     @ErrorCodes({"com.example.bad", "com.example.worse"})
     public void foo() throws GenericMBeanException;
 }

The Descriptor field exceptionUserDataTypes can be used to specify in the MBeanOperationInfo for an operation what the possible types of userData are when that operation throws GenericMBeanException. It is an array of CompositeType values describing the possible CompositeData formats. This field can also be used in an MBeanConstructorInfo or MBeanAttributeInfo to specify the possible types of user data for GenericMBeanException when invoking that constructor or getting that attribute, respectively. The field setExceptionUserDataTypes can be used to specify the possible types of user data for exceptions when setting an attribute. If a Descriptor has both exceptionErrorCodes and exceptionUserDataTypes then the two arrays should be the same size; each pair of corresponding elements describes one kind of exception. Similarly for setExceptionErrorCodes and setExceptionUserDataTypes.

Serialization

For compatibility reasons, instances of this class are serialized as instances of MBeanException. Special logic in that class converts them back to instances of this class at deserialization time. If the serialized object is deserialized in an earlier version of the JMX API that does not include this class, then it will appear as just an MBeanException and the error code or userData will not be available.

Since:: 1.7
See Also:: Serialized Form

Constructor Summary
Constructor and Description
`GenericMBeanException(String message)` Constructs a new `GenericMBeanException` with the given detail message.
`GenericMBeanException(String message, String errorCode, CompositeData userData)` Constructs a new `GenericMBeanException` with the given detail message, error code, and user data.
`GenericMBeanException(String message, String errorCode, CompositeData userData, Throwable cause)` Constructs a new `GenericMBeanException` with the given detail message, error code, user data, and cause.
`GenericMBeanException(String message, Throwable cause)` Constructs a new `GenericMBeanException` with the given detail message and cause.

Method Summary
Modifier and Type	Method and Description
`String`	`getErrorCode()` Returns the error code of this exception.
`CompositeData`	`getUserData()` Returns the userData of this exception.

Methods inherited from class javax.management.MBeanException
`getTargetException`

Methods inherited from class java.lang.Throwable
`fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Constructor Detail