Skip navigation.
Downloads | Product Documentation | Support

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

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`.
`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 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` | BEA Extension | Pathname | A fully qualified MBean type name that this MBean type extends.
`Implements` | BEA 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` | 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.
`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/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-2

Attribute | JMX Specification /BEA 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` | 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 attribute.
`Dynamic` | BEA 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` | 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`.
`InterfaceType` | BEA 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` | 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.
`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.
`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.
`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` j`ava.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 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/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

Attribute | JMX Specification /BEA Extension | Allowed Values | Description
--- | --- | --- | ---
`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 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/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

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.
`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 Listing 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)

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>