Preface

Chapter 1: Introduction
  1.1 About this Book
  1.2 Objectives of this Book
  1.3 Who this Book if For
  1.4 What this Book Does Not Cover
  1.5 Prerequisite Reading
  1.6 Supplementary Reading
  1.7 How this Book is Organized
    Part I: Fundamentals
    Part II: Service Contract Design
    Part III: Service Contract Versioning
    Part IV: Appendices
  1.8 Symbols, Figures, and Style Conventions
  1.9 Additional Information

Chapter 2: Case Study Background
  2.1 How Case Study Examples are Used
  2.2 Case Study Background: ActionCon
    History and Culture
    Technical Infrastructure
    Business Goals and Obstacles

Part I: Fundamental Service Contract Design
Chapter 3: SOA Fundamentals and Web Service Contracts
  3.1 Basic SOA Terminology
    Service-Oriented Computing
    Service-Orientation
    Service-Oriented Architecture (SOA)
    Service
    Service Models
    Service Composition
    Service Inventory
    Service-Oriented Analysis
    Service Candidate
    Service-Oriented Design
    Web Service
    Service Contract
    Service-Related Granularity
    Further Reading
  3.2 Service-Oriented Computing Goals and Web Service Contracts
    Increased Intrinsic Interoperability
    Increased Federation
    Increased Vendor Diversification Options
    Increased Business and Technology Domain Alignment
    Strategic Benefits
    Further Reading
  3.3 Service-Orientation and Web Service Contracts
    Standardized Service Contract
    Service Loose Coupling
    Service Abstraction
    Service Reusability
    Service Discoverability
    Service Composability
    Futher Reading
  3.4 SOA Design Patterns and Web Service Contracts
    Further Reading

Chapter 4: Anatomy of a Web Service Contract
  4.1 What is a Web Service Contract?
    Fundamental Structure
    Abstract and Concrete Descriptions
  4.2 The Parts of a Web Service Contract
    Primary Parts of the Abstract Description
    1. Port Type (Interface) Definition
    2. Operation Definition
    3. Message Definition
    4. Type Definition
    5. Policy Definition
    A Physical View of the Abstract Description
      WSDL 2.0 Changes to Physical View
    Primary Parts of the Concrete Description (Part I)
    1. Port Type (Interface) Binding Definition
    2. Operation Binding Definition
    3. Message Binding Definitions
    5. Policy Definition
    Primary Parts of the Concrete Description (Part II)
    1. Service Definition
    2. Port (EndPoint) Definition
    3. Address Definition
    4. Policy Definition
    How Parts of a Contract Relate to Each Other
    The Primary Parts of a Message
    1. Envleop
    2. Body
    3. Fault
    4. Header
  4.3 Technologies Used to Create Web Serivce Contracts
    Web SErvices Description Language (WSDL)
    XML Schema Definition Language (XML Schema)
    WS-Policy Language
    SOAP Language
    Technologies for the Abstract Description
    Technologies for Concrete Description
    The WS-I Basic Profile
  4.4 Guidelines for Using Web Service Contract Technologies
    Auto-Generation Tools
    Flexibility vs. Restrictiveness
    Modularity and Reuse
    Clarity and Ease of Processing

Chapter 5: A Plain English Guide to Namespaces
  5.1 Elements, Attributes, and Namespaces
    Namespaces and Elements
    Namespaces and Attributes
    Working with Namespaces
  5.2 Namespace Terminology
    Local Name
    Expanded Name
    Namespace Prefix
    Default Namespace
    Qualified Name
    Traget Namespace
  5.3 What's in a Name(space)?
    Industry Standard Namespaces
    Namespace and URL Encoding
    Namespaces and Actual URLs
  5.4 Namespace Syntax
    Declaring a Namespace Prefix
    The Default Namespace
    No Namespace
  5.5 Namespaces and Web Service Contracts
    Common Namespaces in the Web Service Contract
    Common Namespaces in the Message

Chapter 6: Fundamental XML Schema: Types and Message Structure Basics
  6.1 XML Schema Structure
  6.2 Elements and Attributes
    Elements vs. Types
    Elements vs. Attributes
    Global vs. Local Declarations
    Element Granularity
  6.3 Types
    What's a Content Model?
    Named vs. Anonymous Types
    Built-in Simple Types
    Types and Inheritance
    User-Define aSimple Types
    Complex Types
  6.4 Namespaces
    The Target Namespace
    Qualified and Unqualified Elments
    Namespaces and Schema Reuse
  Case Study Example
  6.5 Message Structures
  Case Study Exmple
    Repeating Element Containers
    Case study Example
      A Complete XML Schema Definition for the Purchase Order Service

Chapter 7: Fundamental WSDL Part I: Abstract Description Design
    What, No wsdl: Prefix?
    IRI vs. URI vs. URL vs. URN
  7.1 WSDL Definition and Documentation
    The definitions Element
    The Documentation Element
    Case Study Example
  7.2 Abstract Description Structure
  7.3 Type Definitions
    The types Element
  Case Study Example
    Embedded XML Schema Types
    Included XML Schema Types
  7.4 Message Definitions
    The message Element
    The part Element
  Case Study Example
  7.5 Operation Definitions
    The operation element
    Message Exchange Patterns(MEPs)
    The parameterOrder Attribute
    Operation Overloading
  Case Study Example
  7.6 Port Type Definition
    The portType Element
  7.7 A Complete Abstract Description
  Case Study Example

Chapter 8: Fundamental WSDL Part II: Concrete Description Design
  8.1 Concrete Description Strudture
  8.2 Binding Definition
    The binding Element
    Extensibility Elements
    The binding Element's transport Attribute
    The "Inheritance Rule"
    The soap11:operation Element's soa Action Attribute
    The soap11:binding and operation Element's style Attribute
    SOAP Extensibility Elements (and the use Attribute)
    Literal vs. Encoded
  Case Study Example
    Binding to SOAP 1.2
  Case Study Example
  8.3 Service and Port Definitions
    The Service and port Elements
  Case Study Example
  8.4 A Complete WSDL Definition ( Including the concrete Description)
    Case Study Example

Chapter 9: Fundamental WSDL 2.0: New Features and Design Options
  9.1 WSDL 2.0 Docuemnt Structure
    Elimination of the message Element
  9.2 Interface Definition
    The interface Element's extends Attribute
    The interface Element's styleDefault Attribute
    The wsdlx:safe Gobal Attribute
    The fault, infalut, and outfault Elements
    The pattern and message Label Attributes
  9.3 Service and Endpoint Definitions
  9.4 A Complete WSDL 2.0 Definition

Chapter 10: Fundamental WS-Policy: Assertions, Expressions, and Attachments
  10.1 Policy Structure
    New Namespaces and Prefixes
    Assertions, Expressions, and the Policy Element
    Assertion Instance #1
    Assertion Instance #2
  10.2 Composition Policies
    The ExactlyOne Element
    The wsp:all Element
    The wsp:optional Attribute
  10.3 Operator Composition Rules
    Idempotent Rule
    Commutative Rule
    Associative Rule
    wsp:All is Distributive Over wsp:ExactlyOne
    Empty Operators
    Equivalence
  10.4 Attaching Policies to WSDL Definitions
    Policy Attachment Points and Policyh Subjects
    The wsp:PolicyReference Element
    Embedded Attachments
  10.5 A Complete WSDL Definition with an Attached Policy Expression
  Case Study Example

Chapter 11: Fundamental Message Design: SOAP Envelope Structure, Fault Messages, and Header Processing
  What SOAp is not
  Case Study Background
  11.1 SOAP Message Structure
    The soap:Envelope Element
    The soap:Body Element
    The soap:Header Element
    The soap:Fault Element
  11.2 SOAP Nodes and Roles
  Case Study Example
  11.3 SOAP Header Blocks and Targeted Processing
    The soap:role Attribute
  Case Study Exmaple
    The soap:mustUnderstand Attribute
    The soap:relay Attribute
    Industry SOAP Header Block Examples
  11.4 SOAP Intermediaries
    Forwarding Intermediaries
    Active Intermediaries
  11.5 Fault Messages
    The SOAP Fault Vocabulary
    The soap:Code Element
    The soap:Detail Element
    SOAP Faults vs.WSDL Faults
    SOAP 1.1 Fault Elements and Values

Part II: Advanced Service Contract Design
Chapter 12: Advanced XML Schema Part I: Message Flexibility, Type Inheritance, and Composition
  12.1 Message Flexibility and Constraint Granularity
    Wildcards (xsd:any and xsd:anyAttribute)
    Extension Buckets
    Generic vs. Specific Elements
  Case Study Example
    Content Model Groups (xsd:choice, xsd:all, and xsd:sequence)
  12.2 Type Inheritance and Composition
    Emulating Class Inheritance (abstract and xsd:extenstion)
    Type Composition (xsd:group)
  12.3 Common CRUD Messages Types
    The "Chatty" Factor
    The Agnostic Factor
    Common Message Types
    Add Operation Messages
    Get Operation Messages
    Docuement-Centric Update Operation Messages
    Parameter-Centric Update Operation Messages
    Delete Operation Messages
    Message Type for Task Services

Chapter 13: Advanced XML Schema Part II: Reusability, Relational Design, and Industry Schemas
  13.1 Reusable Schema Design
    Reusing Schemas with the xsd:include Element
  Case Study Example
    Reusing Schemas with the xsd:import Element
  Case Study Example
  Case Study Example
  13.2 Representing Relationships in XML Schemas
    The xsd:key and xsd:keyref Elements
    Separate Relationship Element
  13.3 Narrative Content
  13.4 Incorporating Industry Schemas
    Reusing Types
  Case Study Example
    Adding Wildcards
  Case Study Example

Chapter 14: Advanced WSDL Part II: Modularization, Extensibility, MEPs, and Asynchrony
  14.1 Modularization Mechanisms
    The import Element (WSDL 1.1, 2.0)
  Case Study Example
    Split Concrete Description Sharing the Same Abstract Description
    The include Element (WSDL 2.0)
    How WSDL Documents are Merged
    Importing XML Schemas
  Case Study Example
    Multiple XML Schema Documents in a WSDL Document
  Case Study Example
    More About Interface Inheritance (WSDL 2.0)
  14.2 Extending the WSDL Language
    Extensibility of the SOAP Binding Extensions
    Custom WSDL Extensions and the wsdl:required Attribute
  14.3 Special Message Exchange Patterns
    What Happened to Outbound MEPs?
    The WSDL 2.0 Robust In-Only MEP
    WSDL 2.0 Custom MEPs
  Case Study Example
  14.4 Designing Asynchronous Operations
    The Asynchronous Web Service
    Polling
    Asynchronous Protocol Binding
    WS-Addressing
    Guidelines for Using Asynchronous Patterns
  14.5 WS-BPEL and WSDL
    WS-BPEL Extensions to WSDL
    Asynchronous Message Exchanges
    Correlation
  Case Study Example
    A WSDL Definition with WS-BPEL Extensibility Elements

Chapter 15: Advanced WSDL Part II: Message Dispatch, Service Instance Identification, and Non-SOAP HTTP Binding
  15.1 Extreme Loose Coupling with WSDL 2.0
    The #any Attribute
    Valid #any Messages
    Architectural Considerations
    WSDL #any and XML Schema xsd:any
  15.2 Message Dispatch Challenges
  Case Study Example
    Creating Unique Message Types
  Case Study Example
    HTTP SOAP Action Header
    WS-Addressing SOAP Action Header
  15.3 Messages that Point to Service Instances
    Service vs. Service Instance
    WSDL wsdlx and wsdli Extensibility Attributes
    Applications of this Feature
  15.4 Custom Header Blocks and Header Faults
    The Header and Header Fault Types
  Case Study Example
    A Custom Security Header Block
    Defining SOAP Header Blocks in WSDL 2.0
  15.5 Binding to HTTP Without SOAP
    HTTP as a Messaging Protocol
    Binding to HTTP with WSDL 1.1
  Case Study Example
    A WSDL 1.1 Definition Bound to HTTP
    Binding to HTTP with WSDL 2.0
  Case Study Example
    A WSDL 2.0 Definition Bound to HTTP
    Additional WSDL 2.0 HTTP Binding Features

Chapter 16: Advanced WS-Policy Part I: Policy Centralization and Nested, Parameterized, and Ignorable Assertions
  16.1 Reusability and Policy Centralization
    Policy Centralization and Policy Definitions
    Designing External WS-Policy Definitions
  Case Study Example
    Common Policy Centralization Challenges
  16.2 Nested and Parameterized Assertions
    Nested Policy Assertions
    Parameterized Assertions
  Case Study Example
    Nested and Parameterized WS-SecurityPolicy Assertions
  16.3 Ignorable Assertions
    wsp:Ignorable vs. wsp:Optional
    Using wsp:Ignorable to Target Consumers
  Case Study Example
    Adding an Ignorable Domain Policy Expression
    Considerations for Using Ignorable Assertions
  16.4 Concurrent Policy-Enabled Contracts

Chapter 17: Advanced WS-Policy Part II: Custom Policy Assertion Design, Runtime Representation, and Compatibility
  17.1 Designing Custom Policy Assertions
    Custom Assertion Schemas
    Custom Assertion Processing Logic
  Case Study Example
    Creating a Custom Assertion Schema
    Custom Assertion Attributes
    Custom Policy Assertion Checklist
  17.2 Maintaining Custom Policy Assertions
    Canonical Policy Vocabularies
    Assertion Description Documents
  17.3 Runtime Policy Representation
    Normalization of Policies
    Merging Policies
  17.4 Intersection and Consumer-Service Policy Compatibility
    Compatibility Levels
    Assertion Compatibility
    Alternative Compatibility

Chapter 18: Advanced Message Design Part I: WS-Addressing Vocabularies
  18.1 EPRs an MAPs
    Endpoint References (EPRs)
    Message Addressing Properties (MAPs)
  18.2 The EPR Vocabulary
    The wsa:EndpointReference Element
    The wsa:Address Element
    The wsa:ReferenceParamenters Element
    The wsa:Metadata Element
  18.3 MAP Vocabulary
    The wsa:To Element
    The wsa:From Element
    The wsa:ReplyTo Element
    The wsa:FaultTo Element
    The wsa:Action Element
    The wsa:MessageId Element
    The wsa:RelatesTo Element and the Relationship Type Attribute]
  Case Study Example
    A Complete Message with MAP Headers

Chapter 19: Advanced Message Design Part II: WS-Addressing Rules and Design techniques
  19.1 WS-Addressing Messaging Rules
    SOAP Header Structure
    Sending a Reply to a Message from an Endpoint
    MEP Requirements for MAP Elements
  Case Study Example
    Comparison of Different WS-Addressing Messages
  19.2 EPRs and WSDL Binding
    Embedding WSDL References Within an EPR
    Embedding EPRs in a WSDL Document
  Case Study Example
    Designing a Self-Descriptive Message
  19.3 WS-Addressing and Action Values
    Why is wsa:Action Always Required?
    The wsa:Action Element and WSDL
    The wsa:Action Element and HTTP
    A Reference Table for Action Values
  19.4 WS-Addressing SOAP Faults
  19.5 WS-Addressing Policy Assertions
    The wsam:Addressing Policy Assertion
    The wsam:AnonymousResponse Policy Assertion
    The wsam:NonAnonmousresponse Policy Assertion
  Case Study Example
    Adding a WS-Addressing Policy Assertion

Part III: Service Contract Versioning
Chapter 20: Versioning Fundamentals
  20.1 Basic Concepts and Terminology
    The Scope of a Version
    Fine and Coarse-Grained Constraints
  20.2 Versioning and Compatibility
    Backwards Compatibility
    Forwards Compatibility
    Compatible Changes
    Incompatible Changes
  20.3 Version Identifiers
  20.4 Versioning Strategies
    The Strict Strategy (New Change, New Contract)
    The Flexible Strategy (Backwards Compatibility)
    The Loose Strategy (Backwards and Forwards Compatibility)
    Summary Table

Chapter 21: Versioning WSDL Definitions
  21.1 Version Identifiers and WSDL Definitions
    Base Example
  21.2 Versioning Operation Definitions
    Adding a New Operation
    Renaming an Existing Operation
    Removing an Existing Operation
    Changing the MEP of an Existing Operation
    Adding a Fault Message to an Existing Operation
  21.3 Versioning Port Type Definitions
    Adding a Version Identifier to the Port Type
    Versioning with Multiple Port Types (Flexible)
    Using Prefixes to Associate Versions
  21.4 Versioning Concrete Descriptions
  21.5 WSDL Definitions and Forwards Compatibility
    Descreasing Operation Granularity Levels
    Using the WSDL 2.0 #any Attribute Value

Chapter 22: Versioning Message Schemas
  22.1 Basic Terms an Concepts
    Re-Introducing the "Component"
    Content Sets
    Versioning and the UPA Rule
    Base Example
  22.2 XML Schema and WSDL Target Namespaces
  22.3 Strict Versioning
    Adding a New Schema Component
    Removing an Existing Schema Component
    Renaming an Existing Schema Component
    Modifying the Constraint of an Existing Schema Component
  22.4 Flexible Schema Versioning (Using Optional Components)
    Adding a New Schema Component
    Removing an Existing Schema Component
    Renaming an Existing Schema Component
    Modifying the Constraint of an Existing Schema Component
  22.5 Loose Schema Versioning (Using Wildcards)
    Adding a New Schema component
    Removing an Existing Schema Component
    Renaming an Existing Schema Component
    Modifying the Constraint of an Existing Schema Component

Chapter 23: Advanced Versioning
  23.1 Versioning Policies
    Alternatives
    Optional Assertions
    Ignorable Assertions
    Different Endpoints
    Propagating Major Version Changes to WSDL Definitions
  23.2 Defining "Non-Ignorable" Unknown Elements
    Using a Custom mustUnderstand Attribute
    Using the soap:mustUnderstand Attribute
  23.3 Versioning and Schema Centralization
  23.4 Expressing Termination Information
    Ignorable Termination Assertions
    Mandatory Termination Assertions
    Terminating Individual Operations
  23.5 Working with Unknown Content
    Accept and Retain Unknown Content
    Using a mustRetain Flag
  23.6 Partial Validation
    Validation by Projection
  23.7 Versioning Message Instances
  23.8 Customizing a Versioning Strategy
    Custom Strategies for Schema Versioning
    Version Identification Conventions

Part IV: Appendices
Appendix A: Case Study Conclusion

Appendix B: How Technology Standards are Developed
  How Standards are Developed
  The Standards Development Process

Appendix C: Alphabetical Pesudo Schema Reference

Appendix D: Namespaces and Prefixes Used in this Book

Appendix E: SOA Design Patterns Related to this Book
  Canonical Expression
  Canonical Schema
  Canonical Versioning
  Compatible Change
  Concurrent Contracts
  Contract Centralization
  Contract Denormalization
  Decomposed Capability
  Decoupled COntract
  Distributed Capability
  Messaging Metadata
  Partial validation
  Policy Centralization
  Proxy Capability
  Schema Messaging
  Termination Notification
  Validation Abstraction
  Version Identification

About the Authors
Index
Web Service Contract Design and Versioning for SOA
Web Service Contract Design and Versioning
for SOA

by Thomas Erl, Anish Karmarkar, Priscilla Walmsley, Hugo Haas, Umit Yalcinalp, Canyang Kevin Liu, David Orchard, Andre Tost, James Pasley
Foreword by David Chappell