<?xml version="1.0" encoding="UTF-8"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE document [
  <!ENTITY project SYSTEM "project.xml">
]>
<document url="mbeans-descriptors-howto.html">

    &project;

    <properties>
        <author email="amyroh@apache.org">Amy Roh</author>
        <title>MBeans Descriptors How To</title>
    </properties>

<body>

<section name="Table of Contents">
<toc/>
</section>

<section name="Introduction">

<p>Tomcat uses JMX MBeans as the technology for implementing
manageability of Tomcat.</p>

<p>The descriptions of JMX MBeans for Catalina are in the mbeans-descriptors.xml
file in each package.</p>

<p>You will need to add MBean descriptions for your custom components
in order to avoid a "ManagedBean is not found" exception.</p>

</section>

<section name="Adding MBean descriptions">

<p>You may also add MBean descriptions for custom components in
a mbeans-descriptors.xml file, located in the same package as the class files
it describes.</p>

<p>The permitted syntax for the mbeans-descriptors.xml is defined by
the <a href="mbeans-descriptors.dtd">DTD</a> file.</p>

<p>The entries for a custom LDAP authentication Realm may look like this:</p>

<source><![CDATA[  <mbean         name="LDAPRealm"
            className="org.apache.catalina.mbeans.ClassNameMBean"
          description="Custom LDAPRealm"
               domain="Catalina"
                group="Realm"
                 type="com.myfirm.mypackage.LDAPRealm">

    <attribute   name="className"
          description="Fully qualified class name of the managed object"
                 type="java.lang.String"
            writeable="false"/>

    <attribute   name="debug"
          description="The debugging detail level for this component"
                 type="int"/>
    .
    .
    .

  </mbean>]]></source>


</section>

</body>

</document>