WSDL to C Mapping Revised Submission 1

1
WSDL to C MappingRevised Submission 1

• Rebecca Bergersen
• Principal Architect, Middleware Standards
• IONA Technologies
• MARS/05-04-08

2
Revision Overview (1)

• Sections 7.1 through 7.4 changed return values
  of types string and QName to const .
• preferable for performance reasons since it
  avoids creating a temporary copy of the string or
  QName in question.
• Section 7.5 complete replacement with extended
  explanation of conversions for WSDL ltimportgt,
  ltdefinitionsgt, lttypesgt, ltportTypegt, ltmessagegt,
  ltpartgt, ltoperationgt, ltbindinggt, ltportgt and
  ltservicegt elements, including namespace mapping
  rules, mapping of differing operation modes, and
  method, parameter and fault mappings.

3
Revision Overview (2)

• Section 7.6 complete replacement with
  discussion and specification of the generation of
  client stubs and server skeletons, and the
  physical file structure.
• Section 7.7 specification of mapping of
  namespaces, class, method, and field names, and
  C output files. Also provides memory
  management guidelines and an extended C example.

4
WSDL Conversion Overview

• Logical contract
• Must result in generation of C code
• Defines public interface
• Physical contract
• Do not necessarily require code to be generated
• Defines binding to transport and wire-level data
  format
• May be treated as run-time configuration
  parameters
• Two layers of generated C classes
• An abstract class derived directly from
  ltportTypegt containing pure virtual methods
  derived from its ltoperationgt elements
• Client proxy and server skeleton derived from
  above class

Logical Contract
Physical Contract
5
WSDL ltimportgt element

• Used to aggregate WSDL source from various files
• May appear anywhere within WSDL source file
• Concerns source management
• No direct bearing on C mapping
• Recommended that exception be raised if any
  ltimportgt element fails when processing WSDL
  source
• Recommended that circular references be detected
  and handled

6
WSDL ltdefinitionsgt element

• Root element of WSDL files
• Does not result in direct generation of code
• Is responsible for setting of namespace used
  within generated code

7
WSDL C Namespace

• Attribute targetNamespace
• Must be unique within its context
• Mapping rules specified in section 7.7.1.1
  Namespace
• If absent, then no namespace mapping is made
• WSDL Example
• ltdefinitions targetNamespacehttp//www.example.co
  m/test/this_namespace gt
• Resulting C namespace
• COM_EXAMPLE_TEST_THIS_NAMESPACE

8
WSDL lttypesgt and ltschemagt

• Enclose data type definitions
• WSDL prefers use of XML schema as canonical type
  system
• XSD therefore adopted for these specs
• XSD mandates use of ltschemagt tags within lttypesgt
• ltschemagt may contain targetNamespace attribute
• ltschemagt can also use xsdimport to import
  multiple namespaces
• Where two or more ltschemagt tags share same target
  namespace, the elements within are mapped to same
  C namespace
• Schema in ltschemagt tags mapped to C according
  to definitions in 7.3, Mapping for Simple XML
  Types and 7.4, Mapping for Complex XML Types

9
WSDL Elements
10
WSDL ltportTypegt element

• ltportTypegt describes abstract set of operations
  supported by one or more endpoints
• Each ltportTypegt element is mapped to unique
  abstract class.
• Required name attribute of ltportTypegt
  determines name of class.
• ltportTypegt contains ltoperationgt elements which
  are mapped as pure virtual methods of the class.
• Class used to derive client proxy and server stub
  classes containing necessary bindings

11
ltportTypegt example mapping

• WSDL
• ltportType nameTutorialAgt
• lt/portTypegt
• ltportType nameTutorialBExample
• lt/portTypegt
• C
• abstract class TutorialA
• public
• TutorialA()
• virtual TutorialA()
• // operations
• abstract class TutorialBExample
• public

12
WSDL Elements
13
WSDL ltmessagegt element

• Defines abstract structure and data types of
  messages used in communication between client and
  server
• Contains ltpartgt elements which map to method
  parameters
• ltMessagegt does not map directly to C
• Its a logical link between ltoperationgt element
  and ltpartgt elements of message
• Operation inputs and outputs reference the
  messages they expect
• Operation maps to method message parts map to
  parameters of method.

14
WSDL ltpartgt element

• ltpartgt is element of ltmessagegt
• Each ltpartgt maps to C method parameter
• Has name attribute that maps to the name of C
  parameter
• Has either an element or type attribute that maps
  to the C type of the parameter

15
WSDL Elements
16
WSDL ltoperationgt element

• Specifies an abstract operation, usually using
  the abstract messages defined in the WSDL
• Has unique name attribute which maps to the name
  of the corresponding C method
• Has optional parameterOrder attribute which, if
  present, determines the order of the parameter
  list of the corresponding C method.
• Usually used for RPC bindings
• May be one of four types
• One-way
• Request-Response
• Solicit-Response
• Notification

17
WSDL ltoperationgt element (contd)

• May be one of four types
• One-way
• Request-Response
• Solicit-Response
• Notification
• Types determine what child elements an
  ltoperationgt is allowed to have
• Request-Response or One-Way operations have
• Required ltinputgt element
• Optional ltoutputgt element
• If present, optional ltfaultgt element may be
  present
• Solicit-Response or Notification operations have
• Required ltoutputgt element
• Optional ltinputgt element
• If present, then optional ltfaultgt element may be
  present

18
Operation elements ltinputgt, ltoutputgt and ltfaultgt

• ltinputgt and ltoutputgt
• Required message attribute
• Value is QName of expected message
• Contributes to parameter list of operation
  through its parts
• Optional name attribute
• Value is NCName
• No effect on mapping
• ltfaultgt
• Required message attribute
• Determines data members (and hence get/set
  methods) of fault object
• Required name attribute
• Determines name of exception object

19
ltinputgt, ltoutputgt and ltfaultgt, contd

• If Request-Response or One-Way operation
• Used for messages from client to server
• Required ltinputgt element
• References message from client to server
• Optional ltoutputgt element
• Refers to a response message from server
• Optional ltfaultgt element
• Allowed if ltoutputgt element present
• References exception messages

20
ltinputgt, ltoutputgt and ltfaultgt (contd)

• If Solicit-Response or Notification
• Used for messages from server to client
• Required ltoutputgt element
• Reference message from server to client
• Optional ltinputgt element
• Refers to response message from client
• Optional ltfaultgt element
• Allowed if ltinputgt element present
• References exception message

21
ltoperationgt element mapping

• Maps to single C method in class corresponding
  to ltportTypegt element in which it is contained
• If WSDL definition of two or more operations,
  including name attribute, are identical
• One definition is ignored (recommended)
• OR second C method with an extended or mangled
  name is generated.
• All methods are virtual, to be subclassed by
  client proxy and server skeleton

22
ltoperationgt element mapping (contd)

• All methods return type void
• All values and references passed through C
  operation parameter list
• Method name is mapped from ltoperationgt name
  attribute
• All methods throw xmlException, regardless of
  whether user exception is defined in WSDL or not.
• Allows non-user exceptions to be thrown
• communications or other runtime exceptions
• All user-defined exceptions derived from
  XMLException thus can be thrown by this
  definition

23
Parameter types

• In, out and inout parameters used as in CORBA
• usage in ltinputgt and ltoutputgt self-evident
• When message common to both ltinputgt and ltoutputgt
  within same ltoperationgt, each ltpartgt maps to
  single inout parameter
• When two or more ltpartgt elements, each in
  different ltmessagegt elements, share same name and
  type attributes, and these messages are used
  independently in ltinputgt and ltoutputgt elements
  within the same operation, then the ltpartgt
  element maps to single inout parameter

24
Parameter types example

• WSDL
• ltmessage nameStockIDMessagegt
• ltpart nameexchangeSymbol typexsdstringgt
• ltpart namestockSymbol typexsdstringgt
• lt/messagegt
• ltmessage namestockQuoteMessagegt
• ltpart namestockSymbol typexsdstringgt
• ltpart namehigh typexsddecimalgt
• ltpart namelow typexsddecimalgt
• ltpart namelast typexsddecimalgt
• lt/messagegt
• ltportType gt
• ltoperation nameGetStockPricegt
• ltinput messageStockIDMessagegt
• ltoutput messageStockQuoteMessagegt
• lt/operationgt
• lt/portTypegt
• C

25
Fault Mapping

• User exceptions derived from XMLUserFaultExceptio
  n, which is derived from generic exception class
  XMLException
• Request-Response and Solicit-Response can define
  and raise exceptions through the ltfaultgt element.
• Mapped as C exception classes thrown by method
  it is defined in.

26
C Mapping user fault classes

• Mapped to WSDL namespace as defined earlier
• User fault class derived from class
  XMLUserFaultException
• ltmessagegt element to which ltfaultgt refers maps to
  the C fault class
• Name of C fault class is the value of the name
  attribute of the message
• Error code implementation dependent and exposed
  through inherited method error() defined in class
  Exception.

27
Exception Examples (1)

• WSDL
• ltmessage nameReadyMessagegt
• ltpart nameboolFlag typexsdbooleangt
• lt/messagegt
• ltportType nameStockQuoteEnginegt
• lt!-- one-way operation --gt
• ltoperation nameStartEnginegt
• ltinput messagetnsReadyMessagegt
• lt/operationgt
• lt/portTypegt
• C
• class StockQuoteEngine
• public
• virtual void StartEngine(const XMLBoolean
  boolFlag) throw (XMLException) 0

28
Exception Example (2)

• WSDL
• ltmessage nameVoidMessage /gt
• ltmessage nameReadyMessagegt
• ltpart nameboolFlag typexsdboolean /gt
• lt/messagegt
• ltportType nameStockQuoteEnginegt
• lt! Request-Response operation --gt
• ltoperation nameIsEngineReadygt
• ltinput messagetnsVoidMessage /gt
• ltoutput messagetnsReadyMessage /gt
• lt/operationgt
• lt/portTypegt
• C
• class StockQuoteEngine
• public

29
WSDL Elements
30
WSDL ltbindinggt element

• Defines message format and protocol details for
  operations and messages for particular portType
• Describes physical rather than logical aspect of
  WSDL
• Not mapped directly to C under this
  specification implementation-specific

31
WSDL ltportgt element

• Defines an individual endpoint by specifying a
  single address for a binding
• Describes a physical aspect of WSDL service
• Not mapped directly to C - assumed to be a
  runtime configuration element.

32
WSDL ltservicegt element

• Groups a set of related ports together to
  describe a service
• Describes a physical aspect of WSDL service
• Not mapped directly to C - assumed to be a
  run-time configuration element

33
Implementation and System APIs

• Assumed that an implementer will supply to
  service developer dynamic invocation capabilities
  and API to achieve this
• set of tools that process WSDL source and
  generate C source files
• run-time communications engine
• implements connectivity, binding options, other
  aspects of the physical WSDL contract
• supplies services to the developer at C level
• mechanism for dynamically defining new services
• discovers calls available through previously
  defined services
• Further proposed that existence of dynamic
  invocation API provides means to implement static
  invocations of WSDL services.

34
Physical files

• To realize tools component, implementer must, at
  minimum
• Generate header files containing abstract classes
  mapped from WSDL ltportTypegt definitions
• Generate a types header file containing C class
  mappings when either a lttypesgt section containing
  XML type definitions or a fault message exists
• Optionally, tools may generate
• object factories for creating, tracking, managing
  and destroying the objects mentioned.
• Client and server implementations of the WSDL
  service contract

35
Physical File Structure

Required
Optional
WSDL
Tools
.h
.h
.h
.h
.cpp
.cpp
.h
.cpp
Client stubs
Server skeleton
Logical Contract
Types
Type Factory
36
Communications Engine

• Responsible for implementing physical WSDL
  contract
• Responsible for supplying physical communications
  between client and server
• Supplies interface so DII and static invocation
  classes can connect to and communicate with
  system
• Engine class implementation-dependent, name not
  defined in this specification
• Referred to as CommsEngine in spec
• Recommended that it maps into namespace WSDL

37
Dynamic Invocation Interface

• Collection of methods and classes supplied as
  part of communications engine
• Allow application to construct and use WSDL
  services at runtime

38
DII operations

• (Typically in following order)
• Construct new ClientProxyBase object connected to
  communications engine
• Construct ClientOperation object from
  ClientProxyBase object. Set physical parameters
  of the operation (port, binding, etc.)
• Get input and output messages from
  ClientOperation object
• Construct Part objects that make up the input and
  output messages
• Add the Part objects to the input and output
  messages
• Set the values of the Part objects that make up
  the input message
• Invoke the operation
• Retrieve results of operation by examining values
  of the Part objects that make up the output
  message

39
Class ClientProxyBase

• Class is both starting point for dynamic
  invocation and base class for static
  implementation of web service clients
• Constructor uses pointer to communications engine
  as point of contact with communications
  infrastructure.

40
ClientProxyBase Definition

• C
• Namespace WSDL
• class ClientProxyBase
• public
• ClientProxyBase( XMLString wsdl,
• XMLQName service_name,
• XMLString port_name,
• CommsEngine )
• ClientProxyBase( XMLString wsdl,
• XMLQName service_name,
• CommsEngine )
• virtual ClientProxyBase()
• virtual Port get_port()
• virtual ClientServices get_service()
• virtual ClientOperation create_operation(
• const XMLString operation_name) throw
  (XMLException)
• const XMLString get_wsdl_location()

41
Classes Operation, ClientOperation

• C
• namespace WSDL
• class Operation
• public
• Operation(Port , const WSDLPort )
• virtual Operation()
• virtual Port get_port()
• class ClientOperation public Operation
• public
• virtual ClientOperation()
• virtual const XMLString get_name()
  const
• virtual WritableMessage
  get_input_message()
• virtual ReadableMessage
  get_output_message()
• virtual void invoke() throw
  (XMLException)

42
Static Client Proxy and Server Skeleton

• Tools Implementer may provide automatic
  generation of client proxy and server skeleton
  classes. If not, developer must create these
  classes.
• If implementer supplies DII functionality,
  logical approach would be to use that API to
  implement static classes described herein.

43
Classes of a static invocation

44
Client Proxy

• Must inherit from abstract portType class
  described earlier and implement all abstract WSDL
  operation methods
• Must also inherit from class ClientProxyBase
• Brings methods for obtaining and controlling
  physical aspects of WSDL contract (port and
  binding details)
• Client class named using class name of portType
  with string Client appended
• A portType-derived class named PortType maps to
  client class named PortTypeClient, e.g.

45
Client Proxy example

• C
• namespace PortTypeNamespace
• class PortTypeClient public PortType, public
  WSDLClientProxyBase
• public
• PortTypeClient(XMLString wsdl,
• XMLQName service_name,
• XMLString port_name,
• CommsEngine 0)
• PortTypeClient(XMLString wsdl,
• XMLQName service_name,
• CommsEngine 0)
• virtual PortTypeClient()
• // Include all abstract methods of class
  PortType as non-abstract
• // methods here.

46
StockQuoteEngine WSDL

• ltdefinitions targetNameSpacehttp//www.example.co
  m/stockquote.wsdl gt
• ltmessage nameStockIDMessagegt
• ltpart namestockSymbol typexsdstring /gt
• lt/messagegt
• ltmessage namestockQuoteMessagegt
• ltpart namestockSymbol typexsdstring /gt
• ltpart namehigh typexsddecimal /gt
• ltpart namelow typexsddecimal /gt
• ltpart namelast typexsddecimal /gt
• lt/messagegt
• ltportType nameStockQuoteEnginegt
• ltoperation nameGetStockQuotegt
• ltinput nameStockSymbol
  messageStockIDMessage /gt
• ltoutput nameStockQuote
  messageStockQuoteMessage /gt
• ltfault nameUnknownStockID
  messagetnsStockQuoteIDMessage /gt
• lt/operationgt
• lt/portTypegt

47
Client StockQuoteEngine Proxy C

• namespace COM_EXAMPLE_STOCKQUOTE_WSDL
• class StockQuoteEngineClient public
  StockQuoteEngine, public WSDLClientProxyBase
• public
• StockQuoteEngineClient(XMLString wsdl,
• XMLQName service_name,
• XMLString port_name,
• WSDLCommsEngine
  CommsEngine 0)
• StockQuoteEngineClient(XMLString wsdl,
• XMLQName service_name,
• WSDLCommsEngine
  CommsEngine 0)
• virtual StockQuoteEngineClient()
• virtual void GetStockQuote(XMLString
  stockSymbol,
• XMLDecimal
  high,
• XMLDecimal
  low,
• XMLDecimal
  last) throw (XMLException)

48
Namespace mapping rules

• WSDL namespace is represented by a URI
• Example URI http//www.example.com/soapinterop
• Remove schema and from beginning of URI
• Schema http and urn
• Parse remaining string into list of strings using
  / and as separators. Treat consecutive
  separators as single separator
• www.example.com, soapinterop.wsdl
• For each string result, unescape each escape
  sequence octet
• www.example.com, soapinterop.wsdl

49
Namespace mapping rules (contd)

• Parse internet domain name in first component
• www not considered part of internet domain
  name, so must be dropped
• Internet domain name is reversed, component by
  component
• If first component does not contain a top-level
  domain name (com, gov, net, org, edu, for
  example) or one of English two-letter country
  identifier codes (see ISO Standard 3166, 1981)
  this step must be skipped.
• com, example, soapinterop.wsdl

50
Namespace mapping rules (contd)

• Convert each string in list to uppercase
• COM, EXAMPLE, SOAPINTEROP.WSDL
• If string component contains a hyphen or other
  special character, convert it to an underscore.
• If resulting component is keyword, append
  underscore to it.
• If resulting component starts with a digit or any
  other disallowed identifier initial character,
  prefix an underscore to component
• COM, EXAMPLE, SOAPINTEROP.WSDL
• Concatenate list of strings using _ as
  separating character to produce namespace name.
• Namespace COM_EXAMPLE_SOAPINTEROP_WSDL

51
Class Name Mapping

• portType name maps to C class name
• Schema complex type name maps C class name
• WSDL operation name maps to C method name
• WSDL fields would map to private members, so
  mappings not defined by this specification.
• Recommend WSDL fields map to C class member
  with name var_fieldName

52
C Type Output Files

• Mapping produces number of type definition and
  stub files from wsdl contract.
• Named according to portType name. If WSDL
  contract specifies more than one portType, code
  is generated for each one.
• Type definition files
• WSDLFileName_wsdlTypes.h and WSDLFileName_wsdlType
  s.cxx define the complex datatypes defined in
  WSDL file, if any.
• SchemaFileName_xsdTypes.h and SchemaFileName_xsdTy
  pes.cxx define the complex datatypes defined in
  the import schema file, if any.

53
C Service definition, server skeleton, client
proxy output files

• Service definition
• portTypeName.h defines the super class used to
  implement client and server
• Server skeleton
• portTypeNameServer.h and portTypeNameServer.cxx
  are the server skeleton code implementing the
  service defined in the contract
• Client proxy
• portTypeNameClient.h and portTypeNameClient.cxx
  are the client stub code for implementing a
  client to use the service defined by the contract.

54
Memory Management

• Principles adhered to by this specification
• Client code must allocate, normally on the stack,
  all parameters used for server calls
• Server code must copy allocated parameters if it
  needs local copies
• Assignment operators and copy constructors which
  perform deep object copies should be defined
  where appropriate
• Nested complex types should recursively allocate
  and deallocate memory.
• Discussion of memory considerations for complex
  types unchanged from original

55
Extended C Example

• Provides complex WSDL file and the types and
  service files generated from it according to the
  rules provided in specification.
• Too unwieldy for slide presentation

56
Work Remaining

• Complete TBDs, Check Thiss
• Resolve broken cross-references
• Replace illustrations with non-hand-drawn
  examples
• Define and describe several static and dynamic
  invocation classes
• Define and discuss contexts, object factories and
  interceptors