WSDL Document Structure

Size: px

Start display at page:

Download "WSDL Document Structure"

Solomon Wilson
6 years ago
Views:

1 WSDL Invoking a Web service requires you to know several pieces of information: 1) What message exchange protocol the Web service is using (like SOAP) 2) How the messages to be exchanged are structured (the required data) 3) What transport protocol is employed by the Web service (like HTTP or SMTP) 4) The network address of the Web service In SOA all of this information is provided by a service description. A service description is simply a concept, so it can be implemented in a number of ways. WSDL is a language for creating service descriptions that are precise, machine readable, and platform independent

2 WSDL, cont. WSDL is based on XML. WSDL documents are simply XML documents with their own XML schema, XML namespaces, and processing rules. WSDL was designed as an IDL (interface definition language) for Web services that is independent of any specific protocol, programming language, or operating system. WSDL is typically used to describe SOAP-based Web services, but it is not specific to SOAP. WSDL was also designed to be modular so that its artifacts can be used to describe more than one Web service. WSDL is currently maintained by the W3C. It has large support from vendors in the Web services industry.

3 WSDL Document Structure A WSDL service description is composed of two major sections a service interface definition and a service implementation definition. The service interface definition defines the service at an abstract level by describing the messages it sends and receives. It answers the question about what the Web service does in terms of the operations it provides and the data it requires as well as the data (if any) it responds with. The service implementation definition defines the concrete implementation of the Web service interface by describing the wire and transport protocols in use (e.g., SOAP and HTTP) and the network address (i.e., a URL). It answers the questions about how a service is accessed and where a service is located.

4 WSDL Document Structure, cont. The separation of interface and implementation within a WSDL document allows multiple Web service implementations to be described that reuse the same interface. This can reduce the size of WSDL documents and consequently the time required to process them and the effort required to maintain them. A WSDL document is composed of the following key XML elements (continued on the next few slides), listed in their recommended order of appearance. The WSDL specification does not mandate this order, however, the WS-I BP does. definitions (mandatory): The root element of the XML document that defines a WSDL service description. There can be only one definitions element in a WSDL document and it contains all of the other WSDL elements.

5 WSDL Document Structure, cont. documentation (optional): Can be used to describe aspects of the WSDL document to human readers. May be used within any other WSDL element, meaning it can appear multiple times throughout the document. import (optional): Can be used to make available in the current WSDL document the definitions from other WSDL documents. Allows WSDL documents to be modularized. types (optional): Used to define all of the data types used by other elements throughout the WSDL document. WSDL does not mandate the use of any specific typing system, but the default typing system is XML Schema. message (optional): Used to describe the data transmitted between the service provider and the service requester, which represents a set of operation parameters and return values. Represents the payload of a one-way message, either a request message or a response message.

6 WSDL Document Structure, cont. porttype (optional): Defines a Web service s abstract interface definition (like a Java interface). Contains various operation elements that abstractly define the operations (methods) supported by a Web service. operation (optional): Analogous to a Java method declaration. It defines an operation that may be invoked on a Web service, including the name of the operation and the list of input parameters and output values. The operation element references one or more message elements to describe the parameter list. binding (optional): Used to associate operation elements of a porttype with a data format (like XML Schema) and a protocol (like SOAP over HTTP). Conceptually, the binding element is a concrete implementation of the abstract service interface (the porttype).

7 WSDL Document Structure, cont. service (optional): Aggregates one or more bindings and assigns a network address to each binding. In other words it defines the network address for the Web service. port (optional): Used as the immediate child of the service element to accomplish the actual association between a binding element and a network address. The porttype element (contains operation elements that reference message elements) is used to define the abstract service interface (i.e., what the Web service does). The binding element (references operation elements) and the service element (references binding elements) are used to define the concrete service implementation. The binding element describes how the Web service is accessed and the service element describes where the Web service is located. WSDL 1.1 namespace:

8 <definitions name= targetnamespace= xmlns:soapbind= xmlns:xsd= xmlns= > <types><xsd:schema targetnamespace= > </xsd:schema></types> <message name= ><part name= element= /></message> <porttype name= > <operation name= > <input message= /><output message= /> WSDL <fault name= message= /> </operation> </porttype> <binding name= type= > <soapbind:binding style= transport= /> <operation name= > <soapbind:operation soapaction= /> <input><soapbind:body use= /></input> <output><soapbind:body use= /></output> <fault name= ><soapbind:fault name= use= /></fault> </operation> </binding> <service name= > Document Structure <port name= binding= ><soapbind:address location= /></port> </service> </definitions>

9 <definitions name= MonitorPricingWS targetnamespace= xmlns:mon= xmlns:montypes= xmlns:soapbind= xmlns:xsd= xmlns= > <types> <xsd:schema targetnamespace= > <xsd:element name= MonitorPriceRequest > </xsd:element> <xsd:element name= price type= xsd:float /> <xsd:element name= InvalidArgumentFaultDetail > </xsd:element> </xsd:schema> </types> <message name= GetMonitorPriceRequest > <part name= pricerequest element= montypes:monitorpricerequest /> </message> Example <message name= GetMonitorPriceResponse > <part name= price element= montypes:price /> WSDL </message> <message name= InvalidArgumentFault > Document <part name= errormessage element= montypes:invalidargumentfaultdetail /> </message>

10 <porttype name= MonitorPricingPortType > <operation name= getmonitorprice > <input message= mon:getmonitorpricerequest /> <output message= mon:getmonitorpriceresponse /> <fault name= InvalidArgumentFault message= mon:invalidargumentfault /> </operation> </porttype> <binding name= MonitorPricingSOAPBinding type= mon:monitorpricingporttype > <soapbind:binding style= document transport= /> <operation name= getmonitorprice > <soapbind:operation soapaction= /> <input><soapbind:body use= literal /></input> <output><soapbind:body use= literal /></output> <fault name= InvalidArgumentFault > <soapbind:fault name= InvalidArgumentFault use= literal /> </fault> Example </operation> </binding> WSDL Document

11 Example WSDL Document, cont. <service name= MonitorPricingService > <port name= MonitorPricingPort binding= mon:monitorpricingsoapbinding > <soapbind:address location= /> </port> </service> </definitions> The elements with a prefix of soapbind: are extensibility elements. They are used to define SOAP-specific details of the Web service. The soapbind:binding element defines the messaging style of the Web service operations as document and the network protocol used to transport SOAP messages as HTTP. The soapbind:body element defines the encoding for the input and output messages as literal and the soapbind:fault element defines the encoding for the fault message as literal.

12 WSDL definitions Element The root of the WSDL document. All other WSDL XML elements are contained within definitions. Called definitions because the WSDL document is a container for a set of service definitions. In practice only a single service is defined in a WSDL document. May contain zero or more documentation elements, zero or more import elements, one optional types element, zero or more message elements, zero or more porttype elements, zero or more binding elements, and zero or more service elements. <definitions name= MonitorPricingWS targetnamespace= xmlns:soapbind= xmlns:xsd= xmlns= > </definitions>

13 WSDL documentation Element Provides human-readable information about the Web service. Any WSDL element (except the documentation element) can contain a documentation element. The WSDL 1.1 specification and the XML schema are inconsistent as to where documentation elements can be placed inside of other WSDL elements. Consequently the WS-I Basic Profile mandates that a documentation element, if present, be the first child element of its parent element. <definitions name= MonitorPricingWS targetnamespace= xmlns:wsi= xmlns= > <service name= MonitorPricingService > <port name= MonitorPricingPort binding= mon:monitorpricingsoapbinding > <documentation> <wsi:claim conformsto= /> </documentation> <soapbind:address location= /> </port> </service> </definitions>

14 WSDL import Element Used to import WSDL definitions from other WSDL documents. Works the same as the import element of XML Schema by binding a network location to an XML namespace, but don t confuse the use of the two. WS-I BP mandates that the WSDL import only import WSDL documents, and the XML Schema import only import schema definitions. A typical use of the WSDL import element is to split a WSDL document into service interface definition and service implementation definition. <definitions name= PricingService targetnamespace= xmlns:mon= xmlns:soapbind= xmlns= > <import namespace= location= /> <service name= MonitorPricingService > <port name= PricingPort binding= mon:monitorpricingsoapbinding > <soapbind:address location= /> </port> </service> </definitions>

15 WSDL types Element Defines data types used in the WSDL document. These data types are used within the message elements to define the payloads of the messages transmitted to and from the Web service. Since the default type system of WSDL is XML Schema, all XML Schema built-in types (like xsd:string, xsd:float, etc.) are immediately available, but you often need to define your own types. <definitions name= MonitorPricingWS targetnamespace= xmlns:mon= xmlns:montypes= xmlns:soapbind= xmlns:xsd= xmlns= > <types> <xsd:schema targetnamespace= > <xsd:element name= MonitorPriceRequest > </xsd:element> <xsd:element name= price type= xsd:float /> <xsd:element name= InvalidArgumentFaultDetail > </xsd:element> </xsd:schema> </types> <message name= GetMonitorPriceRequest > <part name= pricerequest element= montypes:monitorpricerequest /> </message> </definitions>

16 WSDL message Element Used to describe the logical abstract payload of a message transmitted to or from a Web service. Can describe incoming messages, outgoing messages, SOAP header blocks, and SOAP fault Detail elements. A WSDL document may contain zero or more message elements, all of which must have names that are unique within the WSDL document (because other WSDL elements reference them by name). Each message element may contain zero or more part elements that describe each part of the message. Can be modeled to represent either a document-style message or an RPC-style message. In a document-style message the part elements represent XML document fragments. In an RPC-style message the part elements represent input or output parameters of a procedure call.

17 WSDL message Element, cont. The part element may contain a type attribute that is used to refer to an XML Schema type (xsd:simpletype or xsd:complextype) or an element attribute that is used to refer to an XML Schema element (xsd:element), both of which are declared (or imported) by the types definition. A part element may use either type or element but not both. If you use the element attribute, then you are specifying that the payload of the message be exactly the XML element that you referenced. If you use the type attribute, then all you are specifying is what the data type of the element must be. The element that is actually used is determined by the binding element. The WS-I BP mandates that part elements use the type attribute for RPC-style messaging and the element attribute for document-style messaging. Because document-style messages are meant to carry XML document fragments (XML elements) and RPC-style messages are meant to carry parameters for a procedure (defined as specific data types).

18 <definitions name= MonitorPricingWS > <types> <xsd:schema targetnamespace= > <xsd:element name= InvalidArgumentFaultDetail > <xsd:complextype> </xsd:complextype> </xsd:element> </xsd:schema> </types> <message name= GetMonitorPriceRequest > <part name= productid type= xsd:string /> <part name= currency type= xsd:string /> </message> <message name= GetMonitorPriceResponse > <part name= price type= xsd:float /> </message> <message name= InvalidArgumentFault > <part name= errormessage element= montypes:invalidargumentfaultdetail /> </message> </definitions> WSDL message Element

19 WSDL porttype Element Used to define the abstract interface of a Web service. A porttype is similar in concept to a Java interface. Defines a collection of operation elements under a unique name (the name attribute of the porttype). The interface that the porttype defines is implemented by the binding and service elements. The binding element specifies the protocols and encoding of the Web service implementation. The service element defines the network address where the Web service implementation can be invoked. <porttype name= MonitorPricingPortType > <operation name= getmonitorprice > <input message= mon:getmonitorpricerequest /> <output message= mon:getmonitorpriceresponse /> <fault name= InvalidArgumentFault message= mon:invalidargumentfault /> </operation> </porttype>

20 WSDL operation Element Analogous to a Java method signature. Can contain zero or one input element, zero or one output element, and zero or more fault elements. The input element declares the message payload that is transmitted from the client to the Web service, and the output element declares the message payload that is transmitted from the Web service to the client. The fault elements declare the payloads of fault messages that may be transmitted from the Web service to the client in the event of an error. Each input, output, and fault element must contain a message attribute whose value is a QName (qualified name) for one of the message elements defined earlier in the WSDL document.

21 WSDL operation Element, cont. <definitions name= MonitorPricingWS targetnamespace= xmlns:mon= xmlns:montypes= xmlns:soapbind= xmlns:xsd= xmlns= > <types> </types> <message name= GetMonitorPriceRequest ><part name= element= /> </message> <message name= GetMonitorPriceResponse ><part name= element= /> </message> <message name= InvalidArgumentFault ><part name= element= /> </message> <porttype name= MonitorPricingPortType > <operation name= getmonitorprice > <input message= mon:getmonitorpricerequest /> <output message= mon:getmonitorpriceresponse /> <fault name= InvalidArgumentFault message= mon:invalidargumentfault /> </operation> </porttype> </definitions>

22 WSDL operation Element, cont. When the operation element only contains an input element, then the MEP is one-way. No output or fault elements can be declared in a one-way MEP. Ex: <porttype name= MonitorPurchaseOrderPortType > <operation name= submitpurchaseorder > <input name= order message= mon:submitpurchaseordermessage /> </operation> </porttype> To define a request-response MEP, the operation element must contain a single input and a single output element, and the input element must precede the output element. Ex: <porttype name= MonitorPricingPortType > <operation name= getmonitorprice > <input message= mon:getmonitorpricerequest /> <output message= mon:getmonitorpriceresponse /> <fault name= InvalidArgumentFault message= mon:invalidargumentfault /> </operation> </porttype>

23 WSDL parameterorder Attribute operation elements may also contain an optional parameterorder attribute, which is used to enforce a proper order of parameters in an RPC-style message. The parameterorder attribute must include all of the operation s input parts and only output parts that are not the return value of the procedure call. If an output message only contains a single part, then that part is assumed to be the return value. If an output part is listed in the parameterorder attribute, then it is treated as an OUT parameter. If both an input and output message contain a part with the same name, then that part is assumed to be the same parameter and is treated as an INOUT parameter.

24 WSDL parameterorder Attribute <message name= GetMonitorPriceRequest > <part name= productid type= xsd:string /> <part name= currency type= xsd:string /> </message> <message name= GetMonitorPriceResponse > <part name= price type= xsd:float /> </message> <porttype name= MonitorPricingPortType > <operation name= getmonitorprice parameterorder= productid currency > <input message= mon:getmonitorpricerequest /> <output message= mon:getmonitorpriceresponse /> </operation> </porttype>

25 WSDL binding Element The service implementation definition is described by the binding and service elements. The binding element defines the format for the messages in a protocol-specific manner. It maps an abstract porttype to a concrete implementation that uses specific messaging styles (RPC or document), protocols (like SOAP and HTTP), and encoding styles (like literal or SOAP Encoding). A single WSDL document may contain multiple bindings for each porttype. For example, you may want to bind a single porttype to both a SOAP over HTTP implementation and a SOAP over SMTP implementation.

26 WSDL binding Element, cont. <definitions name= MonitorPricingWS targetnamespace= xmlns:mon= xmlns:montypes= xmlns:soapbind= xmlns:xsd= xmlns= > <porttype name= MonitorPricingPortType > <operation name= getmonitorprice > <input message= mon:getmonitorpricerequest /> <output message= mon:getmonitorpriceresponse /> </operation> </porttype> <binding name= MonitorPricingSOAPBinding type= mon:monitorpricingporttype > <soapbind:binding style= document transport= /> <operation name= getmonitorprice > <soapbind:operation soapaction= /> <input><soapbind:body use= literal /></input> <output><soapbind:body use= literal /></output> </operation> </binding> </definitions>

27 SOAP Binding The SOAP-WSDL extensibility elements allow us to define the SOAP-specific details of the Web service: soapbind:binding Describes the default message style (RPC or document) of the operations in the WSDL binding and the underlying network protocol (like HTTP) that will be used to transport the messages. soapbind:operation Specifies a message style for the operation that overrides the default style in the soapbind:binding element and to specify a value for the SOAPAction HTTP header field. soapbind:body Describes how the message part elements will be formatted in the SOAP Body element. Defines the encoding style of the message payload, the namespace for the elements of the message payload, and which part elements are going to appear in the message.

28 SOAP Binding, cont. soapbind:fault Serves a similar purpose as the soapbind:body element except it applies to faults instead of input and output messages. soapbind:header Describes SOAP header blocks for input or output messages. Each input and output element can have one or more soapbind:header elements, which makes since because a single SOAP message can have multiple header blocks. soapbind:headerfault Describes a fault that is specific to a header block. SOAP requires faults that are associated with header blocks be placed in the SOAP Header, and consequently, WSDL requires soapbind:headerfault elements to be nested within their associated soapbind:header elements.

29 WSDL service Element Contains a set of port elements, which each assign a network address to a binding. A WSDL document may contain multiple service elements, but usually only one is used. The service element must have a name attribute and the value must be unique among all service elements in the WSDL document. One or more port elements can appear in a single service element and all of them should be related to the same Web service. Multiple port elements within a service can assign different network addresses to the same binding, which can be useful for supporting failover or load balancing. <service name= MonitorPricingService > <port name= MonitorPricingPort binding= mon:monitorpricingsoapbinding > <soapbind:address location= /> </port> </service>

This presentation is a primer on WSDL Bindings. It s part of our series to help prepare you for creating BPEL projects. We recommend you review this

This presentation is a primer on WSDL Bindings. It s part of our series to help prepare you for creating BPEL projects. We recommend you review this presentation before taking an ActiveVOS course or before