(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:
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.
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.
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.
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.
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:
Null values will be marked as such.
XML Element will be saved as XML.
A PropertyEditor for converting to Text will be used, if available.
If the value is Serializable and serialization is succesful it will
be saved as a hex encoded string (ala CORBA IOR).
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="org.jboss.system.pm.AttributePersistenceService" name="jboss:service=AttributePersistenceService" xmbean-dd="resource:xmdesc/AttributePersistenceService-xmbean.xml"> </mbean> ...
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
<xmbean> <description>PersistentServiceExample</description> <descriptors> <persistence persistPolicy="OnUpdate"></persistence> <persistence-manager value="org.jboss.mx.persistence.DelegatingPersistenceManager"></persistence-manager> </descriptors> <class>org.jboss.jmx.examples.persistence.PersistentServiceExample</class> ...
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> <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"> ACED0005737200126A6176612E73716C2E54696D657374616D702618D5C80153BF6502000149000 56E616E6F737872000E6A6176612E7574696C2E44617465686A81014B5974190300007870770800 0000FE922D3F207808B3C880</attribute> <attribute name="SomeNullObject" null="true"></attribute> </attribute-list>
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.
The AttributePersistenceService has the following configurable attributes:
<attribute name="AttributePersistenceManagerClass">org.jboss.system.pm.XMLAttributePersistenceManager</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 org.jboss.system.pm.XMLAttributePersistenceManager
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
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:
<descriptors> <descriptor name="persistPolicy" value="Never"></descriptor> </descriptors>
All issues mentioned in the previous version of this page have been solved.
Please forward any comments/suggestions/bug-reports to firstname.lastname@example.org