blob: 5e511bf09cd03d0f7d79b317c0aeded1d8542025 [file] [log] [blame]
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 1.11.1 at 2022-07-14
| Rendered using Apache Maven Fluido Skin 1.6
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="Date-Revision-yyyymmdd" content="20220714" />
<meta http-equiv="Content-Language" content="en" />
<title>Apache Axis2 &#x2013; Axis2 RPC Support</title>
<link rel="stylesheet" href="../css/apache-maven-fluido-1.6.min.css" />
<link rel="stylesheet" href="../css/site.css" />
<link rel="stylesheet" href="../css/print.css" media="print" />
<script type="text/javascript" src="../js/apache-maven-fluido-1.6.min.js"></script>
<meta name="generator" content="HTML Tidy for Windows (vers 14 June 2007), see www.w3.org" /><meta http-equiv="content-type" content="" /> </head>
<body class="topBarDisabled">
<div class="container-fluid">
<div id="banner">
<div class="pull-left"><a href="http://www.apache.org/" id="bannerLeft"><img src="http://www.apache.org/images/asf_logo_wide.png" alt="Apache Axis2"/></a></div>
<div class="pull-right"><a href=".././" id="bannerRight"><img src="../images/axis.jpg" /></a></div>
<div class="clear"><hr/></div>
</div>
<div id="breadcrumbs">
<ul class="breadcrumb">
<li id="publishDate">Last Published: 2022-07-14<span class="divider">|</span>
</li>
<li id="projectVersion">Version: 1.8.2<span class="divider">|</span></li>
<li class=""><a href="http://www.apache.org" class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li>
<li class=""><a href="../index.html" title="Axis2/Java">Axis2/Java</a><span class="divider">/</span></li>
<li class="active ">Axis2 RPC Support</li>
</ul>
</div>
<div class="row-fluid">
<div id="leftColumn" class="span2">
<div class="well sidebar-nav">
<ul class="nav nav-list">
<li class="nav-header">Axis2/Java</li>
<li><a href="../index.html" title="Home"><span class="none"></span>Home</a> </li>
<li><a href="../download.html" title="Downloads"><span class="none"></span>Downloads</a> </li>
<li><a href="javascript:void(0)" title="Release Notes"><span class="icon-chevron-down"></span>Release Notes</a>
<ul class="nav nav-list">
<li><a href="../release-notes/1.6.1.html" title="1.6.1"><span class="none"></span>1.6.1</a> </li>
<li><a href="../release-notes/1.6.2.html" title="1.6.2"><span class="none"></span>1.6.2</a> </li>
<li><a href="../release-notes/1.6.3.html" title="1.6.3"><span class="none"></span>1.6.3</a> </li>
<li><a href="../release-notes/1.6.4.html" title="1.6.4"><span class="none"></span>1.6.4</a> </li>
<li><a href="../release-notes/1.7.0.html" title="1.7.0"><span class="none"></span>1.7.0</a> </li>
<li><a href="../release-notes/1.7.1.html" title="1.7.1"><span class="none"></span>1.7.1</a> </li>
<li><a href="../release-notes/1.7.2.html" title="1.7.2"><span class="none"></span>1.7.2</a> </li>
<li><a href="../release-notes/1.7.3.html" title="1.7.3"><span class="none"></span>1.7.3</a> </li>
<li><a href="../release-notes/1.7.4.html" title="1.7.4"><span class="none"></span>1.7.4</a> </li>
<li><a href="../release-notes/1.7.5.html" title="1.7.5"><span class="none"></span>1.7.5</a> </li>
<li><a href="../release-notes/1.7.6.html" title="1.7.6"><span class="none"></span>1.7.6</a> </li>
<li><a href="../release-notes/1.7.7.html" title="1.7.7"><span class="none"></span>1.7.7</a> </li>
<li><a href="../release-notes/1.7.8.html" title="1.7.8"><span class="none"></span>1.7.8</a> </li>
<li><a href="../release-notes/1.7.9.html" title="1.7.9"><span class="none"></span>1.7.9</a> </li>
<li><a href="../release-notes/1.8.0.html" title="1.8.0"><span class="none"></span>1.8.0</a> </li>
</ul>
</li>
<li><a href="../modules/index.html" title="Modules"><span class="none"></span>Modules</a> </li>
<li><a href="../tools/index.html" title="Tools"><span class="none"></span>Tools</a> </li>
<li class="nav-header">Documentation</li>
<li><a href="../docs/toc.html" title="Table of Contents"><span class="none"></span>Table of Contents</a> </li>
<li><a href="../docs/installationguide.html" title="Installation Guide"><span class="none"></span>Installation Guide</a> </li>
<li><a href="../docs/quickstartguide.html" title="QuickStart Guide"><span class="none"></span>QuickStart Guide</a> </li>
<li><a href="../docs/userguide.html" title="User Guide"><span class="none"></span>User Guide</a> </li>
<li><a href="../docs/jaxws-guide.html" title="JAXWS Guide"><span class="none"></span>JAXWS Guide</a> </li>
<li><a href="../docs/pojoguide.html" title="POJO Guide"><span class="none"></span>POJO Guide</a> </li>
<li><a href="../docs/spring.html" title="Spring Guide"><span class="none"></span>Spring Guide</a> </li>
<li><a href="../docs/webadminguide.html" title="Web Administrator's Guide"><span class="none"></span>Web Administrator's Guide</a> </li>
<li><a href="../docs/migration.html" title="Migration Guide (from Axis1)"><span class="none"></span>Migration Guide (from Axis1)</a> </li>
<li class="nav-header">Resources</li>
<li><a href="../faq.html" title="FAQ"><span class="none"></span>FAQ</a> </li>
<li><a href="../articles.html" title="Articles"><span class="none"></span>Articles</a> </li>
<li><a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink" title="Wiki"><span class="none"></span>Wiki</a> </li>
<li><a href="../refLib.html" title="Reference Library"><span class="none"></span>Reference Library</a> </li>
<li><a href="../apidocs/index.html" title="Online Java Docs"><span class="none"></span>Online Java Docs</a> </li>
<li class="nav-header">Get Involved</li>
<li><a href="../overview.html" title="Overview"><span class="none"></span>Overview</a> </li>
<li><a href="../git.html" title="Checkout the Source"><span class="none"></span>Checkout the Source</a> </li>
<li><a href="../mail-lists.html" title="Mailing Lists"><span class="none"></span>Mailing Lists</a> </li>
<li><a href="../release-process.html" title="Release Process"><span class="none"></span>Release Process</a> </li>
<li><a href="../guidelines.html" title="Developer Guidelines"><span class="none"></span>Developer Guidelines</a> </li>
<li><a href="../siteHowTo.html" title="Build the Site"><span class="none"></span>Build the Site</a> </li>
<li class="nav-header">Project Information</li>
<li><a href="../team-list.html" title="Project Team"><span class="none"></span>Project Team</a> </li>
<li><a href="../issue-tracking.html" title="Issue Tracking"><span class="none"></span>Issue Tracking</a> </li>
<li><a href="http://svn.apache.org/viewvc/axis/axis2/java/core/trunk/" class="externalLink" title="Source Code"><span class="none"></span>Source Code</a> </li>
<li><a href="../thanks.html" title="Acknowledgements"><span class="none"></span>Acknowledgements</a> </li>
<li class="nav-header">Apache</li>
<li><a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink" title="License"><span class="none"></span>License</a> </li>
<li><a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship"><span class="none"></span>Sponsorship</a> </li>
<li><a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks"><span class="none"></span>Thanks</a> </li>
<li><a href="http://www.apache.org/security/" class="externalLink" title="Security"><span class="none"></span>Security</a> </li>
</ul>
<hr />
<div id="poweredBy">
<div class="clear"></div>
<div class="clear"></div>
<div class="clear"></div>
<div class="clear"></div>
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a>
</div>
</div>
</div>
<div id="bodyColumn" class="span10" >
<html xmlns="http://www.w3.org/1999/xhtml">
<h1>Axis2 RPC Support</h1>
<p>This document describes Axis2's Remote Procedure Call support in
a set of easy to understand implementation steps.</p>
<section>
<h2><a name="Introduction"></a>Introduction</h2>
<p>Axis2 Remote Procedure Call (RPC) support may seem somewhat
tricky and confusing at first glance. However, Axis2 RPC strategy
is based on a set of well defined rules. This document aims to
drill down to the details of the strategy and resolve most of the
unknown bits and pieces. Note that Axis2 currently does not support
the rpc/encoded style. But it fully supports the rpc/literal
style.</p>
<p>We will discuss the Axis2 RPC strategy in the following
steps</p>
<section>
<h2><a name="Step_1_-_Converting_RPC_Style_WSDL.27s_into_Doc.2FLit_Style.0AWSDL"></a>Step 1 - Converting RPC Style WSDL's into Doc/Lit Style
WSDL</h2>
<p>This is probably the most confusing part of the RPC strategy.
Since the Axis2 code generator is based on pure doc/lit style, the
first step of the code generation process is to generate a wrapper
schema. This wrapper generation can be easily explained by using an
example.</p>
<p>Take the following piece of WSDL</p>
<div>
<pre>
.....
&lt;message name=&quot;requestMessage&quot;&gt;
&lt;part name=&quot;part1&quot; type=&quot;xs:string&quot;/&gt;
&lt;part name=&quot;part2&quot; type=&quot;xs:int&quot;/&gt;
&lt;/message&gt;
&lt;message name=&quot;responseMessage&quot;&gt;
&lt;part name=&quot;part1&quot; type=&quot;xs:string&quot;/&gt;
&lt;/message&gt;
&lt;portType name=&quot;echoPortType&quot;&gt;
&lt;operation name=&quot;echo&quot;&gt;
&lt;input message=&quot;y:requestMessage&quot;/&gt;
&lt;output message=&quot;y:responseMessage&quot;/&gt;
&lt;/operation&gt;
&lt;/portType&gt;
&lt;binding name=&quot;echoBinding&quot; type=&quot;y:echoPortType&quot;&gt;
&lt;soap:binding style=&quot;rpc&quot; transport=&quot;http://schemas.xmlsoap.org/soap/http&quot;/&gt;
&lt;operation name=&quot;echo&quot;&gt;
&lt;soap:operation soapAction=&quot;echo&quot;/&gt;
&lt;input&gt;
&lt;soap:body use=&quot;literal&quot;/&gt;
&lt;/input&gt;
&lt;output&gt;
&lt;soap:body use=&quot;literal&quot;/&gt;
&lt;/output&gt;
&lt;/operation&gt;
&lt;/binding&gt;
.....
</pre></div>
<p>The binding says rpc/lit is required and in this case the
message parts will need wrapping in the following order:</p>
<ol style="list-style-type: decimal">
<li>The first element needs to have the operation name as the local
name and the operation namespace. (This happens to be the namespace
of the porttype - in this case the targetnamespace of the
WSDL.)</li>
<li>The children of this element are non namespace qualified
elements with the part names as local names (referred to as
<b>part element</b>)</li>
<li>In case the part refers to a standard type like the example
WSDL, the content of the part element would be of that type. If the
part refers to a complex type defined in the schema, the content of
the part element becomes of that type. Having an element reference
in the part when the binding is rpc is invalid.</li>
</ol>
<p>For example, the input wire message for the echo operation
mentioned in the above WSDL fragment would look like this:</p>
<div>
<pre>
&lt;op:<b>echo</b> xmlns:op=&quot;porttype namespace&quot;&gt;
&lt;<b>part1</b>&gt;Hello World&lt;/part1&gt;
&lt;<b>part2</b>&gt;123&lt;/part2&gt;
&lt;/op:echo&gt;
</pre></div>
<p>Note that the element name is in bold. The first one is the
operation name, the second and third are part names. It can be seen
that it is possible to generate a schema representing this
structure, and then treat the whole service as a pure doc/lit
service. In this case, the following piece of schema is generated
to make the rpc to doc conversion. Note that in this case the wire
message stays unchanged. It is only a different WSDL authoring
style</p>
<div>
<pre>
&lt;xs:element name=&quot;echo&quot;&gt;
&lt;xs:complexType&gt;
&lt;xs:sequence&gt;
&lt;xs:element name=&quot;part1&quot; type=&quot;xs:string&quot; /&gt;
&lt;xs:element name=&quot;part2&quot; type=&quot;xs:int&quot; /&gt;
&lt;/xs:sequence&gt;
&lt;/xs:complexType&gt;
&lt;/xs:element&gt;
</pre></div>
<p>What the Axis2 code generator does is exactly this. By looking
at the binding style, it generates a wrapper schema in places
required before handing over the Axis* hierarchy to the code
generator engine. In every case (even when the schema needs to be
unwrapped) this wrapping part will take place!</p>
<section>
<h2><a name="Step_2_-_Unwrapping_the_Schema"></a>Step 2 - Unwrapping the Schema</h2>
<p>If the schema needs to be unwrapped, it brings up a few issues.
This is mainly because the only thing that the emitters rely on
when generating code is a mapping table.</p>
<ol style="list-style-type: decimal">
<li>When the schema is unwrapped, where will the unwrapping
information remain?
<p>There has to be a store to keep the information seperated. The
Axis * hierarchy can be used for this. It has nicely separated
information holders and a parameter store that can hold an
information bean.</p>
</li>
<li>How do we maintain uniqueness among message part names?
<p>Part names are only unique across a message and not globally.
However, due to the fact that we have a global mapping table, we
need a way to differentiate between parts of different messages.
The technique used here is to generate a QName that has the
operation name as a namespace and a suffix (like _input) appended
to the local name.</p>
</li>
</ol>
<p>Given these solutions, the first step in unwrapping is to walk
the schema and figure out the unwrappable items. The key player of
the unwrapping process is the unwrapping extension. It walks a
given schema and figure out the unwrappable parts if there are
any.</p>
<p>The current unwrapper looks for the following patterns and fails
if it is not found!</p>
<div>
<pre>
&lt; element &gt;
&lt; complexType &gt;
&lt; sequence &gt;
&lt; element /&gt;
&lt; /sequence &gt;
&lt; /complexType &gt;
&lt; /element &gt;
</pre></div>
<p>Once this pattern is detected, the unwrapper details will be
added to the relevant AxisMessage component.</p>
<section>
<h2><a name="Step_3_-_Populate_Type_Information"></a>Step 3 - Populate Type Information</h2>
<p>The next step is to populate the Type information for the parts.
This has to be explicitly done by the data binding extensions, and
currently the ADB and XMLbeans extensions populate the relevant
AxisMessage by looking up their generated type systems. This type
information goes into the AxisMessage inside a
MessagePartInformationHolder instance.</p>
<p>The following code fragment from the ADB extension shows how the
AxisMessages get populated with the relevant type information. The
code is almost the same for the XMLBeans extension. Note the items
in bold.</p>
<div>
<pre>
if (message.getParameter(Constants.UNWRAPPED_KEY) != null) {
XmlSchemaType schemaType = message.getSchemaElement().getSchemaType();
if (schemaType instanceof XmlSchemaComplexType) {
XmlSchemaComplexType cmplxType = (XmlSchemaComplexType) schemaType;
XmlSchemaParticle particle = cmplxType.getParticle();
if (particle instanceof XmlSchemaSequence) {
XmlSchemaObjectCollection items =
((XmlSchemaSequence) particle).getItems();
for (Iterator i = items.getIterator(); i.hasNext();) {
Object item = i.next();
if (item instanceof XmlSchemaElement) {
XmlSchemaElement xmlSchemaElement = (XmlSchemaElement) item;
XmlSchemaType eltSchemaType = xmlSchemaElement.getSchemaType();
if (eltSchemaType != null) {
<b>populateClassName(eltSchemaType,mapper,opName,xmlSchemaElement.getName());</b>
} else if (xmlSchemaElement.getSchemaTypeName() != null) {
eltSchemaType = findSchemaType(schemaMap,
xmlSchemaElement.getSchemaTypeName());
if (eltSchemaType!=null){
populateClassName(eltSchemaType,mapper,opName,xmlSchemaElement.getName());
}
}
}
}
}
}
}
</pre></div>
<p>The populateClassName looks like this</p>
<div>
<pre>
private static void populateClassName(XmlSchemaType eltSchemaType,
TypeMapper typeMap,
String opName,
String partName) {
Map metaInfoMap = eltSchemaType.getMetaInfoMap();
if (metaInfoMap != null) {
<b>String className = (String) metaInfoMap.
get(SchemaConstants.SchemaCompilerInfoHolder.CLASSNAME_KEY);
QName partQName = WSDLUtil.getPartQName(opName,
WSDLConstants.INPUT_PART_QNAME_SUFFIX,
partName);
typeMap.addTypeMappingName(partQName,className);</b>
if (Boolean.TRUE.equals(
metaInfoMap.get(SchemaConstants.
SchemaCompilerInfoHolder.CLASSNAME_PRIMITVE_KEY))){
//this type is primitive - add that to the type mapper status
//for now lets add a boolean
typeMap.addTypeMappingStatus(partQName,Boolean.TRUE);
}
}
}
</pre></div>
<section>
<h2><a name="Step_4_-_Generate_Code_with_Unwrapped_Parameters"></a>Step 4 - Generate Code with Unwrapped Parameters</h2>
<p>The next step is generating the actual code. The
AxisServiceBasedMultiLanguageEmitter has a method that generates
the XML model for the input parameters, and that method includes
the relevant part parameters inside the relavant top level input
parameter element.</p>
<p>The relevant part of the XML model looks like this. Note that
this intermediate XML model is the one that is parsed against the
Stylesheets to generate the code.</p>
<div>
<pre>
&lt;input&gt;
&lt;param name=&quot;param4&quot; type=&quot;com.example.www.ServiceNameStub.Echo&quot; shorttype=&quot;Echo&quot; value=&quot;null&quot; location=&quot;body&quot; opname=&quot;echo&quot;&gt;
&lt;param name=&quot;param5&quot; type=&quot;java.lang.String&quot; shorttype=&quot;String&quot; value=&quot;null&quot; location=&quot;body&quot; opname=&quot;echo&quot; partname=&quot;Part1&quot;
primitive=&quot;yes&quot;/&gt;
&lt;param name=&quot;param6&quot; type=&quot;int&quot; shorttype=&quot;int&quot; value=&quot;0&quot; location=&quot;body&quot; opname=&quot;echo&quot; partname=&quot;Part2&quot; primitive=&quot;yes&quot;/&gt;
&lt;/param&gt;
&lt;/input&gt;
</pre></div>
<p>The next part is handled by the template. Basically, the
template looks after the generation of multiple parameters into the
method signatures, and then the generating of the relevant
serialization and deserialization code for the parameters.</p>
<section>
<h2><a name="Bringing_the_Parameters_Together_and_Exploding_Them"></a>Bringing the Parameters Together and Exploding Them</h2>
<p>This is a somewhat controversial area. The current Axis2 code
generator does the wrapping and unwrapping at the object level and
not the XML level. In short, the exploded parameters are only a
convenience and the explosion does not run down to the XML level.
The following example of generated source code makes this
clear:</p>
<div>
<pre>
private org.apache.axiom.soap.SOAPEnvelope toEnvelope(
org.apache.axiom.soap.SOAPFactory factory, java.lang.String param1,
int param2, boolean optimizeContent) {
<b>com.example.www.ServiceNameStub.Echo wrappedType = new com.example.www.ServiceNameStub.Echo();
wrappedType.setPart1(param1);
wrappedType.setPart2(param2);</b>
rg.apache.axiom.soap.SOAPEnvelope emptyEnvelope = factory.getDefaultEnvelope();
emptyEnvelope.getBody().addChild(wrappedType.getOMElement(
com.example.www.ServiceNameStub.Echo.MY_QNAME, factory));
return emptyEnvelope;
}
</pre></div>
<p>Note the lines in bold. The wrapped class will anyway be
instantiated and used at the end, but what the user sees is
different. Exploding the parameters happens in a similar way!</p>
<section>
<h2><a name="Conclusion"></a>Conclusion</h2>
<p>Axis2 RPC support is sort of a misty area, but it is based on a
well defined set of rules which makes it not <i>that</i> misty
after all!</p>
<hr />
</html>
</div>
</div>
</div>
<hr/>
<footer>
<div class="container-fluid">
<div class="row-fluid">
<p>Copyright &copy;2004&#x2013;2022
<a href="https://www.apache.org/">The Apache Software Foundation</a>.
All rights reserved.</p>
</div>
</div>
</footer>
</body>
</html>