Skip navigation.
Downloads | Product Documentation | Support

Developing Security Providers

# MBean Definition File Element Syntax

An MBean Definition File is an input file to the WebLogic MBeanMaker utility that uses the file to create an MBean type for managing a custom security provider. An MBean Definition File 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 available for use in a valid MBean Definition File:

- MBeanType Root Element
- MBeanAttribute Subelement
- Examples: Well-Formed and Valid MBean Definition Files

# MBeanType Root Element

An MBean Definition File must contain one root element called `MBeanType` that has the following syntax:

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

The `MBeanType` element must include a Name attribute that 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="&quot;Hello World&quot;"/>
>     </MBeanType>

Table A-1 describes the attributes you can use with the `MBeanType` root element.

Table A-1 MBeanType Root Element Attributes

Attribute | Allowed Values | Description
--- | --- | ---
`Abstract` | `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. If you specify `true`, you must create other non-abstract MBean types for carrying out configuration tasks. If you do not specify a value for this attribute, the assumed value is `false`.
`Deprecated` | `true`/`false` | Indicates that the MBean type is deprecated. This information appears in the generated Java source. If you do not specify this attribute, the assumed value is `false`.
`Description` | 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 and DisplayMessage attributes.
`DisplayMessage` | 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.
`DisplayName` | 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."
`Extends` | Pathname | A fully qualified MBean type name that this MBean type extends. See also Implements.
`Implements` | Comma- separated list | A comma-separated list of fully qualified MBean type names that this MBean type implements. See also Extends.
`Name` | String | Mandatory attribute that specifies the internal, programmatic name of the MBean type.
`Package` | 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: Two or more MBean type names can be the same as long as the package name varies.
`VersionID` | 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
`Writeable` | `true`/`false` | A `true` value allows the MBean API attributes to be set through the Administration Console. 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.

# 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= "&quot;cache-on-reference&quot;"
>         />
>     </MBeanType>

Table A-2 describes the attributes available to the `MBeanAttribute` subelement.

Table A-2 MBeanAttribute Subelement Attributes

Attribute | Allowed Values | Description
--- | --- | ---
`Default` | String | The default value of the `MBeanAttribute`. The value of this attribute is a Java expression that must evaluate to an object of a type that is compatible with the 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 the WebLogic MBeanMaker and WebLogic Server.
`DefaultString` | 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 (&quot; in the XML document). If `DefaultString` is used, the quotation marks should be omitted.
`Deprecated` | `true`/`false` | Indicates that the MBean attribute is deprecated. This information appears in the generated Java source. If you do not specify this attribute, the assumed value is `false`.
`Description` | 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 and DisplayMessage attributes.
`DisplayMessage` | String | The message that a user interface displays to describe the MBean attribute. There is no default or assumed value. The `DisplayMessage` may be a paragraph used in Tool Tips or in Help.
`DisplayName` | String | The name that a user interface displays to identify the MBean attribute.
`Encrypted` | `true`/`false` | A `true` value indicates that this MBean attribute is encrypted when it is set in the Administration Application. If you do not specify this attribute, the assumed value is `false`. A true value is the only valid value for single-valued attributes (that is, non- array types).
`IsIs` | `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` | `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` | 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 | String | The value of this attribute is limited to a single numeric primitive value represented as a string. 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 | String | The value of this attribute is limited to a single numeric primitive value represented as a string. 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` | String | Mandatory attribute that specifies the internal, programmatic name of the MBean attribute.
`Type` | Java class name | The fully qualified classname of the data type of this attribute. If you do not specify this attribute, the assumed value is `java.lang.String`. The value of this attribute is one of the following: `java.lang.String` `java.lang.String[]` `java.lang.Integer` `java.lang.Integer[]`
`Writeable` | `true`/`false` | A `true` value allows an `MBeanAttribute`'s value to be set in the Administration Application. 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.

# Examples: Well-Formed and Valid MBean Definition Files

Listing A-1 provides of an example of an MBean Definition File that uses many of the attributes described in this Appendix. It shows the used to generate the MBean type for a Sample Audit provider.

Listing A-1 SampleAuditor.xml

>     <?xml version="1.0" ?>

>     <!DOCTYPE MBeanType SYSTEM "commo.dtd">

>     <!-- MBean Definition File (MDF) for the Sample Auditor.

>          Copyright (c) 2003 by BEA Systems, Inc.  All Rights Reserved.

>     -->

>     <!-- Declare your mbean.

>          Since it is for an auditor, it must extend the

>          weblogic.management.security.audit.Auditor mbean.

>          The Name and DisplayName must be the same.

>          They specify the name that will appear on the

>          console for this provider.

>          Note that since this is an xml document, you can't use double

>          quotes directly.  Instead you need to use &quot;

>          Note that setting "Writeable" to "false" on an attribute

>          makes the attribute read-only.  The default is read-write.

>     -->

>     <MBeanType

>      Name          = "SampleAuditor"

>      DisplayName   = "SampleAuditor"

>      Package       = "examples.security.providers.audit"

>      Extends       = "weblogic.management.security.audit.Auditor"

>     >

>      <!-- You must set the value of the ProviderClassName attribute

>           (inherited from the weblogic.management.security.Provider mbean)

>           to the name of the java class you wrote that implements the

>           weblogic.security.spi.AuditProvider interface.

>           You can think of the provider's mbean as the factory

>           for your provider's runtime implementation.

>      -->

>      <MBeanAttribute

>       Name        = "ProviderClassName"

>       Type        = "java.lang.String"

>       Writeable   = "false"

>       Default     = "&quot;examples.security.providers.audit.SampleAuditProviderImpl&quot;"

>      />

>      <!-- You must set the value of the Description attribute

>           (inherited from the weblogic.management.security.Provider mbean)

>           to a brief description of your provider.

>           It is displayed in the console.

>      -->

>      <MBeanAttribute

>       Name        = "Description"

>       Type        = "java.lang.String"

>       Writeable   = "false"

>       Default     = "&quot;WLES Sample Audit Provider&quot;"

>      />

>      <!-- You must set the value of the Version attribute

>           (inherited from the weblogic.management.security.Provider mbean)

>           to your provider's version.  There is no required format.

>      -->

>      <MBeanAttribute

>       Name        = "Version"

>       Type        = "java.lang.String"

>       Writeable   = "false"

>       Default     = "&quot;1.0&quot;"

>      />

>      <!-- Add any custom attributes for your provider here.

>           The sample auditor adds a custom attribute named

>           LogFileName.  It contains the pathname of the

>           file that the sample auditor should write its

>           audit log to.

>           The sample auditor's runtime implementation

>           (SampleAuditProviderImpl) will read the value

>           of this attribute from its mbean.

>     -->

>      <MBeanAttribute

>       Name        = "LogFileName"

>       Type        = "java.lang.String"

>       Default     = "&quot;SampleAuditor.log&quot;"

>      />

>     </MBeanType>