whitlock 2003/02/25 06:29:57
Modified: forrest-src/src/documentation/content/xdocs/providers/wsdl_extensions
ejb_extension.xml jms_extension.xml
java_extension.xml book.xml
forrest-src/src/documentation/content/xdocs/providers
book.xml
Added: forrest-src/src/documentation/content/xdocs/providers/wsdl_extensions
formattypemapping_extension.xml
Log:
Improve JMS WSDL extensions documentation
Revision Changes Path
1.2 +2 -26
xml-axis-wsif/forrest-src/src/documentation/content/xdocs/providers/wsdl_extensions/ejb_extension.xml
Index: ejb_extension.xml
===================================================================
RCS file:
/home/cvs/xml-axis-wsif/forrest-src/src/documentation/content/xdocs/providers/wsdl_extensions/ejb_extension.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- ejb_extension.xml 31 Jan 2003 13:06:42 -0000 1.1
+++ ejb_extension.xml 25 Feb 2003 14:29:57 -0000 1.2
@@ -53,32 +53,8 @@
This indicates that the binding is an EJB binding.</li>
<li><strong><code>format:typemapping</code></strong>
-This element allows the specification of a mapping from abstract types used in WSDL
message parts (within the abstract service description)
-to java types that can represent the same information. The style attribute is used
to say something about the target type system (i.e. the
-native type system being used to represent the abstract information); in the case
of the java type system the value here must be "Java".
-This use of this attribute allows this extension to be reused for other kinds of
bindings. The encoding attribute must be a URI which is
-used to denote the specific way in which the native type corresponds to the
abstract type. We define a special encoding, the "Java" encoding,
-with the rules that tell us how to create a java class corresponding to an abstract
schema type that can be used through the WSDL java binding.
-Details on the "Java" encoding follow. Having the encoding attribute allows us to
map abstract types to java types in other convenient ways
-by using a customized encoding.
-<br /><br />
-<strong>Java encoding</strong><br />
-The java encoding used by WSIF is unspecified. The reason it does not need to be
specified is that encoding information is useful only when
-the information contained within the java object is transformed in some way -
serialized to a SOAP message, or converted to a representation
-in another type system for example. If all we do with a WSIF message containing
parts belonging to the java type system is invoke the
-corresponding java service, we don't need to do anything more than verify that each
message part is is represented using a java object
-of the correct type (as specified by the typemapping element in the java
binding).<br /><br />
-Of course, we envisage the need for transforming messages from one representation
to another, but we leave the complete specification of
-the java encoding for a later release.
-</li>
-<li>
-<strong><code>format:typemap</code></strong>
-Each typemap element maps an abstract type to a type in some more convenient type
system; in the case of the EJB binding this is the java
-type system. The typeName attribute is a qualified name for the abstract type being
mapped (this must be one of the predefined schema types
-recognised in WSDL, or a type defined under the <types> section in the WSDL).
The elementName attribute may be used to specify an element
-instead of a type (since WSDL message parts can be described either way). The
formatType attribute is the java type corresponding to that
-abstract type or element. It values must be one of the primitive java types (char,
byte, short, int, long, float, double) or the fully
-qualified name of a java class.</li>
+For information about the format:typeMapping and format:typeMap please see
+<link href="formattypemapping_extension.html">Format Type Mapping</link>.</li>
<li><strong><code>ejb:operation</code></strong>
This element maps an abstract WSDL operation to a method offered by an EJB
interface. The <em>methodName</em> attribute specifies the name of
1.2 +83 -6
xml-axis-wsif/forrest-src/src/documentation/content/xdocs/providers/wsdl_extensions/jms_extension.xml
Index: jms_extension.xml
===================================================================
RCS file:
/home/cvs/xml-axis-wsif/forrest-src/src/documentation/content/xdocs/providers/wsdl_extensions/jms_extension.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- jms_extension.xml 31 Jan 2003 13:06:43 -0000 1.1
+++ jms_extension.xml 25 Feb 2003 14:29:57 -0000 1.2
@@ -34,7 +34,7 @@
jmsImplementationSpecificURI="xxx" />
</source>
<ul>
-<li>this must go in the port</li>
+<li>there must be exactly one jms:address in the port instead of the
soap:address</li>
<li>jmsVendorURI is optional and unused by WSIF. It allows to the client
to check the JMS implementation.</li>
<li>either destinationStyle or jmsImplementationSpecificURI must be
@@ -58,6 +58,8 @@
that WSIF will use.</li>
<li>if destinationStyle is specified then either both jndiProviderURL and
initialContextFactory or neither must be specified.</li>
+<li>jndiProviderURL and initialContextFactory specify which JNDI database to
+use. If they are not present, WSIF uses the default JNDI.</li>
</ul>
<p>
WSIF uses the following order to lookup queues and queue managers in JNDI</p>
@@ -74,7 +76,28 @@
</section>
<section><title>Jms binding</title>
<p>
-TODO
+The Jms binding is used to bind Native Jms.
+</p>
+<source>
+<binding name="xxx" type="xxx">
+ <jms:binding type="ObjectMessage"/>
+ <format:typeMapping encoding="Java" style="Java">
+ <format:typeMap typeName="xxx" formatType="xxx" />
+ </format:typeMapping>
+ <operation name="xxx">
+ <input name="xxx" />
+ <output name="xxx" />
+ </operation>
+</binding>
+</source>
+<p>
+For information about the format:typeMapping and format:typeMap please see
+<link href="formattypemapping_extension.html">Format Type Mapping</link>.
+</p>
+<p>
+The jms:binding specifies that this binding is for Native Jms. The type is the
+type of the JMS message that will be sent. Currently only object messages
+are supported.
</p>
</section>
<section><title>Jms property</title>
@@ -82,7 +105,7 @@
<jms:property name="<name>" part="<part>" />
</source>
<ul>
-<li>this must go in the input or output section of the binding operation.
+<li>this must go in the input, output or fault section of the binding operation.
Output jms properties are not yet implemented in WSIF.</li>
<li>the <name> may be the name of a property defined by JMS, or
the name of a property defined by the JMS implementation, or the name of
@@ -117,8 +140,62 @@
</section>
<section><title>Jms fault, fault property and fault indicator</title>
<p>
-TODO
+The JMS fault, fault property and fault indicator tags are WSDL extensions
+that describe the Native JMS binding for a fault message. These tags appear
+in the fault message of a JMS binding operation. These faults are problems
+that the backend web service wishes to report to the client. In Native JMS
+these are mapped to either body parts or JMS properties. There is a JMS
+property that is the fault indicator. If this fault indicator is set, this
+message describes a fault, not an output message. The fault indicator also
+shows which fault occurred.
</p>
+<source>
+<binding name="xxx" type="xxx">
+ <jms:binding type="ObjectMessage"/>
+ <format:typeMapping encoding="Java" style="Java" />
+ <operation name="xxx">
+ <input name="xxx" />
+ <output name="xxx" />
+ <fault name="xxx">
+ <jms:faultIndicator type="property">
+ <jms:faultProperty
+ name="xxx"
+ type="xxx"
+ value="xxx"
+ part="xxx"/>
+ </jms:faultIndicator>
+ <jms:fault parts="a b c"/>
+ <jms:property
+ name="xxx"
+ type="xxx"
+ part="xxx"/>
+ </fault>
+ </operation>
+</binding>
+</source>
+<ul>
+<li>There can be multiple fault messages for a particular operation. Each fault
+message describes a different fault that this operation can return.</li>
+<li>The <jms:faultIndicator tag describes how to recognise this fault message.
+The type of the faultIndicator must be set to property which means that this
+faultIndicator is described by a JMS property. Other faultIndicator types may be
+supported in the future. WSIF currently supports each fault message having
+exactly one jms:faultIndicator.</li>
+<li>The <jms:faultProperty tag appears in the <jms:faultIndicator, if the
+faultIndicator type is property (which is the only value allowed currently).
+The jms:faultProperty describes the JMS property that indicates that this
+message is a fault. The faultProperty name is the name of the JMS property. The
+type is the type of the JMS property, which must also match the type of the message
+part that this faultProperty maps to. Also the value must be able to be
+converted into this type. The value is the value that the JMS property must
+be set to, if the message describes this fault. The part is the message part
+that maps to this faultProperty. The name, type and value are mandatory, whereas
+the part is optional. There cannot be two fault messages for the same operation
+that have the same faultProperty name and value.</li>
+<li>The <jms:fault tag describes which message parts will be set for this
+fault. The parts is a space separated list of message parts.</li>
+<li>For a description of the <jms:property tag, please see above.</li>
+</ul>
</section>
- </body>
- </document>
+</body>
+</document>
1.2 +3 -23
xml-axis-wsif/forrest-src/src/documentation/content/xdocs/providers/wsdl_extensions/java_extension.xml
Index: java_extension.xml
===================================================================
RCS file:
/home/cvs/xml-axis-wsif/forrest-src/src/documentation/content/xdocs/providers/wsdl_extensions/java_extension.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- java_extension.xml 31 Jan 2003 13:06:43 -0000 1.1
+++ java_extension.xml 25 Feb 2003 14:29:57 -0000 1.2
@@ -49,29 +49,9 @@
<ul>
<li><strong><code>java:binding</code></strong> This indicates that the binding is a
Java binding.</li>
-<li><strong><code>format:typeMapping</code></strong> This element allows the
specification of a mapping from abstract types used in
-WSDL message parts (within the abstract service description) to Java types that can
represent the same information. The style attribute
-is used to say something about the target type system (i.e. the native type system
being used to represent the abstract information); in
-the case of the Java type system the value here must be "Java". The use of this
attribute allows this extension to be reused for other
-kinds of bindings. The encoding attribute must be a URI which is used to denote the
specific way in which the native type corresponds to
-the abstract type. We define a special encoding, the "Java" encoding, with the
rules that tell us how to create a Java class corresponding
-to an abstract schema type that can be used through the WSDL Java binding. Details
on the "Java" encoding follow. Having the encoding
-attribute allows us to map abstract types to Java types in other convenient ways by
using a customized encoding.
-<br /><br />
-<strong>Java encoding</strong><br />
-The Java encoding used by WSIF is unspecified. The reason it does not need to be
specified is that encoding information is useful only when the
-information contained within the Java object is transformed in some way -
serialized to a SOAP message, or converted to a representation in
-another type system for example. If all we do with a WSIF message containing parts
belonging to the Java type system is invoke the corresponding
-Java service, we don't need to do anything more than verify that each message part
is represented using a Java object of the correct type (as specified
-by the typemapping element in the Java binding).<br />
-Of course, we envisage the need for transforming messages from one representation
to another, but we leave the complete specification of the Java encoding for a later
release.</li>
-
-<li><strong><code>format:typemap</code></strong>
-Each typemap element maps an abstract type to a type in some more convenient type
system; in the case of the Java binding this is the Java type system.
-The typeName attribute is a qualified name for the abstract type being mapped (this
must be one of the predefined schema types recognised in WSDL, or a type defined
-under the <types> section in the WSDL). The elementName attribute may be used
to specify an element instead of a type (since WSDL message parts can
-be described either way). The formatType attribute is the Java type corresponding
to that abstract type or element. Its value must be one of the primitive
-Java types (char, byte, short, int, long, float, double) or the fully qualified
name of a Java class.</li>
+<li><strong><code>format:typeMapping</code></strong>
+For information about the format:typeMapping and format:typeMap please see
+<link href="formattypemapping_extension.html">Format Type Mapping</link>.</li>
<li><strong><code>java:operation</code></strong>
This element maps an abstract WSDL operation to a Java method. The methodName
attribute specifies the name of the Java method corresponding to the abstract
operation.
1.2 +1 -0
xml-axis-wsif/forrest-src/src/documentation/content/xdocs/providers/wsdl_extensions/book.xml
Index: book.xml
===================================================================
RCS file:
/home/cvs/xml-axis-wsif/forrest-src/src/documentation/content/xdocs/providers/wsdl_extensions/book.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- book.xml 31 Jan 2003 13:06:43 -0000 1.1
+++ book.xml 25 Feb 2003 14:29:57 -0000 1.2
@@ -19,5 +19,6 @@
<menu-item label="EJB" href="ejb_extension.html"/>
<menu-item label="JMS" href="jms_extension.html"/>
<menu-item label="J2C" href="j2c_extension.html"/>
+ <menu-item label="Format type mapping"
href="formattypemapping_extension.html"/>
</menu>
</book>
1.1
xml-axis-wsif/forrest-src/src/documentation/content/xdocs/providers/wsdl_extensions/formattypemapping_extension.xml
Index: formattypemapping_extension.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>WSDL Format Type Mapping Extension</title>
</header>
<body>
<section><title>Details</title>
<p>
The format type mapping WSDL extension maps qnames to Java classes. It appears in
the Java,
EJB and Native JMS bindings.
</p>
<p>
The format type mapping extends WSDL with the following extensibility elements:
</p>
<source>
<format:typeMapping style="uri" encoding="..."/>?
<format:typeMap typeName="qname"|elementName="qname"
formatType="nmtoken"/>*
</format:typeMapping>
</source>
<p>
Each element is described in detail below.
</p>
<ul>
<li><strong><code>format:typemapping</code></strong>
This element allows the specification of a mapping from abstract types used in WSDL
message parts (within the abstract service description) to java types that can
represent the same information. The style attribute is used to say something about
the target type system (i.e. the native type system being used to represent the
abstract information); in the case of the java type system the value here must be
"Java". This use of this attribute allows this extension to be reused for other
kinds of bindings. The encoding attribute must be a URI which is used to denote the
specific way in which the native type corresponds to the abstract type. We define a
special encoding, the "Java" encoding, with the rules that tell us how to create a
java class corresponding to an abstract schema type that can be used through the
WSDL java binding. Details on the "Java" encoding follow. Having the encoding
attribute allows us to map abstract types to java types in other convenient ways
by using a customized encoding.
<br /><br />
<strong>Java encoding</strong><br />
The java encoding used by WSIF is unspecified. The reason it does not need to be
specified is that encoding information is useful only when the information contained
within the java object is transformed in some way - serialized to a SOAP message,
or converted to a representation in another type system for example. If all we do
with a WSIF message containing parts belonging to the java type system is invoke the
corresponding java service, we don't need to do anything more than verify that each
message part is is represented using a java object of the correct type (as specified
by the typemapping element in the java binding).<br /><br />
Of course, we envisage the need for transforming messages from one representation
to another, but we leave the complete specification of the java encoding for a
later release.
</li>
<li>
<strong><code>format:typemap</code></strong>
Each typemap element maps an abstract type to a type in some more convenient type
system; in the case of the Java, EJB and Native JMS bindings this is the java type
system. The typeName attribute is a qualified name for the abstract type being
mapped (this must be one of the predefined schema types recognised in WSDL, or a
type defined under the <types> section in the WSDL). The elementName
attribute may be used to specify an element instead of a type (since WSDL message
parts can be described either way). The formatType attribute is the java type
corresponding to that abstract type or element. It values must be one of the
primitive java types (char, byte, short, int, long, float, double) or the fully
qualified name of a java class.
</li>
</ul>
</section>
</body>
</document>
1.2 +1 -0
xml-axis-wsif/forrest-src/src/documentation/content/xdocs/providers/book.xml
Index: book.xml
===================================================================
RCS file:
/home/cvs/xml-axis-wsif/forrest-src/src/documentation/content/xdocs/providers/book.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- book.xml 31 Jan 2003 13:06:40 -0000 1.1
+++ book.xml 25 Feb 2003 14:29:57 -0000 1.2
@@ -19,5 +19,6 @@
<menu-item label="EJB" href="wsdl_extensions/ejb_extension.html"/>
<menu-item label="JMS" href="wsdl_extensions/jms_extension.html"/>
<menu-item label="J2C" href="wsdl_extensions/j2c_extension.html"/>
+ <menu-item label="Format type mapping"
href="wsdl_extensions/formattypemapping_extension.html"/>
</menu>
</book>
