bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Developing Security Providers for WebLogic Server

MBean Definition File (MDF) Element Syntax

An MBean Definition File (MDF) is an input file to the WebLogic MBeanMaker utility, which uses the file to create an MBean type for managing a custom security provider. An MDF must be formatted as a well-formed and valid XML file that describes a single MBean type. The following sections describe all the elements and attributes that are available for use in a valid MDF:

- The MBeanType (Root) Element

- The MBeanAttribute Subelement

- The MBeanNotification Subelement

- The MBeanConstructor Subelement

- The MBeanOperation Subelement

- Examples: Well-Formed and Valid MBean Definition Files (MDFs)

The MBeanType (Root) Element

All MDFs must contain exactly one root element called MBeanType, which has the following syntax:

<MBeanType Name= string optional_attributes>
subelements
</MBeanType>

The MBeanType element must include a Name attribute, which specifies the internal, programmatic name of the MBean type. (To specify a name that is visible in a user interface, use the DisplayName and LanguageMap attributes.) Other attributes are optional.

The following is a simplified example of an MBeanType (root) element:

>     <MBeanType Name="MyMBean" Package="com.mycompany">
>        <MBeanAttribute Name="MyAttr" Type="java.lang.String" Default="Hello World"/>
>     </MBeanType>

Attributes specified in the MBeanType (root) element apply to the entire set of MBeans instantiated from that MBean type. To override attributes for specific MBean instances, you need to specify attributes in the MBeanAttribute subelement. For more information, see The MBeanAttribute Subelement.

Table A-2 describes the attributes available to the MBeanType (root) element. The JMX Specification/BEA Extension column indicates whether the attribute is a BEA extension to the JMX specification or a standard JMX attribute. Note that BEA extensions might not function on other J2EE Web servers.

Table A-2 Attributes of the MBeanType (Root) Element

Attribute | JMX Specification /BEA Extension | Allowed Values | Description
--- | --- | --- | ---
Abstract | BEA Extension | true/false | A true value specifies that the MBean type cannot be instantiated (like any abstract Java class), though other MBean types can inherit its attributes and operations. If you specify true, you must create other non-abstract MBean types for carrying out management tasks. If you do not specify a value for this attribute, the assumed value is false.
CachingDisabled | BEA Extension | true/false | Ignored. This flag exists to support future functionality. For example, if caching is provided in the types-stubs, this flag may turn off that caching. Currently, MBeans created via the WebLogic MBeanMaker provide server-level caching as per the specification for JMX Model MBeans. Note: For more information on JMX Model MBeans, see the Java Management eXtensions 1.0 specification.
Classification | BEA Extension | String | A string that you can use to classify or group your MBean types, for example, to identify all MBean types that provide implementations of security authorization. There is no default or assumed value for this attribute.
CurrencyTimeLimit | JMX Specification | Integer | The number of seconds that any value cached is considered fresh. After this value expires, the next attempt to access the value triggers a recalculation. When specified in the MBeanType element, this value is considered the default for MBean types. It can be overridden for individual MBeans by setting the same attribute in the MBean's MBeanAttribute or MBeanOperation subelement.
Deprecated | BEA Extension | true/false | Indicates that the MBean type is deprecated. This information appears in the generated Java source, and is also placed in the ModelMBeanInfo object for possible use by a management application. If you do not specify this attribute, the assumed value is false.
Description | JMX Specification | String | An arbitrary string associated with the MBean type that appears in various locations, such as the Javadoc for generated classes. There is no default or assumed value. Note: To specify a description that is visible in a user interface, use the DisplayName, DisplayMessage, and PresentationString attributes.
DisplayMessage | JMX Specification | String | The message that a user interface displays to describe the MBean type. There is no default or assumed value. The DisplayMessage may be a paragraph used in Tool Tips or in Help. A DisplayMessage set for the MBean type is considered the default for MBean instances, unless a different value is specified for individual MBeans when the instance is created.
DisplayName | JMX Specification | String | The name that a user interface displays to identify instances of MBean types. For an instance of type X, the default DisplayName is "instance of type X." This value is typically overridden when instances are created. If you use the LanguageMap attribute, the DisplayName value is used as a key to find a name in the LanguageMap's resource bundle. If you do not specify the LanguageMap attribute, or if the key is not present in the resource bundle, the DisplayName value itself is displayed in the user interface. See also MessageID.
Export | JMX Specification | String | The WebLogic MBeanMaker does not use this attribute. However, to support applications that might use it, the WebLogic MBeanMaker adds the value to the MBeanInfo object. There is no default or assumed value. Note: For more information on the Export attribute, see the Java Management eXtensions 1.0 specification.
Extends | BEA Extension | Pathname | A fully qualified MBean type name that this MBean type extends. See also Implements.
GenerateExtended Accessors | BEA Extension | true/false | A true value enables all MBeanAttribute subelements whose Type is array to generate additional operations and interface methods to support indexed access. A false value prevents all MBeanAttribute subelements from generating additional operations and methods. If you do not specify this attribute, the assumed value is true.
Implements | BEA Extension | Comma- separated list | A comma-separated list of fully qualified MBean type names that this MBean type implements. See also Extends.
InstanceExtent | BEA Extension | true/false | A true value specifies that all instances of an MBean type should be retained in a list for faster and easier access. Setting this attribute to true, however, takes up more space. Note: By default, all security-related MBean types are set to true. If instances of those MBeans override this attribute, security may be adversely impacted.
LanguageMap | BEA Extension | String | Specifies a fully qualified pathname to a resource bundle that contains a map of displayable strings. Other attributes, such as DisplayMessage and DisplayName, use the strings in the LanguageMap to display information about the MBean type. If you do not specify this attribute, other attributes, such as DisplayMessage and DisplayName, display their own values (as opposed to using their values as a key to find appropriate strings in the resource bundle).
Listen | BEA Extension | true/false | Causes a stub for a notification listener to be generated in the MBean implementation object. If you do not specify this attribute, the assumed value is false. Note: For more information about listener stubs, see the Java Management eXtensions 1.0 specification.
Log | JMX Specification | true/false | A true value specifies that notifications for the MBean type are added to the log file. (The LogFile attribute specifies the file into which the information should be written.) If you do not specify this attribute, the assumed value is false, and notifications are not added to the log file. Note: For more information about MBean notifications and logs, see the Java Management eXtensions 1.0 specification.
LogFile | JMX Specification | Pathname | The fully qualified pathname of an existing, writable file into which messages are written when notifications occur for this MBean type. For logging to occur, the Log attribute must be set to true. There is no default or assumed value for this attribute. Note: For more information about MBean notifications and logs, see the Java Management eXtensions 1.0 specification.
MBeanClassName | BEA Extension | Pathname | A fully qualified classname that is a subclass of an MBean type BEA provides. This is included primarily for future development and for those wanting to extend Model MBeans. Note: For more information on JMX Model MBeans, see the Java Management eXtensions 1.0 specification.
MessageID | JMX Specification | String | Provides a key for retrieving a message from a client-side message repository per the Java Management eXtensions 1.0 specification. You can use MessageID, or DisplayMessage, or both to describe a notification MBean type. If you do not specify this attribute, no message ID is available. Note: MessageID does not use the same resource bundle that the LanguageMap attribute specifies, and it is available for notification MBean types only.
Name | JMX Specification | String | Mandatory attribute that specifies the internal, programmatic name of the MBean type.
Package | BEA Extension | String | Specifies the package name of the MBean type and determines the location of the class files that the WebLogic MBeanMaker creates. If you do not specify this attribute, the MBean type is placed in the Java default package. Note: MBean type names can be the same as long as the package name varies.
PersistLocation | JMX Specification | Pathname | The WebLogic MBeanMaker does not use this attribute. However, to support cases where an MBean type extends Model MBeans that do use PersistLocation, the WebLogic MBeanMaker adds the value to the MBeanInfo class. There is no default or assumed value. Note: For more information about PersistLocation and Model MBeans, see the Java Management eXtensions 1.0 specification.
PersistName | JMX Specification | String | The WebLogic MBeanMaker does not use this attribute. However, to support cases where an MBean type extends Model MBeans that do use PersistName, WebLogic MBeanMaker adds the value to the MBeanInfo class. There is no default or assumed value. Note: For more information about PersistName and Model MBeans, see the Java Management eXtensions 1.0 specification.
PersistPeriod | JMX Specification | Integer | Specifies the number of seconds that the OnTimer or NoMoreOftenThan persistence policies use. If you do not specify this attribute in the MBeanType or MBeanAttribute elements, the assumed value is 0. If PersistPolicy is set to OnTimer, then the attribute is persisted when the number of seconds expires. If PersistPolicy is set to NoMoreOftenThan, then persistence is constrained to happen not more often than the specified number seconds. Note: When specified in the MBeanType element, this value overrides any setting within an individual MBeanAttribute subelement.
PersistPolicy | JMX Specification | Never /OnTimer /OnUpdate /NoMoreOftenThan | Specifies how persistence will occur: Never. The attribute is never stored. This is useful for highly volatile data or data that only has meaning within the context of a session or execution period. OnTimer. The attribute is stored whenever the MBean type's persistence timer, as defined in the PersistPeriod attribute, expires. OnUpdate. The attribute is stored every time the attribute is updated. NoMoreOftenThan. The attribute is stored every time it is updated unless the updates are closer together than the PersistPeriod. This mechanism helps prevent temporarily highly volatile data from affecting performance. If you do not specify this attribute in the MBeanType or MBeanAttribute elements, the assumed value is Never. Note: When specified in the MBeanType element, this value overrides any setting within an individual MBeanAttribute subelement.
PresentationString | JMX Specification | Pathname | A fully qualified pathname to a single XML document that provides information that a user interface can use to display the item. The XML document provides additional metadata that is relevant to presentation logic. The format of the PresentationString is any XML/JMX-compliant information. Note: BEA does not currently define a specialized format, and recommends that customers wait before defining their own. The PresentationString attribute is for future use.
Readable | JMX Specification | true/false | Determines whether an MBean attribute's value can be read through the MBean API. If you do not specify this attribute in the MBeanType or MBeanAttribute elements, the assumed value is true. When specified in the MBeanType element, this value is considered the default for individual MBeanAttribute subelements.
Servers | BEA Extension | Comma- separated list | Defines the list of servers that can instantiate instances of an MBean type and the servers to which instances of the MBean type are visible. Instances of the MBean type are guaranteed to be accessible (for read access) from these servers even if the Administration Server is not available. The comma-separated list must specify names of servers that are in the same management domain as the MBean type. If no value is specified, the scope is assumed to be global, meaning that the instance is visible to all servers in the domain. If there is only one Managed Server in the list, the scope is server-specific, meaning that instances are only visible to the Managed Server and cannot be replicated to other servers. If an Administration Server and one or more Managed Servers are in the list, the scope is shared, meaning that the instance is visible to the Administration Server and the Managed Servers specified. Specifying more than one Managed Server without an Administration Server produces an error.
VersionID | BEA Extension | Long | Translates to the Java serialVersionUID. The provided values are placed directly into the generated implementation file in the following form: static final long serialVersionUID = <user provided ID>; Users who change an MBean class in an incompatible way will need to modify the serialVersionUID (using VersionID) to get Java serialization to work correctly. For more information about serialVersionUID, see the Java 2 Platform Standard Edition v1.3.1 API specification.
Visibility | JMX Specification | Integer: 1-4 | Denotes a level of importance for the MBean type. User interfaces use the number to determine whether they present the MBean type to a particular user in a particular context. The lower the value, the higher the level of importance. You can specify a number from 1 to 4. If you do not specify this attribute, the assumed value is 1. For items that have a high level of interest for users, provide a low Visibility number. For example, in the WebLogic Server Administration Console, MBeans with a Visiblity value of 1 are displayed in the left-pane navigation tree.
Writeable | JMX Specification | true/false | A true value allows the MBean API to set an MBeanAttribute's value. If you do not specify this attribute in MBeanType or MBeanAttribute, the assumed value is true. When specified in the MBeanType element, this value is considered the default for individual MBeanAttribute subelements.

The MBeanAttribute Subelement

You must supply one instance of an MBeanAttribute subelement for each attribute in your MBean type. The MBeanAttribute subelement must be formatted as follows:

<MBeanAttribute Name=string optional_attributes />

The MBeanAttribute subelement must include a Name attribute, which specifies the internal, programmatic name of the Java attribute in the MBean type. (To specify a name that is visible in a user interface, use the DisplayName and LanguageMap attributes.) Other attributes are optional.

The following is a simplified example of an MBeanAttribute subelement within an MBeanType element:

>     <MBeanType Name="MyMBean" Package="com.mycompany">
>         <MBeanAttribute Name= "WhenToCache"
>          Type="java.lang.String"
>          LegalValues="'cache-on-reference','cache-at-initialization','cache-never'"
>          Default= "cache-on-reference"
>         />
>     </MBeanType>

Attributes specified in an MBeanAttribute subelement apply to a specific MBean instance. To set attributes for the entire set of MBeans instantiated from an MBean type, you need to specify attributes in the MBeanType (root) element. For more information, see The MBeanType (Root) Element.

Table A-3 describes the attributes available to the MBeanAttribute subelement. The JMX Specification/BEA Extension column indicates whether the attribute is a BEA extension to the JMX specification. Note that BEA extensions might not function on other J2EE Web servers.

Table A-3 Attributes of the MBeanAttribute Subelement

Attribute | JMX Specification /BEA Extension | Allowed Values | Description
--- | --- | --- | ---
CachingDisabled | BEA Extension | true/false | Ignored. This flag exists to support future functionality. For example, if caching is provided in the types-stubs, this flag may turn off that caching. Currently, MBeans created via the WebLogic MBeanMaker provide server-level caching as per the specification for JMX Model MBeans. Note: For more information on JMX Model MBeans, see the Java Management eXtensions 1.0 specification.
CurrencyTimeLimit | JMX Specification | Integer | The number of seconds that any value cached is considered fresh. After this value expires, the next attempt to access the value triggers a recalculation. When specified in the MBeanType element, this value is considered the default for MBean types. It can be overridden for individual MBeans by setting the same attribute in the MBean's MBeanAttribute or MBeanOperation subelement.
Default | JMX Specification | String | The value to be returned if the MBeanAttribute subelement does not provide a getter method or a cached value. The string represents a Java expression that must evaluate to an object of a type that is compatible with the provided data type for this attribute. If you do not specify this attribute, the assumed value is null. If you use this assumed value, and if you set the LegalNull attribute to false, then an exception is thrown by WebLogic MBeanMaker and WebLogic Server.
DefaultString | JMX Specification | String | Same as Default, but can be used if the type of the attribute is String. If Default is used for a string attribute, the value must be enclosed in quotation marks. If DefaultString is used, the quotation marks should be omitted.
Deprecated | BEA Extension | true/false | Indicates that the MBean attribute is deprecated. This information appears in the generated Java source, and is also placed in the ModelMBeanInfo object for possible use by a management application. If you do not specify this attribute, the assumed value is false.
Description | JMX Specification | String | An arbitrary string associated with the MBean attribute that appears in various locations, such as the Javadoc for generated classes. There is no default or assumed value. Note: To specify a description that is visible in a user interface, use the DisplayName, DisplayMessage, and PresentationString attributes.
DisplayMessage | JMX Specification | String | The message that a user interface displays to describe the MBean attributes. There is no default or assumed value. The DisplayMessage may be a paragraph used in Tool Tips or in Help. A DisplayMessage set for the MBean type is considered the default for MBean instances, unless a different value is specified for individual MBeans when the instance is created.
DisplayName | JMX Specification | String | The name that a user interface displays to identify the instances of MBean types. The default value for DisplayName (from the MBean type) is typically overridden when instances are created. For an instance of type X, the default DisplayName is "instance of type X." If you use the LanguageMap attribute, the DisplayName value is used as a key to find a name in the LanguageMap's resource bundle. If you do not specify the LanguageMap attribute, or if the key is not present in the resource bundle, the DisplayName value itself is displayed in the user interface. See also MessageID.
Encrypted | BEA Extension | true/false | A true value indicates that this MBean attribute will be encrypted when it is set. If you do not specify this attribute, the assumed value is false.
Export | JMX Specification | String | The WebLogic MBeanMaker does not use this attribute. However, to support applications that might use it, WebLogic MBeanMaker adds the value to the MBeanInfo object. There is no default or assumed value. Note: For more information on the Export attribute, see the Java Management eXtensions 1.0 specification.
GenerateExtended Accessors | BEA Extension | true/false | A true value enables all MBean attributes whose Type is array to generate additional operations and interface methods to support indexed access. A false value prevents all MBeanAttribute subelements from generating additional operations and methods. If you do not specify this attribute, the assumed value is true.
GetMethod | JMX Specification | String | Overrides the MBean type's default attribute handling logic and provides the name of a getter method to be used for the current MBeanAttribute subelement. The value must correspond to the Name of an MBeanOperation subelement that defines a getter operation within the current MDF. If you do not specify this attribute, the MBean uses its default logic to retrieve the MBean attribute's value. Note: This attribute is affected by the Readable attribute: if Readable is false, then no getters are invoked for the current MBeanAttribute subelement.
InterfaceType | BEA Extension | String | Classname of an interface to be used instead of the MBean interface generated by the WebLogic MBeanMaker. Currently ignored but may be used for future extensibility.
IsIs | JMX Specification | true/false | Specifies whether a generated Java interface uses the JMX is<AttributeName> method to access the boolean value of the MBean attribute (as opposed to the get<AttributeName> method). If you do not specify this attribute, the assumed value is false.
Iterable | JMX Specification | true/false | For aggregate attribute types, indicates whether the attribute supports iteration (that is, whether it can increment its value each time it is accessed). If you do not specify this attribute, the assumed value is false. The WebLogic MBeanMaker does not use this attribute. However, to support applications that might use it, WebLogic MBeanMaker adds the value to the MBeanInfo class. Note: For more information on the Iterable attribute, see the Java Management eXtensions 1.0 specification.
LanguageMap | BEA Extension | String | Specifies a fully qualified pathname to a resource bundle that contains a map of displayable strings. Other attributes, such as DisplayMessage and DisplayName, use the strings in the LanguageMap to display information about the MBean attribute. If you do not specify this attribute, other attributes, such as DisplayMessage and DisplayName, display their own values (as opposed to using their values as a key to find appropriate strings in the resource bundle).
LegalNull | BEA Extension | true/false | Specifies whether null is an allowable value for the current MBeanAttribute subelement. If you do not specify this attribute, the assumed value is true.
LegalValues | BEA Extension | Comma- separated list | Specifies a fixed set of allowable values for the current MBeanAttribute subelement. If you do not specify this attribute, the MBean attribute allows any value of the type that is specified by the Type attribute. Note: The items in the list must be convertible to the data type that is specified by the subelement's Type attribute.
Listen | BEA Extension | true/false | Causes a stub for a notification listener to be generated in the MBean implementation object. If you do not specify this attribute, the assumed value is false. Note: For more information about listener stubs, see the Java Management eXtensions 1.0 specification.
Log | JMX Specification | true/false | A true value specifies that MBean notifications are added to the log file. (The LogFile attribute specifies the file into which the information should be written.) If you do not specify this attribute, the assumed value is false, and notifications are not added to the log file. Note: For more information about MBean notifications and logs, see the Java Management eXtensions 1.0 specification.
LogFile | JMX Specification | Pathname | The fully qualified pathname of an existing, writable file into which messages are written when notifications occur for this MBean attribute. For logging to occur, the Log attribute must be set to true. There is no default or assumed value for this attribute. Note: For more information about MBean notifications and logs, see the Java Management eXtensions 1.0 specification.
Max | BEA Extension | Integer | For numeric MBean attribute types only, provides a numeric value that represents the inclusive maximum value for the attribute. If you do not specify this attribute, the value can be as large as the data type allows. Note: If this maximum varies dynamically, varies based on context, or has a complex set of value ranges (for example, 1-10 or >100), use the Validator attribute instead.
MessageID | JMX Specification | String | Provides a key for retrieving a message from a client-side message repository per the Java Management eXtensions 1.0 specification. You can use MessageID, or DisplayMessage, or both to describe a notification MBean type. If you do not specify this attribute, no message ID is available. Note: MessageID does not use the same resource bundle that the LanguageMap attribute specifies, and it is available for notification MBean types only.
Min | BEA Extension | Integer | For numeric MBean attribute types only, provides a numeric value which represents the inclusive minimum value for the attribute. If you do not specify this attribute, the value can be as small as the data type allows. Note: If this minimum varies dynamically, varies based on context, or has a complex set of value ranges (for example, 1-10 or >100), use the Validator attribute instead.
Name | JMX Specification | String | Mandatory attribute that specifies the internal, programmatic name of the MBean attribute.
NoDump | BEA Extension | true/false | A true value prevents the MBean attribute from being dumped by the WebLogic MBeanDumper utility.
PersistLocation | JMX Specification | Pathname | The WebLogic MBeanMaker does not use this attribute. However, to support cases where an MBean extends Model MBeans that do use PersistLocation, the WebLogic MBeanMaker adds the value to the MBeanInfo class. There is no default or assumed value. Note: For more information about PersistLocation and Model MBeans, see tthe Java Management eXtensions 1.0 specification.
PersistName | JMX Specification | String | The WebLogic MBeanMaker does not use this attribute. However, to support cases where an MBean extends Model MBeans that do use PersistName, WebLogic MBeanMaker adds the value to the MBeanInfo class. There is no default or assumed value. Note: For more information about PersistName and Model MBeans, see the Java Management eXtensions 1.0 specification.
PersistPeriod | JMX Specification | Integer | Specifies the number of seconds that the OnTimer or NoMoreOftenThan persistence policies use. If you do not specify this attribute in the MBeanType or MBeanAttribute elements, the assumed value is 0. If PersistPolicy is set to OnTimer, then the attribute is persisted when the number of seconds expires. If PersistPolicy is set to NoMoreOftenThan, then persistence is constrained to happen not more often than the specified number seconds. Note: When specified in the MBeanType element, this value overrides any setting within an individual MBeanAttribute subelement.
PersistPolicy | JMX Specification | Never /OnTimer /OnUpdate /NoMoreOftenThan | Specifies how persistence will occur: Never. The attribute is never stored. This is useful for highly volatile data or data that only has meaning within the context of a session or execution period. OnTimer. The attribute is stored whenever the MBean attribute's persistence timer, as defined in the PersistPeriod attribute, expires. OnUpdate. The attribute is stored every time the attribute is updated. NoMoreOftenThan. The attribute is stored every time it is updated unless the updates are closer together than the PersistPeriod. This mechanism helps prevent temporarily highly volatile data from affecting performance. If you do not specify this attribute in the MBeanType or MBeanAttribute elements, the assumed value is Never. Note: When specified in the MBeanType element, this value overrides any setting within an individual MBeanAttribute subelement.
PresentationString | JMX Specification | Pathname | A fully qualified pathname to a single XML document that provides information that a user interface can use to display the item. The XML document provides additional metadata that is relevant to presentation logic. The format of the PresentationString is any XML/JMX-compliant information. Note: BEA does not currently define a specialized format, and recommends that customers wait before defining their own. The PresentationString attribute is for future use.
ProtocolMap | JMX Specification | Pathname | The Model MBean APIs allow mapping of the application's Model MBean attributes to existing management data models through the ProtocolMap field of the descriptor. The ProtocolMap field of an attribute's descriptor must contain a reference to an instance of a class that implements the Descriptor interface. Note: For more information about the ProtocolMap attribute and Model MBeans, see the Java Management eXtensions 1.0 specification.
Readable | JMX Specification | true/false | Determines whether the MBean attribute's value can be read through the MBean API. If you do not specify this attribute in the MBeanType or MBeanAttribute elements, the assumed value is true. When specified in the MBeanType element, this value is considered the default for individual MBeanAttribute subelements.
SetMethod | JMX Specification | String | Overrides the MBean type's default attribute handling logic and provides the name of a setter method to be used for the current MBeanAttribute subelement. The value must correspond to the Name of an MBeanOperation subelement that defines a setter operation within the current MDF. If you do not specify this attribute, the MBean uses its default logic to set the MBeanAttribute's value. Note: This attribute is affected by the Writeable attribute: if Writable is false, then no setters are invoked for the current MBeanAttribute subelement.
Type | JMX Specification | Java class name | The fully qualified classname of the data type of this attribute. This corresponding class must be available on the classpath. If you do not specify this attribute, the assumed value is java.lang.String.
Validator | BEA Extension | Java method name | The Validator attribute requires the name of a method that implements the validator logic. This method will be declared in the class generated by WebLogicMBeanMaker. If a specific validator is not provided, WebLogic Server does only basic checking to ensure type compatibility and, for numeric values, simple range checking (as specified in Min and Max). Instantiation and use of a validator is automatic and requires no additional action, beyond that of providing the validator name in the MBean Definition File (MDF) and the validator class on the classpath.
Visibility | JMX Specification | Integer: 1-4 | Denotes a level of importance for the MBean attribute. User interfaces use the number to determine whether they present the MBean attribute to a particular user in a particular context. The lower the value, the higher the level of importance. You can specify a number from 1 to 4. If you do not specify this attribute, the assumed value is 1. For items that have a high level of interest for users, provide a low Visibility number. For example, in the WebLogic Server Administration Console, MBeans with a Visiblity value of 1 are displayed in the left-pane navigation tree.
Writeable | JMX Specification | true/false | A true value allows the MBean API to set an MBeanAttribute's value. If you do not specify this attribute in MBeanType or MBeanAttribute, the assumed value is true. When specified in the MBeanType element, this value is considered the default for individual MBeanAttribute subelements.

The MBeanNotification Subelement

You must supply one instance of an MBeanNotification subelement for each type of notification (that is, broadcast of a management event) that your MBean type can issue. The MBeanNotification must be formatted as follows:

<MBeanNotification Name=string optional_attributes />

The MBeanNotification subelement must include a Name attribute, which specifies the internal, programmatic name of the Java notification, and a comma-separated list of NotificationTypes. (To specify a name that is visible in a user interface, use the DisplayName and LanguageMap attributes.) Other attributes are optional.

The following is a simplified example of an MBeanNotification subelement within an MBeanType element:

>     <MBeanType Name="MyMBean" Package="com.mycompany">
>        <MBeanNotification Name="com.mycompany.myNotification"
>         NotificationTypes="1.1.1.1.2.3.5" />
>     </MBeanType>

Table A-4 describes the attributes available to the MBeanNotification subelement. The JMX Specification/BEA Extension column indicates whether the attribute is a BEA extension to the JMX specification. Note that BEA extensions might not function on other J2EE Web servers.

Table A-4 Attributes of the MBeanNotification Subelement

Attribute | JMX Specification /BEA Extension | Allowed Values | Description
--- | --- | --- | ---
Classname | JMX Specification | String | The classname for the MBeanNotification, as defined by the Java Management eXtensions 1.0 specification. The default classname will work in most cases, but if desired, this attribute allows you to change it.
Deprecated | BEA Extension | true/false | Indicates that the MBean notification is deprecated. This information appears in the generated Java source, and is also placed in the ModelMBeanInfo object for possible use by a management application. If you do not specify this attribute, the assumed value is false.
Description | JMX Specification | String | An arbitrary string associated with the MBean notification type that appears in various locations, such as the Javadoc for generated classes. There is no default or assumed value. Note: To specify a description that is visible in a user interface, use the DisplayName, DisplayMessage, and PresentationString attributes.
DisplayMessage | BEA Extension | String | The message that a user interface displays to describe the MBean notification. There is no default or assumed value. The DisplayMessage may be a paragraph used in Tool Tips or in Help. A DisplayMessage set for the MBean type is considered the default for MBean instances, unless a different value is specified for individual MBeans when the instance is created.
DisplayName | JMX Specification | String | The name that a user interface displays to identify the MBean notification type. There is no default or assumed value. If you use the LanguageMap attribute, the DisplayName value is used as a key to find a name in the LanguageMap's resource bundle. If you do not specify the LanguageMap attribute, or if the key is not present in the resource bundle, the DisplayName value itself is displayed in user interfaces. See also MessageID.
LanguageMap | BEA Extension | String | Specifies a fully qualified pathname to a resource bundle that contains a map of displayable strings. Other attributes, such as DisplayMessage and DisplayName, use the strings in the LanguageMap to display information about the MBean notification. If you do not specify this attribute, other attributes, such as DisplayMessage and DisplayName, display their own values (as opposed to using their values as a key to find appropriate strings in the resource bundle).
Listen | BEA Extension | true/false | Causes a stub for a notification listener to be generated in the MBean implementation object. If you do not specify this attribute, the assumed value is false. Note: For more information about listener stubs, see the Java Management eXtensions 1.0 specification.
Log | JMX Specification | true/false | A true value specifies that MBean notifications are added to the log file. (The LogFile attribute specifies the file into which the information should be written.) If you do not specify this attribute, the assumed value is false, and notifications are not added to the log file. Note: For more information about MBean notifications and logs, see the Java Management eXtensions 1.0 specification.
LogFile | JMX Specification | Pathname | The fully qualified pathname of an existing, writable file into which messages are written when notifications occur for this MBean notification type. For logging to occur, the Log attribute must be set to true. There is no default or assumed value for this attribute. Note: For more information about MBean notifications and logs, see the Java Management eXtensions 1.0 specification.
MessageID | JMX Specification | String | Provides a key for retrieving a message from a client-side message repository per the Java Management eXtensions 1.0 specification. You can use MessageID, or DisplayMessage, or both to describe a notification MBean type. If you do not specify this attribute, no message ID is available. Note: MessageID does not use the same resource bundle that the LanguageMap attribute specifies and it is available for notification MBeans only.
Name | JMX Specification | String | Mandatory attribute that specifies the internal, programmatic name of the Java notification.
NotificationTypes | JMX Specification | Comma- separated list | The types of notifications that are the characterizations of generic notification objects.The list consists of any number of dot-separated components, separated by commas to allow an arbitrary, user-defined structure in the naming of notification types. Note: For more information about notification types, see the Java Management eXtensions 1.0 specification
PresentationString | JMX Specification | Pathname | A fully qualified pathname to a single XML document that provides information that a user interface can use to display the item. The XML document provides additional metadata that is relevant to presentation logic. The format of the PresentationString is any XML/JMX-compliant information. Note: BEA does not currently define a specialized format, and recommends that customers wait before defining their own. The PresentationString attribute is for future use.
Severity | JMX Specification | Integer or String | Indicates the severity of the notification. You must use one of the following values: 0 or unknown 1 or non-recoverable 2, critical, or failure 3, major, or severe 4, minor, marginal, or error 5 or warning 6, normal, cleared, or info The value of this tag can be either the number or any of the provided strings (case insensitive). If you use a string, the MBeanInfo object always converts it to the numerical equivalent and stores the numeric value. If you do not specify this attribute, the notification reports a severity of unknown.
Visibility | JMX Specification | Integer: 1-4 | Denotes a level of importance for the MBean notification. User interfaces use the number to determine whether they present the MBean notification to a particular user in a particular context. The lower the value, the higher the level of importance. You can specify a number from 1 to 4. If you do not specify this attribute, the assumed value is 1. For items that have a high level of interest for users, provide a low Visibility number. For example, in the WebLogic Server Administration Console, MBeans with a Visiblity value of 1 are displayed in the left-pane navigation tree.

The MBeanConstructor Subelement

MBeanConstructor subelements are not currently used by the WebLogic MBeanMaker, but are supported for compliance with the Java Management eXtensions 1.0 specification and upward compatibility. Therefore, attribute details for the MBeanConstructor subelement (and its associated MBeanConstructorArg subelement) are omitted from this documentation.

The MBeanOperation Subelement

You must supply one instance of an MBeanOperation subelement for each operation (method) that your MBean type supports. The MBeanOperation must be formatted as follows:

<MBeanOperation Name=string optional_attributes >
<MBeanOperationArg Name=string optional_attributes />
</MBeanOperation>

The MBeanOperation subelement must include a Name attribute, which specifies the internal, programmatic name of the operation. (To specify a name that is visible in a user interface, use the DisplayName and LanguageMap attributes.) Other attributes are optional.

Within the MBeanOperation element, you must supply one instance of an MBeanOperationArg subelement for each argument that your operation (method) uses. The MBeanOperationArg must be formatted as follows:

<MBeanOperationArg Name=string optional_attributes />

The Name attribute must specify the name of the operation. The only optional attribute for MBeanOperationArg is Type, which provides the Java class name that specifies behavior for a specific type of Java attribute. If you do not specify this attribute, the assumed value is java.lang.String.

The following is a simplified example of an MBeanOperation and MBeanOperationArg subelement within an MBeanType element:

>     <MBeanType Name="MyMBean" Package="com.mycompany">

>        <MBeanOperation
>         Name= "findParserSelectMBeanByKey"
>         ReturnType="XMLParserSelectRegistryEntryMBean"
>         Description="Given a public ID, system ID, or root element tag, returns the object name of the corresponding XMLParserSelectRegistryEntryMBean."
>        >
>           <MBeanOperationArg Name="publicID" Type="java.lang.String"/>
>           <MBeanOperationArg Name="systemID" Type="java.lang.String"/>
>           <MBeanOperationArg Name="rootTag" Type="java.lang.String"/>
>        </MBeanOperation>

>     </MBeanType>

Table A-5 describes the attributes available to the MBeanOperation subelement. The JMX Specification/BEA Extension column indicates whether the attribute is a BEA extension to the JMX specification. Note that BEA extensions might not function on other J2EE Web servers.

Table A-5 Attributes of the MBeanOperation Subelement

Attribute | JMX Specification /BEA Extension | Allowed Values | Description
--- | --- | --- | ---
CurrencyTimeLimit | JMX Specification | Integer | The number of seconds that any value cached is considered fresh. After this value expires, the next attempt to access the value triggers a recalculation. When specified in the MBeanType element, this value is considered the default for MBean types. It can be overridden for individual MBeans by setting the same attribute in the MBean's MBeanAttribute or MBeanOperation subelement.
Deprecated | BEA Extension | true/false | Indicates that the MBean operation is deprecated. This information appears in the generated Java source, and is also placed in the ModelMBeanInfo object for possible use by a management application. If you do not specify this attribute, the assumed value is false.
Description | JMX Specification | String | An arbitrary string associated with the MBean operation that appears in various locations, such as the Javadoc for generated classes. There is no default or assumed value. Note: To specify a description that is visible in a user interface, use the DisplayName, DisplayMessage, and PresentationString attributes.
DisplayMessage | BEA Extension | String | The message that a user interface displays to describe the MBean operation.There is no default or assumed value. The DisplayMessage may be a paragraph used in Tool Tips or in Help. A DisplayMessage set for the MBean type is considered the default for MBean instances, unless a different value is specified for individual MBeans when the instance is created.
DisplayName | JMX Specification | String | The name that a user interface displays to identify the MBean operation. There is no default or assumed value. If you use the LanguageMap attribute, the DisplayName value is used as a key to find a name in the LanguageMap's resource bundle. If you do not specify the LanguageMap attribute, or if the key is not present in the resource bundle, the DisplayName value itself is displayed in user interfaces. See also MessageID.
Impact | JMX Specification |  | The part of an MBean operation that communicates the impact the operation will have on the managed entity represented by the MBean. Note: For more information, see the Java Management eXtensions 1.0 specification
LanguageMap | BEA Extension | String | Specifies a fully qualified pathname to a resource bundle that contains a map of displayable strings. Other attributes, such as DisplayMessage and DisplayName, use the strings in the LanguageMap to display information about the MBean operation. If you do not specify this attribute, other attributes, such as DisplayMessage and DisplayName, display their own values (as opposed to using their values as a key to find appropriate strings in the resource bundle).
Listen | BEA Extension | true/false | Causes a stub for a notification listener to be generated in the MBean implementation object. If you do not specify this attribute, the assumed value is false. Note: For more information about listener stubs, see the Java Management eXtensions 1.0 specification.
MessageID | JMX Specification | String | Provides a key for retrieving a message from a client-side message repository per the Java Management eXtensions 1.0 specification. You can use MessageID, or DisplayMessage, or both to describe a notification MBean type. If you do not specify this attribute, no message ID is available. Note: MessageID does not use the same resource bundle that the LanguageMap attribute specifies and it is available for notification MBeans only.
Name | JMX Specification | String | Mandatory attribute that specifies the internal, programmatic name of the MBean operation.
PresentationString | JMX Specification | Pathname | A fully qualified pathname to a single XML document that provides information that a user interface can use to display the item. The XML document provides additional metadata that is relevant to presentation logic. The format of the PresentationString is any XML/JMX-compliant information. Note: BEA does not currently define a specialized format, and recommends that customers wait before defining their own. The PresentationString attribute is for future use.
ReturnType | JMX Specification | String | A string containing the fully qualified classname of the Java object returned by the operation being described.
ReturnTypeDescription | JMX Specification | String | A textual description of the Java object returned by the operation being described, which can be used in the Javadoc or a graphical user interface.
Visibility | JMX Specification | Integer: 1-4 | Denotes a level of importance for the MBean operation. User interfaces use the number to determine whether they present the MBean operation to a particular user in a particular context. The lower the value the higher the level of importance. You can specify a number from 1 to 4. If you do not specify this attribute, the assumed value is 1. For items that have a high level of interest for users, provide a low Visibility number. For example, in the WebLogic Server Administration Console, MBeans with a Visiblity value of 1 are displayed in the left-pane navigation tree.

Table A-6 describes the attributes available to the MBeanOperationArg subelement. The JMX Specification/BEA Extension column indicates whether the attribute is a BEA extension to the JMX specification. Note that BEA extensions might not function on other J2EE Web servers.

Table A-6 Attributes of the MBeanOperationArg Subelement

Attribute | JMX Specification /BEA Extension | Allowed Values | Description
--- | --- | --- | ---
Description | JMX Specification | String | An arbitrary string associated with the MBean operation argument that appears in various locations, such as the Javadoc for generated classes. There is no default or assumed value.
InterfaceType | BEA Extension | String | Classname of an interface to be used instead of the MBean interface generated by the WebLogic MBeanMaker. Currently ignored but may be used for future extensibility.
Name | JMX Specification | String | Mandatory attribute that specifies the name of the argument.
Type | JMX Specification | String | The type of the MBean operation argument. If you do not specify this attribute, the assumed value is java.lang.String.

Examples: Well-Formed and Valid MBean Definition Files (MDFs)

Listing A-1 and Listing A-2 provide examples of MBean Definition Files (MDFs) that use many of the attributes described in this Appendix. Listing A-1 shows the MDF used to generate an MBean type that manages predicates and reads data about predicates and their arguments. Listing A-2 shows the MDF used to generate the MBean type for the WebLogic (default) Authorization provider.

Listing A-1 PredicateEditor.xml

>     <?xml version="1.0" ?>
>     <!DOCTYPE MBeanType SYSTEM "commo.dtd">

>     <MBeanType
>      Name = "PredicateEditor"
>      Package = "weblogic.security.providers.authorization"
>      Implements = "weblogic.security.providers.authorization.PredicateReader"
>      PersistPolicy = "OnUpdate"
>      Abstract = "false"
>      Description = "This MBean manages predicates and reads data about predicates and their arguments.&lt;p&gt;"
>     >

>        <MBeanOperation
>         Name = "registerPredicate"
>         ReturnType = "void"
>         Description = "Registers a new predicate with the specified class name."
>        >

>          <MBeanOperationArg
>           Name = "predicateClassName"
>           Type = "java.lang.String"
>           Description = "The name of the Java class that implements the predicate."
>          />

>          <MBeanException>weblogic.management.utils.InvalidPredicateException</MBeanException>

>          <MBeanException>weblogic.management.utils.AlreadyExistsException</MBeanException>

>        </MBeanOperation>

>        <MBeanOperation
>         Name = "unregisterPredicate"
>         ReturnType = "void"
>         Description = "Unregisters the currently registered predicate."
>        >

>          <MBeanOperationArg
>           Name = "predicateClassName"
>           Type = "java.lang.String"
>           Description = "The name of the Java class that implements predicate to be unregistered."
>          />

>          <MBeanException>weblogic.management.utils.NotFoundException</MBeanException>

>        </MBeanOperation>

>     </MBeanType>

Listing A-2 DefaultAuthorizer.xml

>     <?xml version="1.0" ?>
>     <!DOCTYPE MBeanType SYSTEM "commo.dtd">

>     <MBeanType
>      Name = "DefaultAuthorizer"
>      DisplayName = "DefaultAuthorizer"
>      Package = "weblogic.security.providers.authorization"
>      Extends = "weblogic.management.security.authorization.DeployableAuthorizer"
>      Implements = "weblogic.management.security.authorization.PolicyEditor, weblogic.security.providers.authorization.PredicateEditor"
>      PersistPolicy = "OnUpdate"
>      Description = "This MBean represents configuration attributes for the WebLogic Authorization provider. &lt;p&gt;"
>     >

>        <MBeanAttribute
>         Name = "ProviderClassName"
>         Type = "java.lang.String"
>         Writeable = "false"
>         Default = "&quot;weblogic.security.providers.authorization.DefaultAuthorizationProviderImpl&quot;"
>         Description = "The name of the Java class used to load the WebLogic Authorization provider."
>        />

>        <MBeanAttribute
>         Name = "Description"
>         Type = "java.lang.String"
>         Writeable = "false"
>         Default = "&quot;Weblogic Default Authorization Provider&quot;"
>         Description = "A short description of the WebLogic Authorization provider."
>        />

>        <MBeanAttribute
>         Name = "Version"
>         Type = "java.lang.String"
>         Writeable = "false"
>         Default = "&quot;1.0&quot;"
>         Description = "The version of the WebLogic Authorization provider."
>        />

>     </MBeanType>