A 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

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 attribute.) 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-1 describes the attributes available to the MBeanType (root) element. The JMX Specification/Oracle Extension column indicates whether the attribute is an Oracle extension to the JMX specification or a standard JMX attribute. Note that Oracle extensions might not function on other Java EE Web servers.

Table A-1 MBeanType (Root) Element Attributes

Attribute JMX Specification/Oracle Extension Allowed Values Description

Abstract

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

Deprecated

Oracle 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 attribute.

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.

Extends

Oracle Extension

Pathname

A fully qualified MBean type name that this MBean type extends.

Implements

Oracle Extension

Comma-

separated list

A comma-separated list of fully qualified MBean type names that this MBean type implements.

See also Extends.

Name

JMX Specification

String

Mandatory attribute that specifies the internal, programmatic name of the MBean type.

Package

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

PersistPolicy

JMX Specification

/OnUpdate

Specifies how persistence will occur:

OnUpdate. The attribute is stored every time the attribute is updated.

Note: When specified in the MBeanType element, this value overrides any setting within an individual MBeanAttribute subelement.

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 attribute.) 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-2 describes the attributes available to the MBeanAttribute subelement. The JMX Specification/Oracle Extension column indicates whether the attribute is an Oracle extension to the JMX specification. Note that Oracle extensions might not function on other Java EE Web servers.

Table A-2 MBeanAttribute Subelement Attributes

Attribute JMX Specification/Oracle Extension Allowed Values Description

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.

Deprecated

Oracle 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 attribute.

Dynamic

Oracle Extension

true/false

Changes made to dynamic MBeans take effect without rebooting the server. By default, all custom security provider MBean attributes are non-dynamic.

Note that in 8.1 and 7.0, all custom security provider MBean attributes were dynamic.

Encrypted

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

InterfaceType

Oracle Extension

String

Classname of an interface to be used instead of the MBean interface generated by the WebLogic MBeanMaker. InterfaceType can be

  • int

  • long

  • float

  • double

  • char

  • byte

Do not specify if "Type" is java.lang.String, java.lang.String[], or java.lang.Properties.

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.

LegalNull

Oracle 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

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

Max

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

Min

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

Name

JMX Specification

String

Mandatory attribute that specifies the internal, programmatic name of the MBean attribute.

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. Type can be

  • java.lang.Integer

  • java.lang.Integer[]

  • java.lang.Long

  • java.lang.Long[]

  • java.lang.Float

  • java.lang.Float[]

  • java.lang.Double

  • java.lang.Double[]

  • java.lang.Char

  • java.lang.Char[]

  • java.lang.Byte

  • java.lang.Byte[]

  • java.lang.String

  • java.lang.String[]

  • java.util.Properties

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 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 (http://jcp.org/aboutJava/communityprocess/final/jsr003/index.html) 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 attribute.) 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-3 describes the attributes available to the MBeanOperation subelement. The JMX Specification/Oracle Extension column indicates whether the attribute is an Oracle extension to the JMX specification. Note that Oracle extensions might not function on other Java EE Web servers.

Table A-3 MBeanOperation Subelement Attributes

Attribute JMX Specification/Oracle Extension Allowed Values Description

Deprecated

Oracle 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 attribute.

Name

JMX Specification

String

Mandatory attribute that specifies the internal, programmatic name of the MBean operation.

ReturnType

JMX Specification

String

A string containing the fully qualified classname of the Java object returned by the operation being described. ReturnType can be void or the following:

  • int

  • int[]

  • long

  • long[]

  • float

  • float[]

  • double

  • double[]

  • char

  • char[]

  • byte

  • byte[]

  • java.lang.String

  • java.lang.String[]

  • java.util.Properties

Table A-4 describes the attributes available to the MBeanOperationArg subelement. The JMX Specification/Oracle Extension column indicates whether the attribute is an Oracle extension to the JMX specification. Note that Oracle extensions might not function on other Java EE Web servers.

Table A-4 MBeanOperationArg Subelement Attributes

Attribute JMX Specification/Oracle 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.

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. Type can be

  • int

  • int[]

  • long

  • long[]

  • float

  • float[]

  • double

  • double[]

  • char

  • char[]

  • byte

  • byte[]

  • java.lang.String

  • java.lang.String[]

  • java.util.Properties

MBean Operation Exceptions

Your MBean Definition Files (MDFs) must use only JDK exception types or weblogic.management.utils exception types. The following is a code fragment from Example A-1 that shows the use of an MBeanException within an MBeanOperation subelement:

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

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

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

Example 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>

Example 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>