Welcome to your first day starting guide\!
Today, you will learn (or remind) what is a WSDL file, and how Petals ESB use it.
Lot of theory today. Don't worry, it's gonna be more and more practical everyday...
{panel:title=Last tested with}
* Getting Started Package 1.0 - [Download binaries here|http://doc.petalslink.com/x/t4KK]
This tutorial uses:
* Petals Studio
{panel}
{composition-setup}{composition-setup}
Any question, any problem? Find the solution on the [WSDL and Administration discussion|http://forum.petalslink.com/Petals-Starting-Guide-day-1-amp-2-WSDL-amp-Administration-td2688072.html].
h2. What is a WSDL?
*The essential: understand what is a WSDL.*
WSDL is essential to SOA. You will use WSDLs all over this guide.
*Answer these questions* before going any further.
* What does the "WSDL" acronym mean?
* What is a WSDL?
* What does a WSDL define?
* Why would you base communications on WSDLs?
* What differences are there between WSDL 1.1 and WSDL 2.0?
You can get answers here:
* [WSDL definitions|petalsstudiosnapshot:Getting started with BPEL#WSDL definitions].
* [5 minutes WSDL Tutorial|http://www.w3schools.com/wsdl/wsdl_documents.asp].
* [WSDL in 30 seconds.|http://tibcompany.blogspot.com/2009/08/what-is-wsdl-and-its-benefits.html]
* [WSDL 2.0 vs 1.1.|http://www.xml.com/pub/a/ws/2004/05/19/wsdl2.html]
* [WSDL on Wikipedia|http://en.wikipedia.org/wiki/Web_Services_Description_Language].
{toggle-cloak:id=WSDL} {color:#800080}{+}I'm done\! Give me the solution\!+{color}
{cloak:id=WSDL}
* *What "WSDL" acronym means?*
Web Service Definition Language.
* *What is a WSDL?*
A XML file defining how to use a service: its operations, adress, name, protocol...
* *What does a WSDL defines?*
** *PortType (WSDL 1.1) / Interface (WSDL 2.0)*: the service interface, which defines a list of operations to invoke.
** *XML Schema*: Define the XML structure of the operation's parameters (input and output parameters).
** *Messages*: Service communications are made through messages. Messages contain parameters and their values for the invocation of an operation.
** *Binding*: Which protocol have to be used to talk with the service. It also binds a service with an interface.
** *Service*: How to find the service. Name and location of the service
* *Why basing communication on WSDL?*
** More interoperability. WSDL XML service descriptions are readable from all platforms and there are bridges with several languages (Java, C, PHP...).
** Helps development. The description tells the developers how to use the service.
** More flexible. The interface makes service evolution more flexible: a WSDL is separated from the service implementation. It is a description. The implementation can change independently from the WSDL. The same service implementation can be deployed on several endpoints. Each end-point will have a slightly different WSDL (only the end-point differs).
* *What are the differences between WSDL 1.1 and WSDL 2.0?*
** WSDL 1.1 is the most commonly used. BPEL (Business Process Execution Language), for service orchestration, uses WSDL 1.1.
** WSDL 2.0 is recommended by W3C, but less used (mostly because of the lack of tooling). It offers more possibilities, such as describing REST services.
** Semantic changed:
*** <definitions> element is renamed to <description>.
*** <portType> element is renamed to <interface>.
*** <port> element is renamed to <endpoint>.
*** Additionally, <message> element is removed.
{info}There is a debate between SOAP and REST service protocol on the web. Google "SOAP vs REST" if you are interested. To sum-up:
* REST is based on HTTP operations. RESTful services are seen as resources. This approach is simpler and faster, but can be messy. It does not have any clear description language yet: WSDL 2.0 is not widely used and WADL is very new (submitted to W3C but not accepted yet).
* SOAP is more structured, descriptive and interoperable, but using XML can be heavier. It is widely used in companies.{info}
{info}Petals ESB supports perfectly SOAP services, but is less good with REST.{info}
{info}Petals ESB accept both WSDL 1.1 and 2.0.{info}
{info}Tips: Is your WSDL 1.1 or 2.0? If you find it <portType> element, it's WSDL 1.1. It was replaced by <interface> in WSDL 2.0.{info}
{cloak}
h2. Find the differences\!
Download those [5 sample WSDLs|^Petals_Getting_Started_WSDLs.zip] and look at them.
Can you *find and explain the main differences* between each?
Solutions:
{toggle-cloak:id=WSDL1} {color:#800080}{+}Petals_Getting_Started_1.wsdl{+}{color}
{cloak:id=WSDL1}
Simple WSDL file that describes a service to command a droid.
Uses WSDL v1.1:
{code:lang=xml}<wsdl:definitions (...) xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" >
(...)
<wsdl:portType name="TuxDroidPortType">{code}
and Binding SOAP v1.1:
{code:lang=xml}<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" > {code}
{cloak}
{toggle-cloak:id=WSDL2} {color:#800080}{+}Petals_Getting_Started_2.wsdl{+}{color}
{cloak:id=WSDL2}
Uses Binding SOAP 1.2:
{code:lang=xml}<wsdl:definitions xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/">{code}
{cloak}
{toggle-cloak:id=WSDL3} {color:#800080}{+}Petals_Getting_Started_3.wsdl{+}{color}
{cloak:id=WSDL3}
Defines two endpoints, one being associated with a SOAP binding 1.1 and the second one being being associated with a SOAP binding 1.2:
{code:lang=xml}<wsdl:service name="TuxDroid">
<wsdl:port name="TuxDroidPort" binding="tns:TuxDroidSoapBinding">
<soap:address location="http://localhost:9090/TuxDroidPort" />
</wsdl:port>
<wsdl:port name="TuxDroidPort_Soap12" binding="tns:TuxDroidSoapBinding_12">
<soap12:address location="http://www.example.org/" />
</wsdl:port>
</wsdl:service>{code}
{cloak}
{toggle-cloak:id=WSDL4} {color:#800080}{+}Petals_Getting_Started_4.wsdl{+}{color}
{cloak:id=WSDL4}
Imports schemas from an external file:
{code:lang=xml}<types>
<xsd:schema>
<xsd:import namespace="http://tuxdroid.ebmwebsourcing.com/" schemaLocation="TuxDroidService_schema1.xsd"/>
</xsd:schema>
</types>
{code}
{cloak}
{toggle-cloak:id=WSDL5} {color:#800080}{+}Petals_Getting_Started_5.wsdl{+}{color}
{cloak:id=WSDL5}
This WSDL describes a complete different service.
It respects the version 2.0 of the WSDL specifications (previous ones were all WSDL 1.1).
{code:lang=xml}<wsdl2:description xmlns:wsdl2="http://www.w3.org/ns/wsdl">
(...)
<wsdl2:interface name="ServiceInterface">{code}
{cloak}
h2. Import a Web Service in Petals ESB, using Petals Studio
A web service is always described by a WSDL file.
Notice that other kinds of services can be described with a WSDL.
This exercice will introduce the manipulation of WSDL definition through Petals' tooling.
\\
*Follow these steps to import the 4 first WSDLs into Petals Studio*.
Do not try with the 5th one. WSDL 2.0 support has been delayed from Petals.
# Download, [Install|http://doc.petalslink.com/display/petalsstudio11/Installing+Petals+Studio] and run Petals Studio: [Petals Studio Download|http://doc.petalslink.com/x/t4KK]
# *File > New > Service Unit Project*. Window "Select the kind of service to create" is displayed.
# Select: *Provide...* / *SOAP* / the version of the SOAP component to use and click *Next*.
# Click *Browse...* and select your WSDL file. All the fields should be filled-in automatically. Click *Next*.
{info}A Petals service is identified by the triplet (interface name, service name, endpoint name) defined in its jbi.xml file. If this service was associated with a WSDL, then the values in the jbi.xml must match those of the WSDL.{info}
# Define the name of the project and its location. Click *Next*.
{info}In Eclipse, you cannot have two projects with the same name in a given workplace.
{info}
# This current page expects properties that are specific to the Petals SOAP component.
{info} This is the SOAP Component configuration page. Configuration is retrieved by Petals Studio: Soap version, Address... Stop you mouse on the fields for a description. Or read more on [Petals-BC-SOAP documentation|petalscomponents:Petals-BC-SOAP].{info}
!screen-SOAP.png|thumbnail,border=1!
# Click *Next*. You here come to the last page of this wizard. By default, you have nothing to do here.
{info} This page defines CDK properties for the component. The CDK (Component development toolkit) is the basis of all the Petals components. Thus, these properties are common to several components.{info}
# Click *Finish*.
# Repeat for each WSDLs.
*Look at the WSDL and jbi.xml files*:
# In the left navigation tree, open any _jbi.xml_ => _Source_ Tab. Have a look and try to understand.
{info}JBI standard (or [JSR-208|http://jcp.org/aboutJava/communityprocess/final/jsr208/index.html]) defines the interactions between the container and components. jbi.xml files are used to configure artifacts in Petals. These artifacts can be components (if you develop a component), service-units (if you want to use a component), etc. So, basically, the jbi.xml file you opened is the file that configures the import of a Web Service in Petals (that makes it visible in Petals, to other Petals services).{info}
# Open the WSDL file => Source Tab. Those are the WSDLs you imported.
\\
Let's package these Service-Units for Petals ESB\!
*Export Service-Units for Petals ESB:*
# Click *File > Export* and select *Petals > Service-Unit*. Click *Next*.
# Check the project(s) "su-SOAP-XXX" to export. Select the output directory and click *Finish*.
\\
*DONE\! Bravo\!*
Now you know (or you got reminded):
* What is a WSDL, its elements, the difference between WSDL 1.1 and 2.0.
* How to import a WSDL in Petals Studio and generate a configuration file for the Petals SOAP component (Petals-BC-SOAP).
* How to package Service-Units for Petals ESB.
*Next step : Deploy, test, and monitor services in Petals ESB.*
Today, you will learn (or remind) what is a WSDL file, and how Petals ESB use it.
Lot of theory today. Don't worry, it's gonna be more and more practical everyday...
{panel:title=Last tested with}
* Getting Started Package 1.0 - [Download binaries here|http://doc.petalslink.com/x/t4KK]
This tutorial uses:
* Petals Studio
{panel}
{composition-setup}{composition-setup}
Any question, any problem? Find the solution on the [WSDL and Administration discussion|http://forum.petalslink.com/Petals-Starting-Guide-day-1-amp-2-WSDL-amp-Administration-td2688072.html].
h2. What is a WSDL?
*The essential: understand what is a WSDL.*
WSDL is essential to SOA. You will use WSDLs all over this guide.
*Answer these questions* before going any further.
* What does the "WSDL" acronym mean?
* What is a WSDL?
* What does a WSDL define?
* Why would you base communications on WSDLs?
* What differences are there between WSDL 1.1 and WSDL 2.0?
You can get answers here:
* [WSDL definitions|petalsstudiosnapshot:Getting started with BPEL#WSDL definitions].
* [5 minutes WSDL Tutorial|http://www.w3schools.com/wsdl/wsdl_documents.asp].
* [WSDL in 30 seconds.|http://tibcompany.blogspot.com/2009/08/what-is-wsdl-and-its-benefits.html]
* [WSDL 2.0 vs 1.1.|http://www.xml.com/pub/a/ws/2004/05/19/wsdl2.html]
* [WSDL on Wikipedia|http://en.wikipedia.org/wiki/Web_Services_Description_Language].
{toggle-cloak:id=WSDL} {color:#800080}{+}I'm done\! Give me the solution\!+{color}
{cloak:id=WSDL}
* *What "WSDL" acronym means?*
Web Service Definition Language.
* *What is a WSDL?*
A XML file defining how to use a service: its operations, adress, name, protocol...
* *What does a WSDL defines?*
** *PortType (WSDL 1.1) / Interface (WSDL 2.0)*: the service interface, which defines a list of operations to invoke.
** *XML Schema*: Define the XML structure of the operation's parameters (input and output parameters).
** *Messages*: Service communications are made through messages. Messages contain parameters and their values for the invocation of an operation.
** *Binding*: Which protocol have to be used to talk with the service. It also binds a service with an interface.
** *Service*: How to find the service. Name and location of the service
* *Why basing communication on WSDL?*
** More interoperability. WSDL XML service descriptions are readable from all platforms and there are bridges with several languages (Java, C, PHP...).
** Helps development. The description tells the developers how to use the service.
** More flexible. The interface makes service evolution more flexible: a WSDL is separated from the service implementation. It is a description. The implementation can change independently from the WSDL. The same service implementation can be deployed on several endpoints. Each end-point will have a slightly different WSDL (only the end-point differs).
* *What are the differences between WSDL 1.1 and WSDL 2.0?*
** WSDL 1.1 is the most commonly used. BPEL (Business Process Execution Language), for service orchestration, uses WSDL 1.1.
** WSDL 2.0 is recommended by W3C, but less used (mostly because of the lack of tooling). It offers more possibilities, such as describing REST services.
** Semantic changed:
*** <definitions> element is renamed to <description>.
*** <portType> element is renamed to <interface>.
*** <port> element is renamed to <endpoint>.
*** Additionally, <message> element is removed.
{info}There is a debate between SOAP and REST service protocol on the web. Google "SOAP vs REST" if you are interested. To sum-up:
* REST is based on HTTP operations. RESTful services are seen as resources. This approach is simpler and faster, but can be messy. It does not have any clear description language yet: WSDL 2.0 is not widely used and WADL is very new (submitted to W3C but not accepted yet).
* SOAP is more structured, descriptive and interoperable, but using XML can be heavier. It is widely used in companies.{info}
{info}Petals ESB supports perfectly SOAP services, but is less good with REST.{info}
{info}Petals ESB accept both WSDL 1.1 and 2.0.{info}
{info}Tips: Is your WSDL 1.1 or 2.0? If you find it <portType> element, it's WSDL 1.1. It was replaced by <interface> in WSDL 2.0.{info}
{cloak}
h2. Find the differences\!
Download those [5 sample WSDLs|^Petals_Getting_Started_WSDLs.zip] and look at them.
Can you *find and explain the main differences* between each?
Solutions:
{toggle-cloak:id=WSDL1} {color:#800080}{+}Petals_Getting_Started_1.wsdl{+}{color}
{cloak:id=WSDL1}
Simple WSDL file that describes a service to command a droid.
Uses WSDL v1.1:
{code:lang=xml}<wsdl:definitions (...) xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" >
(...)
<wsdl:portType name="TuxDroidPortType">{code}
and Binding SOAP v1.1:
{code:lang=xml}<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" > {code}
{cloak}
{toggle-cloak:id=WSDL2} {color:#800080}{+}Petals_Getting_Started_2.wsdl{+}{color}
{cloak:id=WSDL2}
Uses Binding SOAP 1.2:
{code:lang=xml}<wsdl:definitions xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/">{code}
{cloak}
{toggle-cloak:id=WSDL3} {color:#800080}{+}Petals_Getting_Started_3.wsdl{+}{color}
{cloak:id=WSDL3}
Defines two endpoints, one being associated with a SOAP binding 1.1 and the second one being being associated with a SOAP binding 1.2:
{code:lang=xml}<wsdl:service name="TuxDroid">
<wsdl:port name="TuxDroidPort" binding="tns:TuxDroidSoapBinding">
<soap:address location="http://localhost:9090/TuxDroidPort" />
</wsdl:port>
<wsdl:port name="TuxDroidPort_Soap12" binding="tns:TuxDroidSoapBinding_12">
<soap12:address location="http://www.example.org/" />
</wsdl:port>
</wsdl:service>{code}
{cloak}
{toggle-cloak:id=WSDL4} {color:#800080}{+}Petals_Getting_Started_4.wsdl{+}{color}
{cloak:id=WSDL4}
Imports schemas from an external file:
{code:lang=xml}<types>
<xsd:schema>
<xsd:import namespace="http://tuxdroid.ebmwebsourcing.com/" schemaLocation="TuxDroidService_schema1.xsd"/>
</xsd:schema>
</types>
{code}
{cloak}
{toggle-cloak:id=WSDL5} {color:#800080}{+}Petals_Getting_Started_5.wsdl{+}{color}
{cloak:id=WSDL5}
This WSDL describes a complete different service.
It respects the version 2.0 of the WSDL specifications (previous ones were all WSDL 1.1).
{code:lang=xml}<wsdl2:description xmlns:wsdl2="http://www.w3.org/ns/wsdl">
(...)
<wsdl2:interface name="ServiceInterface">{code}
{cloak}
h2. Import a Web Service in Petals ESB, using Petals Studio
A web service is always described by a WSDL file.
Notice that other kinds of services can be described with a WSDL.
This exercice will introduce the manipulation of WSDL definition through Petals' tooling.
\\
*Follow these steps to import the 4 first WSDLs into Petals Studio*.
Do not try with the 5th one. WSDL 2.0 support has been delayed from Petals.
# Download, [Install|http://doc.petalslink.com/display/petalsstudio11/Installing+Petals+Studio] and run Petals Studio: [Petals Studio Download|http://doc.petalslink.com/x/t4KK]
# *File > New > Service Unit Project*. Window "Select the kind of service to create" is displayed.
# Select: *Provide...* / *SOAP* / the version of the SOAP component to use and click *Next*.
# Click *Browse...* and select your WSDL file. All the fields should be filled-in automatically. Click *Next*.
{info}A Petals service is identified by the triplet (interface name, service name, endpoint name) defined in its jbi.xml file. If this service was associated with a WSDL, then the values in the jbi.xml must match those of the WSDL.{info}
# Define the name of the project and its location. Click *Next*.
{info}In Eclipse, you cannot have two projects with the same name in a given workplace.
{info}
# This current page expects properties that are specific to the Petals SOAP component.
{info} This is the SOAP Component configuration page. Configuration is retrieved by Petals Studio: Soap version, Address... Stop you mouse on the fields for a description. Or read more on [Petals-BC-SOAP documentation|petalscomponents:Petals-BC-SOAP].{info}
!screen-SOAP.png|thumbnail,border=1!
# Click *Next*. You here come to the last page of this wizard. By default, you have nothing to do here.
{info} This page defines CDK properties for the component. The CDK (Component development toolkit) is the basis of all the Petals components. Thus, these properties are common to several components.{info}
# Click *Finish*.
# Repeat for each WSDLs.
*Look at the WSDL and jbi.xml files*:
# In the left navigation tree, open any _jbi.xml_ => _Source_ Tab. Have a look and try to understand.
{info}JBI standard (or [JSR-208|http://jcp.org/aboutJava/communityprocess/final/jsr208/index.html]) defines the interactions between the container and components. jbi.xml files are used to configure artifacts in Petals. These artifacts can be components (if you develop a component), service-units (if you want to use a component), etc. So, basically, the jbi.xml file you opened is the file that configures the import of a Web Service in Petals (that makes it visible in Petals, to other Petals services).{info}
# Open the WSDL file => Source Tab. Those are the WSDLs you imported.
\\
Let's package these Service-Units for Petals ESB\!
*Export Service-Units for Petals ESB:*
# Click *File > Export* and select *Petals > Service-Unit*. Click *Next*.
# Check the project(s) "su-SOAP-XXX" to export. Select the output directory and click *Finish*.
\\
*DONE\! Bravo\!*
Now you know (or you got reminded):
* What is a WSDL, its elements, the difference between WSDL 1.1 and 2.0.
* How to import a WSDL in Petals Studio and generate a configuration file for the Petals SOAP component (Petals-BC-SOAP).
* How to package Service-Units for Petals ESB.
*Next step : Deploy, test, and monitor services in Petals ESB.*