axis-java-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ruchith Fernando <ruchith.ferna...@gmail.com>
Subject [Axis2] Configuring modules
Date Thu, 25 Aug 2005 14:28:04 GMT
Hi All,

In implementing the WSS4J module we discovered that currently we do
not have sufficient functionality to provide module configuration
parameters.

Following describes the problem and some proposals we came up with to
solve them:

Problem:
----------------------------------------------------------------------------------------------
Axis2 modules are self contained units that can be simply dropped into
an Axis2 repository and engaged.
Furthermore modules can be engaged 
	Globally
	Per service
	Per operation

Most of the time module authors will require the end user of the
module to configure the module by providing various configuration
information at the above different levels. And the module.xml can ONLY
be used for more concrete module configuration (by the module author)
since it comes in the archived .mar file.

As of now, Axis2 provides the concrete configuration information from
the module.xml to a module and its handlers. Therefore we will have to
use axis2.xml and service.xml to obtain module configuration parameter
that are to be set by the module user. But the information that is
available in the service.xml and axis2.xml are available via the
description hierarchy - figure - [1].

When a parameter is requested from the MessageContext the 'context'
hierarchy will be traversed to obtain the value if it exists. But we
still have not defined how to provide the module configuration
information via service.xml and axis2.xml where it has to traverse the
'description' hierarchy and they should be accessible by the module
author through the MessageContext.

Proposals:
================================================

* Qualify the module parameters names
-----------------------------------------------------------------------------------------------------------

This will remove any potential confusion of the module parameters in
the service.xml, axis2.xml and module.xml

* Enable axis2.xml and service.xml to provide config params as shown
in figure - [1]
-----------------------------------------------------------------------------------------------------------

Lets understand the BIG picture first: 
     Please have a look at -
http://people.apache.org/~ruchithf/module_config.png

Right hand side of the figure shows the layout of the parameters in
module.xml, axis2.xml and service.xml. Each scoped parameter group is
numbered and as follows:

module.xml - contains a set of global parameters that provides static
configuration for the module author - Parameter group 7
      These are loaded in to the ModuleDescription at the deployment time.
  
axis2.xml - contains a global parameter set that can include module
specific parameters and others - Parameter group 6
      These are loaded into the AxisConfiguration

axis2.xml - includes global module engagements and there we can define
the properties as well - Parameter group 5
      These should be loaded into the the AxisConfiguration in
relation to each module

service.xml - contains the general set of parameters common to the
service where we may have module related (may be shared) parameters -
Parameter group 4
      There are loaded into ServiceDescription

service.xml - contains the service specific module engagements and we
can have parameters in the scope of those modules as well - Parameter
group 5
      These should be loaded into ServiceDescription in relation to each module

service.xml - can also be used to engage modules with respect to
operations. Therefore with respect to operations we have two more
parameter groups as shows - Parameter group 2 and 1

When requested for a parameter then the lower parameter group
(starting from operation specific ones) will take precedence over the
higher ones.

* Finalize locking mechanism of the parameters
-----------------------------------------------------------------------------------------------------------

The above explained hierarchy of parameters overrides the upper level
ones. Therefore we also should provide a mechanism to be able to mark
a parameter 'final'. This can be done using the 'locked' attribute of
the parameter element.

For example is the module author marks a parameter as locked in the
module.xml that cannot be overridden at any point.

* Introduce two new methods getModuleParameter() and getParameter() to
MessageContext which will search the parameter collections at each
level of the description hierarchy.
-----------------------------------------------------------------------------------------------------------

	Note that MessageContext.getParameter() will not look in the module
parameter collections (1,3 and 5 in the figure) and
getModuleParameter() will traverse the whole thing to provide for the
parameters shared among modules.

* Parameter vales as OMElements
-----------------------------------------------------------------------------------------------------------

As of now (proposed)  getParameter() and getModuleParameter() methods
will return a org.apache.axis2.description.Parameter object.
If the parameter is read from either module.xml, axis2.xml or
service.xml then the Parameter.getValue() will return a
java.lang.String object.

But it'll be much more flexible for the module/service developers if
they can access the XML element describing the parameter as an
OMElement.

This mechanism will enable the developer to store much more than just
a String value in the parameter definition:
		<parameter name="mod1:policy" locked="false"
xmlns:mod1="http://my.module.org">
			<assersion id="foo"></assersion>
			<assersion id="bar"></assersion>
			<assersion id="foo_bar"></assersion>
		</parameter>

Also consider the following example:
<parameter name="Action" flow="in" locked="xsd:false">UsernameToken</parameter>
<parameter name="Action" flow="out" locked="xsd:false">UsernameToken</parameter>

this will allow setting additional parameter ATTRIBUTES that can be
used to specify the flow. [2]


Please raise any questions/comments you have on these proposals :-)

Thanks
-- 
Ruchith


[1] http://people.apache.org/~ruchithf/module_config.png
[2] http://marc.theaimsgroup.com/?l=axis-dev&m=112497401724093&w=2

Mime
View raw message