JAIN SLEE 1.1 introduced the Resource Adaptor API, including ConfigProperties as functionality to configure a Resource Adaptor, instead of the Env Entries concept used by SBBs and Profiles. This extension to the specification exposes the usage of ConfigProperties to SBBs and Profiles, main advantages are:
- normalization - the developer and admin use a single "API" regarding component configuration
- simplicity - does not uses JNDI, makes code simpler
- performance - most enterprise JNDI implementations are slow with respect to SLEE components performance requirements
- reconfiguration - through JMX it is possible to update the component configuration
Additionally the configuration means are added to Services, allowing it to redefine the default configuration for the SBBs it refers.
Note: the package for ConfigProperties class used by the extension is org.mobicents.slee, not javax.slee.resource from JAIN SLEE 1.1 RA API, but only the javadocs were updated.
Service Configuration
It is considered that different services may redefine an SBB configuration, thus the JAIN SLEE 1.1 Service XML descriptor DTD is extended to include a static way to do that:
- The element <service/> is redefined as <!ELEMENT service (description?, service-name, service-vendor, service-version, root-sbb, default-priority, address-profile-table?, service-configuration? )> , that is, a new <service-configuration/> element may optionally be added as <service/>'s last child.
- The <service-configuration/> element is defined as <!ELEMENT service-configuration (sbb-configuration*)>, that is, it may have a list of <sbb-configuration/> child elements.
- The <sbb-configuration/> element is defined as <!ELEMENT sbb-configuration (sbb-ref,config-property*)>, that is, it has a <sbb-ref/> child element followed by an optional list of <config-property/> child elements.
- The <sbb-ref/> element is defined as <!ELEMENT sbb-ref (description?, sbb-name, sbb-vendor, sbb-version)>, similar to the same named element in the Sbb XML Descriptor DTD, except it doesn't include the <sbb-alias/> child element.
- The <config-property/> element is defined as <!ELEMENT config-property (description?, config-property-name, config-property-type, config-property-value?)>, similar to the same named element in the Resource Adaptor 1.1 XML Descriptor DTD.
The Administrator may also desire to update a service configuration at runtime, and to provide such functionality it is proposed an extension to the standard javax.slee.management.ServiceManagentMBean, through the interface org.slee.management.ServiceManagentExtMBean. The extended MBean interface introduces 2 new JMX operations:
- public ConfigProperties getConfigurationProperties(ServiceID serviceID, SbbID sbbID) throws NullPointerException, UnrecognizedSbbException, UnrecognizedServiceException, ManagementException;
Retrieves the configuration properties, and their default values if any, for the specified Service's SBB.
- public void updateConfigurationProperties(ServiceID serviceID, SbbID sbbID, ConfigProperties properties) throws NullPointerException, UnrecognizedSbbException, UnrecognizedServiceException, InvalidConfigurationException, ManagementException;
Reconfigures a service with new configuration properties. Properties are specified using a <code>ConfigProperties</code> object.
Only properties that need updating need to be included in the org.mobicents.slee.ConfigProperties object.
The management client must ensure that all properties included in the ConfigProperties object have a non-null value before passing it to this method.
The org.mobicents.slee.SbbExt#sbbConfigurationUpdate(ConfigProperties) method is invoked on a SbbExt object to test validity of configuration.
An org.mobicents.slee.ServiceConfigurationUpdateEvent#org.mobicents.slee#1.1 event is fired in the Service's Activity Context, which may be used to apply some service logic.
SBB Configuration
The SBB Configuration is exposed through the interface org.mobicents.slee.SbbExt, which extends javax.slee.Sbb, introducing 4 new lifecyle methods, all related with ConfigProperties.
To support the introduction of ConfigProperties a new state is introduced, named Unconfigured, which stands between the standard Does Not Exists and Pooled states.
Unconfigured is reached from Does Not Exists after invocation of javax.slee.Sbb#setSbbContext(javax.slee.SbbContext), and after invocation of org.mobicents.slee.SbbExt#sbbConfigure(ConfigProperties) the Pooled state is reached.
In the reverse direction of the state machine, instead of moving from Pooled to Does Not Exists state, now it goes from Pooled to Unconfigured, upon invocation of org.mobicents.slee.SbbExt#sbbUnconfigure(), and upon invocation of javax.slee.Sbb#unsetSbbContext() the state goes to Does Not Exists again.
The new methods are:
- public void sbbConfigure(ConfigProperties properties);
The SLEE invokes this method on a SBB object in the Unconfigured state to provide it with configuration properties common for any SBB entity that uses the object.
- public void sbbUnconfigure();
The SLEE invokes this method on a SBB object in the Pooled state, indicating the transition to Unconfigured state.
The object should release any resources acquired when invocation of org.mobicents.slee.SbbExt#sbbConfigure(ConfigProperties) or org.mobicents.slee.SbbExt#sbbConfigurationUpdate(ConfigProperties).
- public void sbbVerifyConfiguration(ConfigProperties properties) throws InvalidConfigurationException;
This method is invoked by the SLEE whenever a new service, which refers the SBB, is activated by the Administrator, or when the Administrator attempts to update the configuration properties of an existing service which refers the SBB.
The implementation of this method should examine the configuration properties supplied and verify that the configuration properties are valid for the SBB.
This method may be invoked on a SBB object in any valid state, therefore the implementation of this method should assume nothing about the internal state of the SBB object.
- public void sbbConfigurationUpdate(ConfigProperties properties)
This method is invoked by the SLEE whenever the Administrator successfully updates a Service and SBB with new configuration properties.
The implementation of this method should apply the new configuration properties to its internal state.
In case of SbbExt object pooling, it is expected that the invocation of this method will only be done when an object is about to be used and its configuration is outdated.
Instead of requiring an update to SLEE 1.1 Sbb XML Descriptor DTD it is considered that the <env-entry/> XML element will be used for each config property.
Profile Configuration
The changes to Profile Configuration are similar to the ones promoted for Sbb. In concrete such features are exposed through the interface org.mobicents.slee.ProfileExt, which extends javax.slee.Profile, introducing 4 new lifecyle methods, all related with ConfigProperties.
To support the introduction of ConfigProperties a new state is introduced, named Unconfigured, which stands between the standard Does Not Exists and Pooled states.
Unconfigured is reached from Does Not Exists after invocation of javax.slee.Profile#setSbbContext(javax.slee.ProfileContext), and after invocation of org.mobicents.slee.ProfileExt#profileConfigure(ConfigProperties) the Pooled state is reached.
In the reverse direction of the state machine, instead of moving from Pooled to Does Not Exists state, now it goes from Pooled to Unconfigured, upon invocation of org.mobicents.slee.ProfileExt#profileUnconfigure(), and upon invocation of javax.slee.Profile#unsetProfileContext() the state goes to Does Not Exists again.
The new methods are:
- public void profileConfigure(ConfigProperties properties);
The SLEE invokes this method on a Profile object in the Unconfigured state to provide it with configuration properties common for any Profile entity that uses the object.
- public void profileUnconfigure();
The SLEE invokes this method on a Profile object in the Pooled state, indicating the transition to Unconfigured state.
The object should release any resources acquired when invocation of org.mobicents.slee.ProfileExt#profileConfigure(ConfigProperties) or org.mobicents.slee.ProfileExt#profileConfigurationUpdate(ConfigProperties).
- public void profileVerifyConfiguration(ConfigProperties properties) throws InvalidConfigurationException;
This method is invoked by the SLEE whenever a new Profile Spec, which refers the abstract Profile class, is activated by the Administrator, or when the Administrator attempts to update the configuration.
The implementation of this method should examine the configuration properties supplied and verify that the configuration properties are valid for the Profile.
This method may be invoked on a Profile object in any valid state, therefore the implementation of this method should assume nothing about the internal state of the Profile object.
- public void profileConfigurationUpdate(ConfigProperties properties)
This method is invoked by the SLEE whenever the Administrator successfully updates a Profile Spec with new configuration properties.
The implementation of this method should apply the new configuration properties to its internal state.
Instead of requiring an update to SLEE 1.1 Profile Specification XML Descriptor DTD it is considered that the <env-entry/> XML element will be used for each config property.
The standard javax.slee.management.ProfileProvisioningMBean is extended, through interface org.mobicents.slee.management.ProfileProvisioningExtMBean, to allow a Profile Specification reconfiguration during runtime, in a similar way as avax.slee.management.ServiceManagentMBean was extended, 2 new JMX operations are exposed:
- public ConfigProperties getConfigurationProperties(ProfileSpecificationID profileSpecificationID) throws NullPointerException, UnrecognizedProfileSpecificationException, ManagementException;
Retrieves the configuration properties, and their default values if any, for the specified Profile Specification.
- public void updateConfigurationProperties(ProfileSpecificationID profileSpecificationID, ConfigProperties properties) throws NullPointerException, UnrecognizedProfileSpecificationException, InvalidConfigurationException, ManagementException;
Reconfigures a Profile Specification with new configuration properties. Properties are specified using a <code>ConfigProperties</code> object.
Only properties that need updating need to be included in the org.mobicents.slee.ConfigProperties object.
The management client must ensure that all properties included in the ConfigProperties object have a non-null value before passing it to this method.
The org.mobicents.slee.ProfileExt#profileConfigurationUpdate(ConfigProperties) method is invoked on a ProfileExt object to test validity of configuration.
Discussion topics
- Should the Sbb and Profile XML Descriptor DTDs also be updated with new <config-property/> elements, instead of reusing the existent <env-entry/> elements?
Comments