Version 9


    (or Yet Another Persistence Manager)




    JBoss ModelMBeans (XMBeans) can specify a PersistenceManager (PM) that is

    used during XMBean instantiation to load any attributes previously saved,

    and during normal operation to save attributes, based on the chosen Persistence



    The supplied ObjectStreamPersistenceManager uses serialization to files

    in order to persist and restore the XMBean state (infact, it saves the full

    XMBean metadata, including descriptors and everything).


    There are some problems with this setup:


    1. Lack of management interface - we cannot tell programmatically or otherwise

    (e.g. through the jmx-console) if some XMBean has been persisted. We cannot

    remove the persistent image unless we know how a particular persistence

    manager is implemented.

    1. We don't have central control over the configuration or lifecycle of a PM.

    If multiple instances use the same PM implementation (although a

    different instance of it), each could have different settings.

    1. It's not possible to apply the notion of "versions" of persistent data

    in a uniform way, in case we want to version a particular configuration.

    1. ObjectStreamPersistenceManager, in particular, that acts as a baseline PM

    doesn't not offer "visibility" over the persisted data.


    So, given the need for (a) persisting and managing MBean configuration changes,

    and (b) the possibility for supporting configuration versioning in jboss,

    we came up with the idea of an external MBean service called

    AttributePersistenceService (APS) that manages a new form of

    PersistenceManagers called AttributePersistenceManagers (APMs),

    offering a basic management interface.


    This facility along with an XML-based implementation of an APM

    is available from JBoss 3.2.6+ onwards, including JBoss 4.x.




    The classes and interfaces involved can be seen in the attached class diagram.



    A description of the new elements follows:



    This is an implementation of the usual PersistenceManager

    interface that hooks into the existing PM framework. The difference is that instead

    of providing a PM implementation, it contacts a factory method (by default: apmCreate())

    on an external MBean service (by default jboss:service=AttributePersistenceService)

    in order to get an implementation of the new AttributePersistenceManager

    (APM) interface. It will then use the load() and store() methods on this

    interface whenever called by the ModelMBeanInvoker.

    The DelegatingPersistenceManager also handles all details, like which

    attributes to persist, or how to load them back and it only leaves the actual

    loading and storing of an AttributeList to the APM implementation.



    This is a new interface for an enhanced, but probably simpler PM. To begin with,

    it has an explicit lifecycle interface, with a create() that accepts a

    versionTag and an XML Element containing arbitrary configuration information,

    and a destroy() that makes the APM unusable. An APM implementation must

    be thread-safe since it is shared by many DelegatingPersistenceManagers.

    The configuration is set only at the beginning of a session and it cannot change.

    If a versionTag is specified then the APM implementation must make sure that

    data stored/loaded under different version tags are partitioned.

    store() & load() operate on AttributeLists and like most other methods

    require an id to identify the persistent data image. The calling

    DelegatingPersistenceManager will pick the XMBean ObjectName as the default

    id. There are also methods to get all saved ids, check the existence of an

    image, remove it, or remove all persistent data.


    • (APS).

    This is a simple MBean service that instantiates and configures an

    AttributePersistenceManager implementation. The APM is then shared

    by all DelegatedPersistentManagers that request it. It also provides

    an entry point to the APM administrative interface (e.g. listAll(),

    remove(), etc.) This service is most probably started during JBoss

    boot time (i.e. from conf/jboss-service.xml) so that is present to

    all XMBeans that use it as an APM factory.

    The service may be stopped, re-configured and restarted to perform

    e.g. a versionTag change, presuming that a different JBoss configuration

    version is about to be used. The service is also persistent itself

    so that it's configuration changes may survive server restarts.



    This is an implementation of the AttributePersistenceManager interface

    and the default APM to be instantiated by the APS. It creates XML files

    whose format looks similar to that of the JBoss MBean deployment descriptor,

    so that the persited data is as visible as possible (could be partially

    edited by hand). The strategy for persisting attributes is the following:

      1. Null values will be marked as such.

      2. XML Element will be saved as XML.

      3. A PropertyEditor for converting to Text will be used, if available.

      4. If the value is Serializable and serialization is succesful it will

      be saved as a hex encoded string (ala CORBA IOR).

      1. If all fails, record an XML comment and log a warning.




    Provided the AttributePersistenceService is started (e.g. ./conf/jboss-service.xml)

    <!-- ==================================================================== -->
    <!-- XMBean Persistence                                                   -->
    <!-- ==================================================================== -->   
    <mbean code=""

    you may copy/paste to the ./deploy directory the example from

    docs/examples/jmx/persistent-service.sar that instantiates a persistent service

    with 10 different attribute types, using the name

    jboss.jmx:service=PersistentServiceExample. The jboss-service.xml descriptor

    of the said service contains inline the xmbean descriptor that specifies

    the DelegatingPersistenceManager:

          <persistence persistPolicy="OnUpdate"></persistence>
          <persistence-manager value=""></persistence-manager>

    Find the instantiated MBean jboss.jmx:service=PersistentServiceExample

    in the jmx-console, change an attribute (e.g. SomeInteger) and press

    on "Apply Changes". Going to the default location ./data/xmbean-attrs/

    you'll find the file jboss.jmx@3Aservice@3DPersistentServiceExample.xml

    whose content should be something close to:

    <?xml version="1.0" encoding="UTF-8"?>
    <!-- automatically produced by XMLAttributePersistenceManager -->
    <attribute-list date="20040824220829" id="jboss.jmx:service=PersistentServiceExample">
    <attribute name="SomeBigDecimal" type="java.math.BigDecimal">31400000000000000</attribute>
    <attribute name="SomeBoolean" type="java.lang.Boolean">true</attribute>
    <attribute name="SomeElement" type="org.w3c.dom.Element">
    <some-message>Welcome to the Athens 2004, Olympic Games!</some-message>
    <attribute name="SomeInt" type="java.lang.Integer">666</attribute>
    <attribute name="SomeInteger" type="java.lang.Integer">888</attribute>
    <attribute name="SomeString" type="java.lang.String">I've got the devil inside me</attribute>
    <attribute name="SomeTimestamp" serialized="true" type="java.sql.Timestamp">
    <attribute name="SomeNullObject" null="true"></attribute>

    Touch the service descriptor

    (./deploy/persistent-service.sar/META-INF/jboss-service.xml) and see how

    the re-deployed MBean retains/reloads the saved values.


    Going back to the jmx-console, locate the jboss:service=AttributePersistenceService

    and execute the apmListAllAsString() operation. You should get the id

    (ObjectName) of the persisted MBean. Copy the id and feed it to the

    apmRemove() operation. The persisted .xml file will be gone.


    Configuration Options


    The AttributePersistenceService has the following configurable attributes:

    <attribute name="AttributePersistenceManagerClass"></attribute>
    <attribute name="AttributePersistenceManagerConfig"></attribute>      
    <attribute name="ApmDestroyOnServiceStop">false</attribute>
    <attribute name="VersionTag"></attribute>


    • AttributePersistenceManagerClass can be used to specify an alternative APM

    implementation. The default is


    • AttributePersistenceManagerConfig is an XML Element that is passed to the APM to

    perform arbitrary configuration and will differ from APM to APM. For the

    default XMLAttributePersistenceManager it can be used to specify the

    directory to use for saving the .xml files, as follows:




    • ApmDestroyOnServiceStop is a boolean flag used to indicate whether destroy()

    should be called on the APM upon service stop. Doing so will render the APM

    unusable and every DelegatingPersistenceManager with a reference to this APM

    will get back an IllegalStateException if it tries to load/store data. This

    may be useful in cases we want to be sure no MBean is writing data, e.g.

    in case we want to alter the active configured version.



    • VersionTag by default it is null by it can take any value (e.g. "1.0"). The

    way a version is interpreted by an APM will be different. The default

    XMLAttributePersistenceManager will create/use a new subdirectory using the tag

    name (e.g. ./data/xmbean-attrs/1.0) to store/load its data. Thus, assuming we have

    a way to activate alternative deployment configuration, we can also alter the

    persistent images used, according to the active version by simply stopping,

    reconfiguring and restarting APS, dynamically. (This will instantiate a new APM.)

    Note also that APS is by default persistent itself (using the old

    ObjectStreamPersistenceManager) so any change, e.g. in the VersionTag

    will survive server restarts. The persistent image of APS is stored at



    XMBean Configuration


    Configurable options of interest on the XMBean descriptor of the MBeans to

    be persisted, are the following (MBean level):


    • persistName - can be used to specify a specific id, instead of the default



    • attribute-persistence-service - can be used to point to a different service name

    than the default jboss:service=AttributePersistenceService


    • attribute-persistence-operation - can be used to specify a different

    factory method on the target MBean service; the default is apmCreate


    Options on the XMBean attribute level:


    • For attributes that cannot be persisted, it may be useful to mark them with:

             <descriptor name="persistPolicy" value="Never"></descriptor>


    Known Issues


    All issues mentioned in the previous version of this page have been solved.




    Please forward any comments/suggestions/bug-reports to




    Referenced by: