uCosminexus Service Platform, Reception and Adapter Definition Guide

[Contents][Glossary][Index][Back][Next]

2.7.1 Example of a Business Process Used for Creating WSDL

This subsection explains the illustrated contents of a business process used for explaining how to create a WSDL file.

Organization of this subsection
(1) Example of a business process
(2) Example of message format contents
(3) Example of Creating WSDL

(1) Example of a business process

The following figure shows a business process to be used as an example for creating the WSDL.

Figure 2-7 Business process to be used as an example for creating the WSDL

[Figure]

  1. The service requester sends a service component execution request to a business process.
  2. An XML request message is sent with the service component execution request.
  3. The business process receives the XML request message with the receive activity Reception 1. The operation name in this case is operation1.
  4. In Reception 1, the variable RequestMessage is allocated and Request.xsd is specified as a message format that provides the request message.
  5. The service component is invoked from the business process. If a fault occurs, the fault is returned in No. 10.
  6. The business process configures the service component execution result as an XML response message, and returns the result with the reply activity Response 1.
  7. In Response 1, the variable ResponseMessage is allocated and Response.xsd is specified as a message format that provides the response message.
  8. The response to the service requester is returned.
  9. The XML response message is sent as the response to the service requester.
  10. If a fault occurs in No. 5, the fault fault1 is returned from the reply activity Response 2.
  11. In Response 2, the variable FaultMessage is allocated and Fault.xsd is specified as the message format that provides the fault message.
  12. The fault message is sent to the service requester.

(2) Example of message format contents

An example of message format used in the business process and shown in the Figure 8-4 is described below:

Request.xsd
  • XML schema source
    This is the message format for a request message that provides a single element <Request1> having a string value.
     
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema targetNamespace="http://www.example.org/request"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <xsd:element name="Request1" type="xsd:string" />
</xsd:schema>
  • XML sent according to the provision of this message format
     
<Request1>Sample request message</Request1>

Response.xsd
  • XML schema source
    This is the message format for a response message that provides a single element <Response1> having a boolean value.
     
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema targetNamespace="http://www.example.org/response"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <xsd:element name="Response1" type="xsd:boolean" />
</xsd:schema>
  • XML sent according to the provision of this message format
     
<Response1>true</Response1>

Fault.xsd
  • XML schema source
    This is a message format for the fault message that provides an element called <Fault1>, and also provides an element <param1> having int value as a child element.
     
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema targetNamespace="http://www.example.org/service"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:svc="http://www.example.org/service">
  <xsd:element name="Fault1" type="svc:SampleData"/>
  <xsd:complexType name="SampleData">
    <xsd:sequence>
      <xsd:element name="param1" type="xsd:int"/>
    </xsd:sequence>
  </xsd:complexType>
</xsd:schema>
  • XML sent according to the provision of this message format
     
<Fault1>
  <param1>123</param1>
</Fault1>

(3) Example of Creating WSDL

This subsection explains an example of creating WSDL that is appropriate to the business process described in 2.7.1 Example of a Business Process Used for Creating WSDLby assuming the use of SOAP1.1. For details on the conditions and precautions related to the WSDL format, see 2.7.1 Application Scopes of Service Components That Use Web Services and 2.7.3 Notes on creating WSDL of a user-defined reception.

The example for creating WSDL is assumed to be Sample_Reception.wsdl. An overview of Sample_Reception.wsdl is explained below:

Sample_Reception.wsdl, an example of creating WSDL, is explained below:

 
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions
 targetNamespace="http://www.example.org/service"
 xmlns:svc="http://www.example.org/service"
 xmlns:req="http://www.example.org/request"
 xmlns:res="http://www.example.org/response"
 xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
 xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <wsdl:types>
    <xsd:schema targetNamespace="http://www.example.org/request">
      <xsd:element name="Request1" type="xsd:string" />
    </xsd:schema>
    <xsd:schema targetNamespace="http://www.example.org/response">
      <xsd:element name="Response1" type="xsd:boolean" />
    </xsd:schema>
    <xsd:schema targetNamespace="http://www.example.org/service">
      <xsd:element name="Fault1" type="svc:SampleData"/>
      <xsd:complexType name="SampleData">
        <xsd:sequence>
          <xsd:element name="param1" type="xsd:int"/>
        </xsd:sequence>
      </xsd:complexType>
    </xsd:schema>
  </wsdl:types>
  <wsdl:message name="ReqMsg1">
    <wsdl:part element="req:Request1" name="reqParam"/>
  </wsdl:message>
  <wsdl:message name="ResMsg1">
    <wsdl:part element="res:Response1" name="resParam"/>
  </wsdl:message>
  <wsdl:message name="FltMsg1">
    <wsdl:part element="svc:Fault1" name="fltParam"/>
  </wsdl:message>
  <wsdl:portType name="SamplePortType">
    <wsdl:operation name="operation1">
      <wsdl:input message="svc:ReqMsg1"/>
      <wsdl:output message="svc:ResMsg1"/>
      <wsdl:fault message="svc:FltMsg1" name="Fault1"/>
    </wsdl:operation>
  </wsdl:portType>
  <wsdl:binding name="SampleBinding" type="svc:SamplePortType">
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="operation1">
      <soap:operation soapAction=""/>
      <wsdl:input>
        <soap:body/>
      </wsdl:input>
      <wsdl:output>
        <soap:body/>
      </wsdl:output>
      <wsdl:fault name="Fault1">
        <soap:fault name="Fault1"/>
      </wsdl:fault>
    </wsdl:operation>
  </wsdl:binding>
  <wsdl:service name="SampleService">
    <wsdl:port binding="svc:SampleBinding" name="UserInfo">
      <soap:address location="http://localhost:80/SampleService/services/UserInfo" />
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>

This example Sample_Reception.wsdl is created as per the operations explained below from (1) to (8):

(a) Listing the operations and fault names

List the synchronous operations defined in the receive activity and reply activity of a business process. If a reply activity exists in which the fault name is defined, list the fault names as well.

In the creation example, the operation corresponds to operation1. Also, the fault name corresponds to Fault1.

(b) Listing the message format definition files for the allocated variable

List message format definition files for the allocated variables used in the receive activity and reply activity.

In the creation example, the files correspond to Request.xsd, Response.xsd, and Fault.xsd.

Note
  • If there are multiple schemas with the same name space in the listed message format definition files, they must be consolidated into one schema.
    At this time, if the following conditions are satisfied, make changes so that the message format definition file for the allocated variable does not have duplicate names:
    - There are duplicate names for elements within the schema.
    - The contents of the elements are different.
    Note that if there are multiple message format definition files for an allocated variable (when an external XML file is referenced), make changes so that there is no duplication of elements including the external XML file schema.
    Furthermore, if the individual schema attributes have conflicting values, you consolidate the schema considering the impact caused by the change in values.
  • If there is a schema (chameleon schema) that does not have the targetNamespace attribute within the listed message format definition files, change to a schema with the targetNamespace attribute specified in the message format definition files for the allocated variable.
  • If the root element in the message format definition file for the listed fault messages is not a complex type, you change the root element in the message format definition file for the allocated variable, so that the root element becomes a complex type.
  • The name space of the fault message root element needs to match with the name space of the wsdl:definitions element.
    Therefore, if the following conditions are satisfied, you change the message format file of the allocated variables:
    - There are multiple fault messages.
    - The name spaces of the root element are different.
    If the name spaces for the same fault messages in different operations are different, you can create separate WSDL files for each operation, and create multiple user-defined receptions for providing support.
(c) Creating the template for a WSDL file (defining the wsdl:definitions element)

Define an XML declaration and the wsdl:definitions element as the template for a WSDL file. In the wsdl:definitions element, add the attributes described in the following table.

Table 2-22 Attributes to be added in the wsdl:definitions element

Attributes Meaning Value Number
targetNamespace Name space URI of the service component You can define any URI. However, if a fault message exists, define URI same as the value of targetNamespace attribute that exists in the xsd:schema element of the message format definition file for the fault message. 1
xmlns:svc Prefix declaration of a service component Define the value specified in the targetNamespace attribute. 1
xmlns:req Message format prefix declaration of a request message Define URI same as the value of targetNamespace attribute that exists in the xsd:schema element of the message format definition file for the request message. 1
xmlns:res Message format prefix declaration for a response message Define URI same as the value of targetNamespace attribute that exists in the xsd:schema element of the message format definition file for the response message. 1
xmlns:soap Prefix declaration of SOAP Define the pre-defined value http://schemas.xmlsoap.org/wsdl/soap/. 1
xmlns:wsdl Prefix declaration of WSDL Define the pre-defined value http://schemas.xmlsoap.org/wsdl/ 1
xmlns:xsd Prefix declaration of XML schema Define the pre-defined value http://www.w3.org/2001/XMLSchema. 1

The following figure shows an example for defining the wsdl:definitions element:

Figure 2-8 Definition example of the wsdl:definitions element

[Figure]

When using multiple operations
In the creation example (Sample_Reception.wsdl) only one operation is used, but if multiple operations are used, multiple request messages and response messages are handled. If these messages use multiple different name spaces, you define individual prefix declarations in the wsdl:definitions element, as shown in the table below:

Table 2-23 Attribute to be added in the wsdl:definitions element (when multiple operations are used)

Attributes Meaning Value
xmlns:reqN(N>0) Prefix declaration used when the request messages are divided into multiple name spaces Define URI same as the value of targetNamespace attribute that exists in the xsd:schema element of the message format definition file for the request message.

Example
http://www.example.org/request1
xmlns:resN(N>0) Prefix declaration used when the response messages are divided into multiple name spaces Define URI same as the value of targetNamespace attribute that exists in the xsd:schema element of the message format definition file for the response message.

Example
http://www.example.org/response1
The contents are defined in the element attribute of the wsdl:part element that is a child element of the wsdl:message element. For details on the wsdl:message element definition, see "(e) Defining the wsdl:message element".
The following figure shows an example of definition when multiple operations are used:

Figure 2-9 Definition example of the wsdl:definitions element (When multiple operations are used)

[Figure]
(d) Defining the wsdl:types element

Define the wsdl:types element, its lower elements, and attributes.

  1. Define the wsdl:types element as a child element of the wsdl:definitions element defined in (c) Creating the template for a WSDL file (defining the wsdl:definitions element).
  2. Classify the xsd:schema element in message format definition files listed in (2) into the targetNamespace attribute, and define one xsd:schema element for each targetNamespace values (b) Listing the message format definition files for the allocated variable.
  3. Add all the attributes that exist in the xsd:schema element of the message format definition file as attributes for the xsd:schema element defined in step 2.
  4. Add all the child elements that exist in the xsd:schema element of the message format definition file as the child elements for the xsd:schema element defined in step 2.
  5. If there are multiple fault messages and name spaces are different, change the name space of fault message into the value of targetNamespace attribute in the wsdl:definitions element.

The following table describes the elements and attributes to be defined in the wsdl:types element:

Table 2-24 Elements and attributes to be defined in the wsdl:types element

Element Attributes Meaning Value Number
wsdl:types -- Type definition element -- 1
xsd:schema -- Schema element -- From 1 up to the number of name spaces used in the message format definition file
targetNamespace Name space attribute Define the value same as the targetNamespace of the message. 1
Attribute of xsd:schema Attributes Define the value same as the message attribute. From 1 up to the number of attributes
Child element of xsd:schema -- Message contents Copy all the child elements of the xsd:schema element that the message contains. From 1 up to the number of child elements of the xsd:schema element in the message formats using the same name space

Legend:
--: Not applicable

The following figure shows an example for defining the wsdl:types element:

Figure 2-10 Definition example of the wsdl:types element

[Figure]

(e) Defining the wsdl:message element

Define the wsdl:message element, its lower elements and attributes:

  1. Define the wsdl:message element as the child element of the wsdl:definitions element that is defined in (c) Creating the template for a WSDL file (defining the wsdl:definitions element).
    Define the same number of wsdl:message elements as the number of request messages, response messages, and fault messages that exist in the operations defined in WSDL.
    There is one operation in the creation example. Since this operation has one request message, one response message, and one fault message, three wsdl:message elements are defined.
  2. Define the name attribute in the wsdl:message element.
    Define a value different from the name attribute of other wsdl:message elements so that the name attribute value is a unique value in the file.
    In the creation example, ReqMsg1 is defined in the operation1 request message and ResMsg1 is defined in the response message. The fault messages are FltMsgN (N is 1 or more) as per the numbers.
  3. Define wsdl:part elements as child elements of the wsdl:message element, one by one.
  4. Define the name attribute and element attribute in the wsdl:part element.
    Specify any string in the name attribute.
    Select a root element from a child element of the xsd:schema element copied in (4), and specify (d) Defining the wsdl:types element in the element attribute value element. Use the prefix and root element names described in the Table 2-22 and specify the name in QName.

The following table describes the elements and attributes to be defined in the wsdl:message element:

Table 2-25 Elements and attributes to be defined under the wsdl:message element

Element Attributes Meaning Value Number
wsdl:message -- Message definition element -- 1
name Message name attribute Define a unique string different from the name attribute of other wsdl:message elements. 1
wsdl:part -- Message part definition element -- 1
name Message part name attribute Define any string#. 1
element Element reference attribute Define the root element of applicable message format file. 1

Legend:
--: Not applicable

#
There are limited character types that can be used. For details about the character types that can be used, see "2.7.3(2) Characters that can be used for WSDL definition".

The following figure shows an example for defining the wsdl:message element:

Figure 2-11 Definition example of the wsdl:message element

[Figure]

(f) Defining the wsdl:portType element

Define the wsdl:portType element, its lower elements, and attributes.

  1. Define one wsdl:portType element as the child element of the wsdl:definitions element defined in (c) Creating the template for a WSDL file (defining the wsdl:definitions element).
  2. Define the name attribute in the wsdl:portType element.
    You can specify any string in the name attribute value.
  3. Define only the number of operations listed up by (a) Listing the operations and fault names for the wsdl:operation element.
    Define the wsdl:operation element for all the operations listed in (1).
  4. Define the name attribute in the wsdl:operation element.
    Specify the operation name for the operation listed in (a) Listing the operations and fault names in the name attribute value.
    In the creation example, define one wsdl:operation element and assume the name attribute as operation1.
  5. Define the wsdl:input element, wsdl:output element, and wsdl:fault element as the child elements of the wsdl:operation element.
    Define the child elements in the order of wsdl:input element, wsdl:output element, and wsdl:fault element.
    If the reply activity for the fault message does not exist, you can omit the wsdl:fault element. If there are multiple reply activities for the fault message, define only for the number of activities that exist.
    In the creation example, wsdl:input element, wsdl:output element, and wsdl:fault element are defined one by one.
  6. Define the message attribute in the wsdl:input element and wsdl:output element.
    In the message attribute value, specify the name attribute value of the wsdl:message element defined in (e) Defining the wsdl:message element with QName.
  7. Define the name attribute and message attribute in the wsdl:fault element.
    Specify a fault name listed in (a) Listing the operations and fault names in the name attribute value.
    In the message attribute value, specify the name attribute value of the wsdl:message element defined in (e) Defining the wsdl:message element with QName.

The following table describes the elements and attributes to be defined in the wsdl:portType element:

Table 2-26 Elements and attributes to be defined in the wsdl:portType element

Element Attributes Meaning Value Number
wsdl:portType -- Port type definition element -- 1
name Port type name attribute Define any string#. 1
wsdl:operation -- Operation definition element -- From 1 up to number of operations
name Operation name attribute Define the operation name. 1
wsdl:input -- Request message definition element -- 1
Message Message reference attribute Specify the name attribute value of the wsdl:message element defined in (e) Defining the wsdl:message element with QName. 1
wsdl:output -- Response message definition element -- 1
Message Message reference attribute Specify the name attribute value of the wsdl:message element defined in (e) Defining the wsdl:message element with QName. 1
wsdl:fault -- Fault message definition element -- From 1 up to number of faults
name Fault message name attribute Define fault name. 1
Message Fault message reference attribute Specify the name attribute value of the wsdl:message element defined in (e) Defining the wsdl:message element with QName. 1

Legend:
--: Not applicable

#
There are limited character types that can be used. For details about the character types that can be used, see "2.7.3(2) Characters that can be used for WSDL definition".

The following figure shows an example for defining the wsdl:portType element:

Figure 2-12 Definition example of the wsdl:portType element

[Figure]

(g) Defining the wsdl:binding element

Define the wsdl:binding element, its lower elements, and attributes.

  1. Define the wsdl:binding element as a child element of the wsdl:definitions element defined in (c) Creating the template for a WSDL file (defining the wsdl:definitions element).
  2. Define the name attribute and type attribute in the wsdl:binding element.
    You can specify any string in the name attribute value.
    In the type attribute value, specify the name attribute value of wsdl:portType element defined in (f) Defining the wsdl:portType element with QName.
  3. Define the soap:binding element as a child element of the wsdl:binding element.
  4. Define the transport attribute in the soap:binding element.
    The transport attribute value is a fixed value. It is defined as http://schemas.xmlsoap.org/soap/http.
  5. Define only the number of operations listed up by (a) Listing the operations and fault names for the wsdl:operation element.
    Define the wsdl:operation element for all the operations listed in (1).
  6. Define the name attribute in the wsdl:operation element.
    In the name attribute value, specify the value same as the name attribute value of the wsdl:operation element that is the child element of the wsdl:portType element defined in (f) Defining the wsdl:portType element.
  7. Define the soap:operation element as a child element of the wsdl:operation element.
  8. Specify the soapAction attribute in the soap:operation element.
    The value of the soapAction attribute is set to null.
  9. Define the wsdl:input element, wsdl:output element, and wsdl:fault element as the child elements of the wsdl:operation element.
    Define the child elements in the order of wsdl:input element, wsdl:output element, and wsdl:fault element.
    If the reply activity for the fault message does not exist, you can omit the wsdl:fault element. If there are multiple reply activities for the fault message, define only for the number of activities that exist.
    In the creation example, wsdl:input element, wsdl:output element, and wsdl:fault element are defined one by one.
  10. Define the soap:body element as a child element of the wsdl:input element and wsdl:output element.
    Value is not specified in the soap:body element.
  11. Define the name attribute in the wsdl:fault element.
    In the name attribute value, specify a value same as the name attribute value of the wsdl:fault element that is a child element of the wsdl:operation element defined in (f) Defining the wsdl:portType element.
  12. Define the soap:fault element as a child element of the wsdl:fault element.
  13. Define the name attribute in the soap:fault element.
    In the name attribute value, specify a value same as the name attribute of the wsdl:fault element that is the parent element.

The following table describes the elements and attributes to be defined in the wsdl:binding element:

Table 2-27 Elements and attributes to be defined in the wsdl:binding element

Element Attributes Meaning Value Number
wsdl:binding -- Binding definition element -- 1
name Binding name attribute Define any string#. 1
type Port type reference attribute Specify the name attribute value of wsdl:portType defined in (f) Defining the wsdl:portType element in QName. 1
soap:binding -- SOAP binding definition element -- 1
transport SOAP binding transmission type definition attribute Define http://schemas.xmlsoap.org/soap/http (fixed value). 1
wsdl:operation -- Operation definition element -- From 1 up to number of operations
name Operation name attribute Define the operation name.
Specify the value same as the name attribute value of the wsdl:fault element that is a child element of the wsdl:operation element defined in (f) Defining the wsdl:portType element.		 1
soap:operation -- SOAP binding operation definition element -- 1
soapAction SOAPAction header definition attribute -- 1
wsdl:input -- Request message definition element -- 1
soap:body -- SOAP binding Body element definition element -- 1
wsdl:output -- Response message definition element -- 1
soap:body -- SOAP binding Body element definition element -- 1
wsdl:fault -- Fault message definition element -- From 1 up to number of faults
name Fault message name attribute Define fault name. 1
soap:fault -- SOAP binding Fault element definition element -- 1
name SOAP binding name attribute Define fault name. 1

Legend:
--: Not applicable

#
There are limited character types that can be used. For details about the character types that can be used, see "2.7.3(2) Characters that can be used for WSDL definition".

The following figure shows an example for defining the wsdl:binding element:

Figure 2-13 Definition example of the wsdl:binding element

[Figure]

To use the style attribute and use attribute
You can also use the style attribute and use attribute in the wsdl:binding element to clearly specify document or literal.

Figure 2-14 Definition example of the wsdl:binding element (When the style attribute and use attribute are used)

[Figure]
(h) Defining the wsdl:service element

Define the wsdl:service element, its lower elements, and attributes.

  1. Define the wsdl:service element as a child element of the wsdl:definitions element defined in (c) Creating the template for a WSDL file (defining the wsdl:definitions element).
  2. Define the name attribute in the wsdl:service element.
    You can specify any string in the name attribute value.
  3. Define one wsdl:port element as the child element of the wsdl:service element.
  4. Define the name attribute and binding attribute in the wsdl:port element.
    You can specify any string in the name attribute value.
    As the binding attribute value, specify the name attribute value of the wsdl:binding element defined in (g) Defining the wsdl:binding element with QName.
  5. Define one soap:address element as a child element of the wsdl:port element.
  6. Define the location attribute in the soap:address element.
    As the location attribute value, http://localhost:80/SampleService/services/PortName is specified as a temporary value.
    Specify the value same as the name attribute defined in step 4. in PortName.
    Hint
    At the stage when WSDL is created, the service location value (location attribute value of the soap-address element in the wsdl:port element) is not yet determined. Therefore, specify a temporary value. This value does not cause an error in the SOAP Communication Infrastructure and JAX-WS engine provided by Cosminexus.
    The service location value is fixed after specifying the deployment definition of the HCSC component in which the user definition file is included. Edit WSDL, set up the fixed service location value, and then create the service requester based on WSDL. For details on editing WSDL, see 8.7.2 Editing a WSDL.

The following table describes the elements and attributes to be defined in the wsdl:service element:

Table 2-28 Elements and attributes to be defined under the wsdl:service element

Element Attributes Meaning Value Number
wsdl:service -- Service definition element -- 1
name Service name attribute Define any string#. 1
wsdl:port -- Port definition element -- 1
name Port name attribute Define any string#. 1
binding Binding reference attribute Specify the name attribute value of the wsdl:binding element defined in (g) Defining the wsdl:binding element with QName. 1
soap:address -- SOAP binding address definition element -- 1
location Service location definition attribute As a temporary value, define http://localhost:80/SampleService/services/PortName.
Specify a value same as the name attribute of the wsdl:port element in PortName.		 1

Legend:
--: Not applicable

#
There are limited character types that can be used. For details about the character types that can be used, see "2.7.3(2) Characters that can be used for WSDL definition".

The following figure shows an example for defining the wsdl:service element:

Figure 2-15 Definition example of the wsdl:service element

[Figure]

When using multiple wsdl:port
In the creation example (Sample_Reception.wsdl), all the operations are defined in one wsdl:port element, however, you can also use multiple wsdl:port elements to define each operation.
The following figure shows a definition example when multiple wsdl:port elements are used:

Figure 2-16 Definition example of the wsdl:service element (When multiple wsdl:port elements are used)

[Figure]

[Contents][Back][Next]

[Trademarks]

All Rights Reserved. Copyright (C) 2015, Hitachi, Ltd.