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

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