Your SlideShare is downloading. ×
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
WSDL Training
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×
Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

WSDL Training

2,555

Published on

http://www.Intertech.com …

http://www.Intertech.com

This is a slidedeck on WSDL.

Published in: Technology
1 Comment
7 Likes
Statistics
Notes
  • A very good overview of WSDL, good links to other resourses and a nice argument for schema design first.
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
No Downloads
Views
Total Views
2,555
On Slideshare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
9
Comments
1
Likes
7
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

Transcript

  • 1. Why Bother with this talk?  Web Services are a hot topic  Web Services commonly fall short of their potential • Leaders decide on a single technology stack to avoid web service issues (to unify approach) • People create web services the easy way without understanding the technology • Tools don’t always do what they should by default  Many Web Services are failing to follow evolving standards
  • 2. Defining Web Services  Before we get too far in we should understand what we mean by a web service  For many attendees I expect this is review, but we need to establish some definition of a web service • I just want to limit the definition in order to focus this talk • Definitions of web services are typically vague
  • 3. Many SOA Definitions Exist “A set of components which can be invoked, and whose interface descriptions can be published and discovered” W3C “SOA is an architectural style whose goal is to achieve loose coupling among interacting software agents.” Hao He (on O’Reilly.com) “SOA is kind of an IT manager's holy grail, in which software components can be exposed as services on the network, and so can be re-used time and time again for different applications and purposes” Preston Gralla “The policies, practices, frameworks that enable application functionality to be provided and consumed as sets of services published at a granularity relevant to the service consumer. Services can be invoked, published and discovered, and are abstracted away from the implementation using a single, standards-based form of interface.” David Sprott and Lawrence Wilkes
  • 4. My Simple Definition  These are the characteristics that define a web service (at least for today) • A “service” can be invoked over HTTP (not limited to HTTP) • “Services” accept and transmit XML messages following the SOAP (XML Protocol) standard • “Services” provide descriptions using WSDL documents
  • 5.  The basic picture of a web service should be familiar XML over HTTP SOAP!  This picture just demonstrates that a web service is a distributed technology using SOAP as the communication
  • 6.  WSDL Communicates to the client how to call the web service WSDL STUB  The WSDL is used to create a “stub” which encodes the method invocation as SOAP
  • 7. XML Schema  I should mention that the WSDL document commonly refers to or includes XML Schema • XML Schema is the W3C recommended way to define the grammar of an xml document • It describes the XML payload, what is allowed, required and forbidden • More on XML Schema later
  • 8. Best Left Unsaid  The Role of UDDI and how it is being used is beyond the scope of this presentation  The exact rules of SOAP are left off for your enjoyment  This talk is not going to discuss SOA details or do comparisons of Web Services to EDI
  • 9. DEMONSTRATION Quick Web Service WSDL Based Client (Optional)
  • 10. RPC Thinking  The previous demonstration (and most web service API’s) tends to lead a programmer to a very comfortable way of thinking 1) Create a method just like I always do 2) Somehow apply a doohickey (technical term) to the method and it becomes a web service 3) Create a regular looking client by giving a WSDL doc to that new contraption and I don’t need to learn much XML at all (YEA this is easy!)
  • 11. RPC Thinking - Trouble  The trouble with RPC thinking in a web service is multifold, we will look at 6 reasons to not think like a programmer 1. Schema is more descriptive 2. Your programming language isn’t alone 3. Change will happen in schema 4. The Web Service isn’t just the method 5. SOAP Faults don’t provide enough error reporting 6. Standards are setup for WSDL and SOAP not your language
  • 12. Message Design Thinking  Instead of RPC thought I will suggest a WSDL/Schema first approach • Thinking WSDL/Schema first leads to better message design • Web Services is a distributed technology, but it’s not a binary distributed technology • WSDL/Schema first puts the design of the interface first, which is a traditional best practice of distributed programming
  • 13. 1 - Schema is More Descriptive  Data types in C# and Java are limited in nature and descriptive only in code  XML Schema types are flexible and fully described in the schema file • We are creating a customer service based web service package • One simple method service is updateCustomer
  • 14.  The interface to update customer might look simple like this • Exception handling and packaging (namespaces for my .Net friends) is being ignored public boolean updateCustomer(Customer input) { return null; }
  • 15.  The Customer type being passed is a simple Data structure of an object • In Java a JavaBean, really just an encapsulated class public class Customer { private Address address; private java.lang.String firstName; private java.lang.String lastName; private int age; //...
  • 16.  The generated schema for that type might look something like the following <complexType name=quot;Customerquot;> <sequence> <element name=quot;addressquot; nillable=quot;truequot; type=quot;cust:Addressquot; /> <element name=quot;firstNamequot; nillable=quot;truequot; type=quot;xsd:stringquot;/> <element name=quot;lastNamequot; nillable=quot;truequot; type=quot;xsd:stringquot;/> <element name=quot;agequot; nillable=“true” type=quot;xsd:intquot; /> </sequence> </complexType>
  • 17.  This mapping is fine, but what if you want to control, or limit your clients a bit more <complexType name=quot;Customerquot;> <sequence> <element name=quot;addressquot; nillable=quot;truequot; type=quot;cust:Addressquot; /> <element name=quot;firstNamequot; nillable=quot;truequot; type=quot;xsd:stringquot;/> <element name=quot;lastNamequot; nillable=quot;truequot; type=quot;xsd:stringquot;/> <element name=quot;agequot; type=quot;xsd:intquot; minOccurs=“0” /> </sequence> </complexType>
  • 18.  In Schema we can make many changes to the types, easily • Limit Strings to enumerations (State Names) • Limit integers to ranges (positive int or 1-31) • Make elements optional • Require one of two options (home or work address) • Limit strings to some pattern (email, id numbers)  These types of limits in a programming language are traditionally in the implementation not the interface
  • 19.  Delivering these limitations to the client of our web services is most easily done via schema  When a schema is delivered to the client it should not change without notification • We will look at changing schema later in the lecture  These simple changes are commonly done by hand to the schema, not in the code with an attribute or any other in code modifier
  • 20. 2 - Your Language is not alone!  When creating a web service you share the WSDL and Schema • In the past you might have shared compiled code, or source code to enable a client • The client now can be created knowing only the WSDL and supporting Schema  This means your language is no longer central and should not be treated as the center (except to you the developer)
  • 21.  Because you are not sharing the compiled code, the client know less about your system • This loose coupling can be a tremendous advantage • Loose coupling enables many different types of clients  What the client does know about the web service is the WSDL and supporting Schema • This makes the schema central, its versions should be tracked • You will need to ensure that all clients have the same schema (or at least know the differences) • Relying on a tool to auto-generate the schema puts you at the mercy of a change in that tool set
  • 22.  Clients are not the only possibility for heterogeneous environments • You might create a type of object in Java that will later need to be replicated in .Net • If your environment is not mixed now it might become mixed as your company evolves • Plan to reuse the definition of a “Customer” created in .Net even when coding Java • Ending up with mirror for each language will force you to choose a “master” definition
  • 23.  To ensure good reuse of types they must be shared using some schema not in code • Global definitions of types should be shared by all portions of the enterprise • Entity types are perfect examples, why create a Java and a C# version of the “Customer” when one should suit • Message standards type are another perfect example, creating a standard set of info passed with every message (for audits, tracking etc.)
  • 24. 3 – Change happens in Schema  It seems that all technologies are released with little thought to change • Viewing complex topics is much easier if you don’t need to add the forth dimension into it • Failures in your enterprises ability to adapt or version easily has caused many a company much pain (2-Tier client server) • Changes need to be managed in shared resources
  • 25.  If your code is central that is what you naturally track for version control • The WSDL becomes a byproduct of the deployment and might change at any time • You should know an keep track of WSDL/Schema changes so clients troubles might be tracked to a single WSDL or Schema • Code first thinking will let you ignore Schema/WSDL versions (dangerous)
  • 26.  Taking a look at an example we might be able to see this better  Working with the simple customer example we started with the following definition of a customer public class Customer { private Address address; private java.lang.String firstName; private java.lang.String lastName; private int age; //...
  • 27.  Assume the web service is up and running, but we want to change it, adding a middle name field • A simple change in code is easy as pie public class Customer { private Address address; private java.lang.String firstName; private java.lang.String middleName; private java.lang.String lastName; private int age; //...
  • 28.  Being code first developers we deploy this to the web site but all is not well • The simple addition of a middleName will cause a change in the WSDL (in the schema actually) • The Schema will contain one more required field • This required field will not be sent by any of the clients previously using the web service • This change will typically cause all existing client’s messages to fail forcing updates of all clients (the dreaded ripple effect)
  • 29.  Below is the new Schema for reference <schema elementFormDefault=quot;qualifiedquot; targetNamespace=quot;http://domain/axis/services/customerquot; xmlns=quot;http://www.w3.org/2001/XMLSchemaquot;> <complexType name=quot;Customerquot;> <sequence> <element name=quot;addressquot; nillable=quot;truequot; type=quot;cust:Addressquot; minOccurs=quot;0quot;/> <element name=quot;firstNamequot; nillable=quot;truequot; type=quot;xsd:stringquot;/> <element name=“middleNamequot; nillable=quot;truequot; type=quot;xsd:stringquot;/> <element name=quot;lastNamequot; nillable=quot;truequot; type=quot;xsd:stringquot;/> <element name=quot;agequot; type=quot;xsd:intquot; /> </sequence> </complexType>
  • 30. Handle Versioning  What is key to our understanding of version is how namespaces work and what kind of change you are creating  The namespace of a schema is a URI, not necessarily an actual location (URL), rather a string you don’t plan on changing(URN)  Types defined in a URN should not change so much as to break existing implementations
  • 31.  I like to break changes down into two different categories • Backwards Compatible • Non-Backwards Compatible  Backwards compatible changes should not force the client to change with your web service • Adding optional elements is backwards compatible • Backwards compatible changes allow a client to change when the client schedule allows • Not forcing change serves to make our client/service relationship less tightly coupled
  • 32.  Backwards compatible change <schema elementFormDefault=quot;qualifiedquot; targetNamespace=quot;http://domain/services/customerquot; xmlns=quot;http://www.w3.org/2001/XMLSchemaquot;> <complexType name=quot;Customerquot;> <sequence> <element name=quot;addressquot; nillable=quot;truequot; type=quot;cust:Addressquot; minOccurs=quot;0quot;/> <element name=quot;firstNamequot; nillable=quot;truequot; type=quot;xsd:stringquot;/> <!-- Middle name optional to be backwards compatible --!> <element name=“middleNamequot; nillable=quot;truequot; type=quot;xsd:string“ minOccurs=“0”/> <element name=quot;lastNamequot; nillable=quot;truequot; type=quot;xsd:stringquot;/> <element name=quot;agequot; type=quot;xsd:intquot; /> </sequence> </complexType>
  • 33.  Non-Backwards compatible changes are more profound in there impact • Clients need to change to use the new service • We still don’t want to inflict our schedule on all clients  To manage these changes we introduce a new URI and a new Schema • Schema URIs commonly carry version names • Services might support both versions for some reasonable length of time
  • 34.  The new Schema might look like below <schema elementFormDefault=quot;qualifiedquot; targetNamespace=quot;http://domain/services/customer/V2_0quot; xmlns=quot;http://www.w3.org/2001/XMLSchemaquot;> <complexType name=quot;Customerquot;> <sequence> <element name=quot;addressquot; nillable=quot;truequot; type=quot;cust:Addressquot; minOccurs=quot;0quot;/> <element name=quot;firstNamequot; nillable=quot;truequot; type=quot;xsd:stringquot;/> <element name=“middleNamequot; nillable=quot;truequot; type=quot;xsd:stringquot;/> <element name=quot;lastNamequot; nillable=quot;truequot; type=quot;xsd:stringquot;/> <element name=quot;agequot; type=quot;xsd:intquot; /> </sequence> </complexType>
  • 35.  Support of changing URIs seems more appropriately handled in Schema than in source code  The change of a global type must be handled with care • By changing your customer are you influencing all your clients and fellow service developers  Version handling of source code is well understood • This is fine, but clients don’t have access to your version control software • Other developers might not be using the same language
  • 36. 4 – The Web Service is more than the method  Headers have and continue to develop in web services to add powerful features • Headers are typically used to pass metadata related to the message • Some headers are required to meet exterior standard (such as how to handle security) • Some headers might be added strictly for your company (tracking or auditing information)
  • 37.  Most packages handle headers using an “Intercepting Filter” • The headers are processed before they land on the “method” freeing up the method to focus on the actual business • Headers can be read and handled in the service as well • Axis calls these “Handlers” .Net calls them “Web Extensions” • The advantage is that they can be added or removed and the service method is blissfully free of that knowledge
  • 38.  The problem is that the code or method is blissfully unaware of the intercepting filter • It is good to pass required (and optional) header info to the client which means a change to WSDL • If the method is being used to generate the WSDL we will need to add more info to correctly generate the WSDL (one more doohickey) • The Web Service is now not just the “method”, but the method and surrounding filters  The idea that our web service is “Just a Method” is fundamentally wrong • The web service is all things that make a WSDL/Schema document work properly
  • 39. 5 – SOAP Faults are too limited  Error handling is another essential fact of any “real” project • Like versioning error handling is usually not fully thought out with the first release  SOAP has a built in error reporting technique called a SOAP Fault • To understand why this is inadequate we need to look at its limits
  • 40.  Taking a quick look at SOAP Faults we can quickly see that they are good, but limited • A SOAP Fault consists of only four things: code, string, actor, and detail (which is flexible) • The SOAP Fault codes include versionMismatch, MustUnderstand, Client, and Server • The SOAP Fault has to be a child of the <Body> so it can’t appear inside another tag • The SOAP Fault is sent instead of the usual output
  • 41.  The SOAP Fault can contain information, but is a Boolean type of error reporting • The response is completely an error, or reports no error • This is an inflexible error return type  To handle more flexible error conditions it is common to add your own error types • These errors are typically optional • They can allow for partial success
  • 42.  To handle this more flexible error reporting you need to design a message with the possibility for error • Below we see a possible schema <element name=quot;addCustomerquot;> <complexType> <sequence> <element name=quot;inputquot; type=“itech:Error“ minOccurs=“0”/> <element name=quot;inputquot; type=quot;cust:Customer“ minOccurs=“0”/> </sequence> </complexType> </element>
  • 43.  Creating the correct schema to handle this error condition is actually very simple • Creating that same schema with a method first technique would be more complex • Decisions on when to use the SOAPFault and when to use an optional error type is additional information needed when defining the method  What is really happening in this example is a move toward message design, not method design
  • 44. 6 – Standards are setup for WSDL not your language  Toolkits and companies are seeking interoperable solutions and the WS-I is a group that is successfully delivering standards • The WS-I is a group backed largely by MS and IBM that is further evolving interop issues • The WS-I “Basic Profile” is a standard that helps clear out many of the inconsistencies in SOAP and WSDL specs
  • 45.  When you work with your web services one of the best ways to guarantee interop is to follow the WS-I Basic Profile • The rule behind the Basic Profile are fairly extensive and will not be discussed here (I gave a talk on that) • Toolkits commonly support the basic profile, but you need to be careful when creating web services • Many default Web Services will not match the Basic Profile
  • 46.  Because it is very easy to create WS-I Basic Profile non-conformant web service, I have some advice • Use testing tools, the WS-I ships an ugly one with a few bugs, and you can buy tools (SOAP Scope is a good one) • Test WSDL, XML Schema and SOAP messages • You can’t rely on defaults, you will normally need to learn your API beyond the basics
  • 47.  If you test the WSDL and find an error fix it • If you edit the WSDL your changes will need to be reflected in the source code • If you end up editing the WSDL it is easier to just generate the service interface using the WSDL contraption provided by the toolkit • I find it easier to correct mistakes in the WSDL because it is directly related to the standards documentation • If you toolkit is producing perfect WSDL this might not be reason enough (see the other 5)
  • 48. Why Not WSDL/Schema First  I’ve attempted to lay out an organized set of why Schema is done first, but there is a downside as well • If there was no downside we would have no debate - this talk would be irrelevant • Method first seems to be a more common approach than WSDL/Schema first
  • 49.  For the downside I see four significant problems 1. Programmers are relatively uncomfortable with XML Schema 2. XML Schema itself is not the prettiest or simplest of technologies 3. Tools commonly stress programs and the procedural approach (for now anyway) 4. Finding Schema created by another team might be more difficult than finding an object
  • 50. Tips for WSDL First  If ended the talk discussing the negative side you might think that the WSDL first way is tedious or arduous, but it isn’t really that bad • If you properly separate out the XML Schema the WSDL file becomes very easy to work with • Creation of the Schema can be done with tools and edited by hand as needed  Let’s take a look at some best practices
  • 51. Store Schema Separately  Any Schema that might be reused by another web service should be stored separately • The WSDL file can use an import to bring the schema into the WSDL • The Schema can and should have a targetNamespace different than the WSDL file • Carefully organize the schema using the URIs • Some schema might be defined in the WSDL
  • 52.  The WSDL types section can include a simple schema import tag like below <wsdl:types> <xs:schema targetNamespace=quot;http://domain/group/serviceName/version/ quot; xmlns:xs=quot;http://www.w3.org/2001/XMLSchemaquot; xmlns:libPrefix=quot;http://domain/group/typeLibName/version/quot; <xs:import namespace=quot;http://domain/group/typeLibName/version/quot; schemaLocation=quot;typeLibName.xsdquot;/> </xs:schema> <wsdl:types>
  • 53. Include Versions in URI  The targetNamespace declared in the WSDL and all schema should include some version number • You can use dates, or numbers for more dynamic situations • By placing a version in the URN you have flexibility to change by creating a new definition • This suggestion is really an XML Schema best practice applied to a web service situation
  • 54. Organize and Share Schema  Finding other people’s schema can be made simpler through organization • Use the targetNamespace to represent a physical location to make it more intuitive to understand • With this rule goes another very simple one, prefer to reuse over rewriting types that can be shared (all groups don’t need a different definition of customer) • Similar types might created for separate groups to reduce the complexity of a type
  • 55. Use Template for WSDL  If all reusable types are stored in schema files, the WSDL document becomes simple • Message type can contain references to predefined types • Most WSDL document become very similar • Using a few templates or examples you can easily create WS-I compliant WSDL
  • 56. Compliance Check at Design Time  Early testing is a best practice in any development  Before creating a web service, test the WSDL and Schema for WS-I compliance • The WS-I ships more than one version of the testing tool (Java, C#) • A good tool is sold by Mindreef called SOAP Scope, an inexpensive but great tool • Tools for creating schema can be a great
  • 57. Review Schema Design  Internal Company Design standards can also be checked before creation of the service • At a minimum companies should setup naming conventions and namespace conventions to be followed • Other Schema best practices dealing with use of elements vs. complex types is beyond the scope of this lecture • An internal review can give XML Schema experts a chance to mentor developers reducing the Schema learning curve
  • 58. DEMONSTRATION Compliant Web Service WSDL Based Service (Optional)
  • 59. Conclusions  Changing from object design to message design is fundamentally what we are proposing  Nearly all reasons for WSDL first revolve around the fact the WSDL is the center of development • They are shared with clients and fellow developers  Not all teams need to move to WSDL first • If you are just getting started it might be appropriate to see some simple success first • If the client and all developers are using the same toolkit then method first is attractive • If you have nobody on your team that is familiar with schema, WSDL first is trouble
  • 60. Conclusions  If you are attempting to create a heterogeneous Web Service library that applies to multiple clients for the entire enterprise WSDL first should be considered  The choice of a toolkit or framework (.Net or Java or whatever) is secondary, they can both do WSDL/Schema first
  • 61. Continuing education  Learning Schema • http://www.w3schools.com/schema/default.asp • http://www.w3.org/TR/xmlschema-0/  Learning WSDL and SOAP • http://www.w3schools.com/wsdl/default.asp • http://searchwebservices.techtarget.com (various links) • http://www.w3schools.com/soap/default.asp  Testing tools • http://www- 106.ibm.com/developerworks/webservices/library/ws-wsitest/ • SOAP Scope http://www.mindreef.com/  ILT – www.intertechtraining.com
  • 62. Presentation Complete If time allows: questions Please visit www.intertechtraining.com
  • 63. Thank You

×