Developing Security Providers

MBean Definition File 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/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.

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.

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

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.

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

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