sca client and implementation model cpp-v100

8/6/2019 SCA Client and Implementation Model Cpp-V100

1/70

i

SSSCCCAAA SSSeeerrrvvviiiccceee CCCooommmpppooonnneeennntttAAA rrrccchhhiiittteeeccctttuuurrreee

Client and Implementation Model Specification

for C++

SCA Version 1.00, March 21 2007

Technical Contacts: Andrew Borley IBM Corporation

David Haney Rogue Wave Software

Oisin Hurley IONA Technologies

Todd Little BEA Systems, Inc.

Brian Lorenz Sybase, Inc.

Conor Patten IONA Technologies

Pete Robbins IBM Corporation

Colin Thorne IBM Corporation


2/70

SCA Service Component Architecture

SCA Client and Implementation Model for C++ ii March 2007

Copyright Notice

Copyright BEA Systems, Inc., Cape Clear Software, International Business Machines Corp, Interface21, IONA

Technologies, Oracle, Primeton Technologies, Progress Software, Red Hat, Rogue Wave Software, SAP AG.,

Siemens AG., Software AG., Sun Microsystems, Inc., Sybase Inc., TIBCO Software Inc., 2005, 2007. All rightsreserved.

License

The Service Component Architecture Specification is being provided by the copyright holdersunder the following license. By using and/or copying this work, you agree that you have read,

understood and will comply with the following terms and conditions:

Permission to copy, display and distribute the Service Component Architecture Specificationand/or portions thereof, without modification, in any medium without fee or royalty is herebygranted, provided that you include the following on ALL copies of the Service Component

Architecture Specification, or portions thereof, that you make:

1. A link or URL to the Service Component Architecture Specification at this location:

http://www.osoa.org/display/Main/Service+Component+Architecture+Specifications

2. The full text of the copyright notice as shown in the Service Component ArchitectureSpecification.

BEA, Cape Clear, IBM, Interface21, IONA, Oracle, Primeton, Progress Software, Red Hat, RogueWave, SAP, Siemens AG., Software AG., Sun Microsystems, Sybase, TIBCO (collectively, the

Authors) agree to grant you a royalty-free license, under reasonable, non-discriminatory terms

and conditions to patents that they deem necessary to implement the Service ComponentArchitecture Specification.

THE Service Component Architecture SPECIFICATION IS PROVIDED "AS IS," AND THE AUTHORSMAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS

SPECIFICATION AND THE IMPLEMENTATION OF ITS CONTENTS, INCLUDING, BUT NOT LIMITEDTO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-

INFRINGEMENT OR TITLE.

THE AUTHORS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR

CONSEQUENTIAL DAMAGES ARISING OUT OF OR RELATING TO ANY USE OR DISTRIBUTION OF

THE Service Components Architecture SPECIFICATION.
http://www.osoa.org/display/Main/Service+Component+Architecture+Specificationshttp://www.osoa.org/display/Main/Service+Component+Architecture+Specificationshttp://www.osoa.org/display/Main/Service+Component+Architecture+Specifications


3/70


SCA Client and Implementation Model for C++ iii March 2007

The name and trademarks of the Authors may NOT be used in any manner, including advertisingor publicity pertaining to the Service Component Architecture Specification or its contents

without specific, written prior permission. Title to copyright in the Service ComponentArchitecture Specification will at all times remain with the Authors.

No other rights are granted by implication, estoppel or otherwise.

Status of this DocumentThis specification may change before final release and you are cautioned against relying on thecontent of this specification. The authors are currently soliciting your contributions and

suggestions. Licenses are available for the purposes of feedback and (optionally) forimplementation.

IBM is a registered trademark of International Business Machines Corporation in the United

States, other countries, or both.

BEA is a registered trademark of BEA Systems, Inc.

Cape Clear is a registered trademark of Cape Clear Software

IONA and IONA Technologies are registered trademarks of IONA Technologies plc.

Oracle is a registered trademark of Oracle USA, Inc.

Progress is a registered trademark of Progress Software Corporation

Primeton is a registered trademark of Primeton Technologies, Ltd.

Red Hat is a registered trademark of Red Hat Inc.

Rogue Wave is a registered trademark of Quovadx, Inc

SAP is a registered trademark of SAP AG.

SIEMENS is a registered trademark of SIEMENS AG

Software AG is a registered trademark of Software AG

Sun and Sun Microsystems are registered trademarks of Sun Microsystems, Inc.

Sybase is a registered trademark of Sybase, Inc.

TIBCO is a registered trademark of TIBCO Software Inc.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United

States, other countries, or both.

Other company, product, or service names may be trademarks or service marks of others.


4/70


SCA Client and Implementation Model for C++ iv March 2007

Table of Contents

Copyright Notice ............................................................................................................... iiLicense............................................................................................................................ iiStatus of this Document.....................................................................................................iii

Table of Contents............................................................................................................. iv

1. Client and Implementation Model .............................................................................. 11.1. Introduction........................................................................................................... 1

1.1.1. Use of Annotations ........................................................................................... 11.2. Basic Component Implementation Model .................................................................... 1

1.2.1. Implementing a Service .................................................................................... 11.2.2. Conversational and Non-Conversational services................................................... 51.2.3. Component Implementation Scopes.................................................................... 51.2.4. Implementing a Configuration Property ............................................................... 71.2.5. Component Type and Component ....................................................................... 81.2.6. Instantiation.................................................................................................. 10

1.3. Basic Client Model................................................................................................. 101.3.1. Accessing Services from Component Implementations......................................... 101.3.2. Accessing Services from non-SCA component implementations............................. 111.3.3. Calling Service Methods .................................................................................. 12

1.4. Error Handling...................................................................................................... 121.5. Conversational Services......................................................................................... 13

1.5.1. Conversational Client ...................................................................................... 141.5.2. Conversational Service Provider ....................................................................... 141.5.3. Methods that End the Conversation................................................................... 161.5.4. Passing Conversational Services as Parameters .................................................. 161.5.5. Conversation Lifetime Summary....................................................................... 171.5.6. Application Specified Conversation IDs .............................................................. 171.5.7. Accessing Conversation IDs from Clients ........................................................... 18

1.6. Asynchronous Programming ................................................................................... 181.6.1. Non-blocking Calls.......................................................................................... 181.6.2. Callbacks ...................................................................................................... 19

1.7. C++ API.............................................................................................................. 231.7.1. Reference Counting Pointers ............................................................................ 231.7.2. Component Context........................................................................................ 24


5/70


SCA Client and Implementation Model for C++ v March 2007

1.7.3. ServiceReference ........................................................................................... 251.7.4. SCAException ................................................................................................ 261.7.5. SCANullPointerException ................................................................................. 271.7.6. ServiceRuntimeException ................................................................................ 271.7.7. ServiceUnavailableException............................................................................ 271.7.8. NoRegisteredCallbackException........................................................................ 271.7.9. ConversationEndedException ........................................................................... 281.7.10. MultipleServicesException................................................................................ 28

1.8. C++ Annotations.................................................................................................. 281.8.1. Interface Header Annotations........................................................................... 291.8.2. Implementation Header Annotations ................................................................. 31

1.9. WSDL to C++ and C++ to WSDL Mapping................................................................ 352. Appendix 1 .......................................................................................................... 36

2.1. Packaging............................................................................................................ 362.1.1. Composite Packaging...................................................................................... 363. Appendix 2 .......................................................................................................... 38

3.1. Types Supported in Service Interfaces ..................................................................... 383.1.1. Local service ................................................................................................. 383.1.2. Remotable service.......................................................................................... 384. Appendix 3 .......................................................................................................... 39

4.1. Restrictions on C++ header files ............................................................................. 395. Appendix 4 .......................................................................................................... 40

5.1. XML Schemas....................................................................................................... 405.1.1. sca-interface-cpp.xsd...................................................................................... 405.1.2. sca-implementation-cpp.xsd ............................................................................ 416. Appendix 5 .......................................................................................................... 43

6.1. C++ to WSDL Mapping .......................................................................................... 436.2. Parameter and Return Type mappings ..................................................................... 44

6.2.1. Built-in, STL and SDO type mappings................................................................ 446.2.2. Binary data mapping ...................................................................................... 476.2.3. Array mapping............................................................................................... 476.2.4. Multi-dimensional array mapping...................................................................... 486.2.5. Pointer/reference mapping .............................................................................. 486.2.6. STL container mapping ................................................................................... 496.2.7. Struct mapping.............................................................................................. 50


6/70


SCA Client and Implementation Model for C++ vi March 2007

6.2.8. Enum mapping .............................................................................................. 516.2.9. Union mapping .............................................................................................. 526.2.10. Typedef mapping ........................................................................................... 526.2.11. Pre-processor mapping ................................................................................... 526.2.12. Nesting types ................................................................................................ 526.2.13. SDO mapping ................................................................................................ 546.2.14. void* mapping............................................................................................... 546.2.15. User-defined types (UDT) mapping ................................................................... 546.2.16. Included or Inherited types.............................................................................. 55

6.3. Namespace mapping ............................................................................................. 556.4. Class mapping...................................................................................................... 566.5. Method mapping................................................................................................... 59

6.5.1. Default parameter value mapping..................................................................... 596.5.2. Non-named parameters and the return type ...................................................... 606.5.3. The void return type....................................................................................... 606.5.4. No Parameters Specified ................................................................................. 626.5.5. In/Out Parameters ......................................................................................... 626.5.6. Public Methods............................................................................................... 626.5.7. Inherited Public Methods ................................................................................. 636.5.8. Protected/Private Methods............................................................................... 636.5.9. Constructors/Destructors................................................................................. 636.5.10. Overloaded Methods ....................................................................................... 636.5.11. Operator overloading...................................................................................... 636.5.12. Exceptions .................................................................................................... 637. References........................................................................................................... 64


7/70


SCA Client and Implementation Model for C++ 1 March 2007

1. Client and Implementation Model12

1 .1 . I n t r o d u c t i o n 3This document describes the SCA Client and Implementation Model for the C++ programming4

language.5

6

The SCA C++ implementation model describes how to implement SCA components in C++. A7component implementation itself can also be a client to other services provided by other8

components or external services. The document describes how a C++ implemented component9gets access to services and calls their methods.10

11

The document also explains how non-SCA C++ components can be clients to services provided12by other components or external services. The document shows how those non-SCA C++13

component implementations access services and call their methods.14

151.1.1.Use of Annotations16

This document defines interface and implementation meta-data using annotations. The17

annotations are defined as C++ comments in interface and implementation header files, for18example:19

20

// @Scope(stateless)21

22

All meta-data that is represented by annotations can also be defined in .composite and23

.componentType side files as defined in the SCA Assembly Specification and the extensions24

defined in this specification. Component type information found in the component type file must25be compatible with any specified annotation information.26

27

28

1 .2 . Bas ic Com ponen t I m p lemen t a t i on Model 29This section describes how SCA components are implemented using the C++ programming30

language. It shows how a C++ implementation based component can implement a local or31remotable service, and how the implementation can be made configurable through properties.32

33

A component implementation can itself be a client of services. This aspect of a component34implementation is described in the basic client model section.35

36

1.2.1.Imp lementing a Service37

A component implementation based on a C++ class (a C+ + i m p l e m e n t a t i on ) provides one or38

more services.39


8/70



40

The services provided by the C++ implementation have an interface which is defined using the41

declaration of a C++ abstract base class. An abstract base class is a class which has only pure42virtual methods. This is the service interface.43

44

The C++ class based component implementation must implement the C++ abstract base class45 that defines the service interface.46

47

The abstract base class for the service interface could be generated from a WSDL portType using48

the mapping defined in this specification.49

50

The following snippets show the C++ service interface and the C++ implementation class of a51

C++ implementation.52

53

Service interface.54

55

// LoanService interface56class LoanService {57public:58

virtualbool approveLoan(unsignedlong customerNumber,59unsignedlong loanAmount) = 0;60

};61

62

63

Implementation declaration header file.64

class LoanServiceImpl : public LoanService65{66public:67

LoanServiceImpl();68virtual ~LoanServiceImpl();69

70virtualbool approveLoan(unsigned long customerNumber,71

unsigned long loanAmount);72};73

7475

Implementation.76

77#include "LoanServiceImpl.h"78

79LoanServiceImpl::LoanServiceImpl()80{81

82}83LoanServiceImpl::~LoanServiceImpl()84{85


9/70


10/70



1.2.1 .1 . I m p l ement i ng a Rem otab l e Serv i ce 12

Remotable services are services that can be published through entry points. Published services13

can be accessed by clients outside of the composite that contains the component that provides14the service.15

16

Whether a service is remotable is defined by the interface of the service. This can be achieved by17

using the @Remotableannotation in the C++ interface header or by adding the r e m o t a b l e 18attribute to the C++ interface definition in the componentType file. The following snippet shows19

the annotation of the interface header:20

21

// LoanService interface22// @Remotable23class LoanService {24public:25


};28

29

The following snippet shows the component type for a remotable service:30

3132

3334

3536

37

The style of remotable interfaces is typically coarse gra inedand intended for l oose ly coupled38interactions. Remotable service Interfaces are not allowed to make use of method over l oad i ng .39

40Complex data types exchanged via remotable service interfaces must be compatible with the41marshalling technology that is used by the service binding. For example, if the service is going42

to be exposed using the standard web service binding, then the parameters must be Service43

Data Objects (SDOs) [1].44

45

Independent of whether the remotable service is called from outside a composite, or from46

another component in the same composite, the data exchange semantics are by -va l ue .47

48

Implementations of remotable services may modify input data during or after an invocation and49

may modify return data after the invocation. If a remotable service is called locally or remotely,50 the SCA container is responsible for making sure that no modification of input data or post-51

invocation modifications to return data are seen by the caller.52

53

An implementation of a remotable service can declare whether it allows pass by reference data54exchange semantics on calls to it, meaning that the by-value semantics can be maintained55

without requiring that the parameters be copied. The implementation of remotable services that56


11/70



allow pass by reference must not alter its input data during or after the invocation, and must not57

modify return data after invocation. The @Al low sPassByReferenceannotation on the58implementation header of a remotable service is used to either declare that calls to the whole59

interface or individual methods allow pass by reference. Alternatively this can be specified in60

SCDL using the allowsPassByReference=true attribute on the implementation.cpp element or61method definition.62

631.2.1 .2 . I m p l ement i ng a Loca l Serv i ce 64

A local service can only be called by clients that are part of the same composite as the65component that implements the local service. Local services cannot be published through entry66

points.67

68

Whether a service is local is defined by its interface. In C++ this is indicated by the service not69

being defined as r e m o t a b l e .70

71

The style of local interfaces is typically f i ne g ra i ned and intended for t i gh t l y coup l ed 72

interactions.7374

The data exchange semantics for calls to local services is by - re fe rence . This means that code75

must be written with the knowledge that changes made to parameters (other than simple types)76by either the client or the provider of the service can be seen by the other.77

78

1.2.2.Conversational and Non-Conversational services79

Service interfaces may be annotated to specify whether their contract is conversational, as80

described in the Assembly Specification [2]using the @Conversation annotation.81

A non-conversational service, the default when no annotation is specified, indicates that the82

service contract is stateless between requests. A conversational service indicates that requests to83the service are correlated.84

85

1.2.3.Component Implementation Scopes86

Component implementations can either manage their own state or allow the SCA runtime to do87

so. In the latter case, SCA defines the concept of implementation scope, which specifies the88

visibility and lifecycle contract an implementation has with the runtime. Invocations on a service89offered by a component will be dispatched by the SCA runtime to an implementation instance90

according to the semantics of its scope.91

92

Scopes may be specified using the scope attribute of the implementation.cpp or by specifying93 the @Scopeannotation on the service class in the implementation header.94

95

When a scope is not specified on an implementation class, the SCA runtime will interpret the96

implementation scope as stateless.97


12/70


13/70



remote request is always considered to be present, but the lifetime of the request is43

implementation dependent. For example, a timer event could be treated as a remote request.44

45

1.2.3 .3 . Com pos i te scope46

All service requests are dispatched to the same implementation instance for the lifetime of the47

containing composite. The lifetime of the containing composite is defined as the time it becomes48

active in the runtime to the time it is deactivated, either normally or abnormally.49

50

A composite scoped implementation may also specify eager initialization using the @EagerInit51annotation or the eagerInit=true attribute on the implementation.cpp element of a component52

definition. When marked for eager initialization, the composite scoped instance will be created53when its containing component is started.54

55

1.2.3 .4 . Conver sat ion scope56

A conversation is defined as a series of correlated interactions between a client and a target57

service. A conversational scope starts when the first service request is dispatched to an58

implementation instance offering the target service. A conversational scope completes after an59end operation defined by the service contract is called and completes processing or the60conversation expires (see 1.5.3 Methods that End the Conversation). A conversation may be61

long-running and the SCA runtime may choose to passivate implementation instances. If this62occurs, the runtime must guarantee implementation instance state is preserved.63

Note that in the case where a conversational service is implemented by a C++ implementation64that is marked as conversation scoped, the SCA runtime will transparently handle65

implementation state. It is also possible for an implementation to manage its own state. For66

example, a C++ implementation class having a stateless (or other) scope could implement a67conversational service.68

69

1.2.4.Imp lementing a Configuration Property70Component implementations can be configured through properties. The properties and their71types (not their values) are defined in the component type file or by using the @Property72

annotation on a data member of the implementation interface class. The C++ component can73retrieve the properties using the getProperties() on the ComponentContext class.74

75

The following code extract shows how to get the property values.76

#include "ComponentContext.h"77using namespace osoa::sca;78

79void clientMethod()80

{81 8283

ComponentContext context = ComponentContext::getCurrent();8485

DataObjectPtr properties = context.getProperties();8687

long loanRating = properties->getInteger(maxLoanValue);88


14/70



8990

}9192

1.2.5.Component Type and Component93

For a C++ component implementation, a component type must be specified in a side file. The94

component type side file must be located in the same composite directory as the header file for95 the implementation class.96

97

This Client and Implementation Model for C++ extends the SCA Assembly model [2] providing98

support for the C++ interface type system and support for the C++ implementation type.99

00

The following snippet shows a partial schema for the C++ interface element used to type01services and references of component types. Additional attributes are described later in this02

document.03

04

06

07

The interface.cpp element has the following attributes:08

header full name of the header file, including relative path from the composite root.09

This header file describes the interface10

class optional name of the class declaration in the header file, including any namespace11definition. If the header only contains one class then this class does not need to be12

specified.13

ca l lbackHeader optional full name of the header file that describes the callback14interface, including relative path from the composite root.15

cal lbackClass optional name of the class declaration for the call back in the callback16header file, including any namespace definition. If the header only contains one class then17

this class does not need to be specified18

r e m o t a b l e optional boolean value indicating whether the service is remotable or local.19The default is local.20

21

The following snippet shows a partial schema for the C++ implementation element used to22

define the implementation of a component. Additional attributes are described later in this23document.24

25

27

28

The implementation.cpp element has the following attributes:29


15/70



l i b ra r y name of the dll or shared library that holds the factory for the service30

component. This is the root name of the library. On Windows the suffix .dll will be31appended to this name. On linux the prefix lib and the suffix .so will be added.32

p a t h - optional path to the library which is relative to the root of the composite.33

header The name of the header file that declares the implementation class of the34

component. A path is optional which is relative to the root of the composite.35

class optional name of the class declaration of the implementation, including any36namespace definition. If the header only contains one class then this class does not need37

to be specified.38

scope optional attribute indicating the scope of the component implementation. The39

default is stateless.40

41

The following snippets show the C++ service interface and the C++ implementation class of a42C++ service.43

44



};50

51

Implementation declaration header file.52

class LoanServiceImpl : public LoanService53{54public:55

LoanServiceImpl();56virtual ~LoanServiceImpl();57

58virtualbool approveLoan(unsigned long customerNumber,59

unsigned long loanAmount);60};61

62

63

Implementation.64

65#include "LoanServiceImpl.h"66

67//////////////////////////////////////////////////////////////////////68// Construction/Destruction69

//////////////////////////////////////////////////////////////////////70LoanServiceImpl::LoanServiceImpl()71{72

73}74LoanServiceImpl::~LoanServiceImpl()75{76

77


16/70



}78//////////////////////////////////////////////////////////////////////79// Implementation80//////////////////////////////////////////////////////////////////////81bool LoanServiceImpl::approveLoan(unsignedlong customerNumber,82

unsignedlong loanAmount)83{84

85}86

87

The following snippet shows the component type for this component implementation.88

89

9091

9293

9495

96

The following snippet shows the component using the implementation.97

98

990102

0304


17/70



namespace osoa {23namespace sca {24

25class ComponentContext {26public:27

static ComponentContextPtr getCurrent();28virtual void * getService(const std::string& referenceName) const = 0;2930

}31}32

}33

34

The getService() method takes as its input argument the name of the reference and returns a35pointer to an object providing access to the service. The returned object will implement the36

abstract base class definition that is used to describe the reference.37

38

The following shows a sample of how the ComponentContext is used in a C++ component39

implementation. The getService() method is called on the ComponentContext passing the40reference name as input. The return of the getService() method is cast to the abstract base class41

defined for the reference.42

43

#include "ComponentContext.h"44#include "CustomerService.h"45

46using namespace osoa::sca;47

48void clientMethod()49{50

51unsignedlong customerNumber = 1234;52

53

ComponentContextPtr context = ComponentContext::getCurrent();5455

CustomerService* service =56(CustomerService* )context->getService("customerService");57

58short rating = service->getCreditRating(customerNumber);59

60}61

62

63

1.3.2.Accessing Services from non-SCA component implementations64

65

Non-SCA components can access component services by obtaining a ComponentContextPtr from66

the SCA runtime and then following the same steps as a component implementation as described67above.68

69

How an SCA runtime implementation allows access to and returns a ComponentContextPtr is not70defined by this specification.71


18/70



72

73

1.3.3.Calling Service Methods74

The previous sections show the various options for getting access to a service. Once you have75access to the service, calling a method of the service is like calling a method of a C++ class.76

If you have access to a service whose interface is marked as remotable, then on calls to methods77of that service you will experience remote semantics. Arguments and return are passed by -78

va l ue and you may get a ServiceUnavai lableExcept ion, which is a ServiceRuntimeException.79

80

81

1 .4 . Er r o r Hand l ing 82Clients calling service methods will experience business exceptions, and SCA runtime exceptions.83

84

Business exceptions are raised by the implementation of the called service method. They should85be caught by client invoking the method on the service.86

87

SCA runtime exceptions are raised by the SCA runtime and signal problems in the management88of the execution of components, and in the interaction with remote services. Currently the89

following SCA runtime exceptions are defined:90

SCAException defines a root exception type from which all SCA defined exceptions91derive.92

o SCANul lPointerExcept ion signals that code attempted to dereference a null93

pointer from a RefCountingPointer object.94

o Serv iceRunt imeExcept ion- signals problems in the management of the95

execution of SCA components.96

ServiceUnavai lableExcept ion signals problems in the interaction with97remote services. This extends ServiceRuntimeException. These are98

exceptions that may be transient, so retrying is appropriate. Any exception99that is a ServiceRuntimeException that is not a ServiceUnavailableException00

is unlikely to be resolved by retrying the operation, since it most likely01requires human intervention.02

Mul t ip leServ icesExcept ion signals that a method expecting03

identification of a single service is called where there are multiple services04defined. Thrown by ComponentContext::getService(),05

ComponentContext::getSelfReference() and06

ComponentContext::getServiceReference().07

Conversat ionEndedExcept ion signals that a method has been called on08a conversational service after the conversation was ended.09

NoRegisteredCal lbackExcept ion signals that a callback was invoked on10

a service, but a callback method was not registered.11

12

13


19/70



1 .5 . Conv ersa t i ona l Serv i ces 1415

16A frequent pattern that occurs during the execution of remotable services is that a conversation17

is started between the client of the service and the provider of the service. The conversation is a18series of method invocations that all pertain to a single common topic. For example, a19

conversation may be the series of service calls that are necessary in order to apply for a bank20loan.21

22

Conversations occur between a client and a target service. Consequently, requests originating23

from one client to multiple target services will result in multiple conversations. For example, if a24client A calls B and C, implemented by conversational scoped classes, two conversations will25

result, one between A and B and another between A and C. Likewise, requests flowing through26

multiple implementation instances will result in multiple conversations. For example, a request27originating from A to B to C will involve two conversations (A and B, B and C). In the previous28

example, if a request was then made from C to A, a third conversation would result (and the29implementation instance for A would be different than the one making the original request).30

31

Callback invocations will take place within the context of the conversation.32

33

The mechanics for maintaining and flowing conversational ids remotely is delegated to the34

particular binding the request is made through.35

36

For C++ component implementations, a service interface method may be decorated with the37

@EndConversation annotation to indicate to the SCA runtime that the current conversation38should be ended when the method is invoked. A conversation may also be ended by calling the39

endConversation () method on a service reference.40

The following is an example interface that has been annotated as being conversational:41

42

// LoanService interface43// @Remotable44// @Scope(conversation)45class LoanService {46public:47

virtualvoid apply(LoanApplication application) = 0;48virtualvoid lockCurrentRate(unsigned int termInYears) = 0;49// @EndConversation50virtualvoid cancelApplication( ) = 0;51virtualint getLoanStatus( ) = 0;52

};53

54

The cancelApplication() method is annotated to end the conversation.55

56


20/70



1.5.1.Conversational Client57

There is no special coding required by the client of a conversational service. The developer of58

the client knows that the service is conversational from the service interface definition. The59following shows an example client of the conversational service described above:60

61

#include "LoanApplicationClientImpl.h"62

#include "ComponentContext.h"63#include "LoanService.h"64#include LoanApplication.h65

66using namespace osoa::sca;67

68void LoanApplicationClientImpl::clientMethod( LoanApplication loanApp,69

unsigned int term )70{71

unsignedlong customerNumber = 1234;7273


// service is defined as member field: LoanService* service;76 service = (LoanService* )context->getService("loanService");7778

service->apply( loanApp );79service->lockCurrentRate( term );80

81}82

83bool LoanApplicationClientImpl::isApproved()84{85

return (service->getLoanStatus() == 1);86}87

88

89

1.5.2.Conversational Service Provider90

91

The provider of the conversational service also is not required to write special code to maintain92

state if the implementation is annotated as conversation scoped.93

94

There are a few capabilities that are available to the implementation of the service, but are not95

required. The conversation ID can be retrieved from the ServiceReference:96

ComponentContextPtr context = ComponentContext::getCurrent();97ServiceReferencePtr serviceRef = context->getSelfReference();98

std:string conversationID = serviceRef->getConversationID();9900

The type of the conversation ID is a std::string. Application generated conversation IDs may be01other complex types, as described in the section below titled "Application Specified Conversation02

IDs", that are serialized to a string.03

04


21/70



The service implementation class may also have an optional @Conversation annotation that has05

the following form:06

07

@Conversation(maxIdleTime="10 minutes",08maxAge="1 day",09singlePrincipal=false)10

11

The attributes of the @Conversation annotation have the following meaning:12

m a x I d l eTi m e - The maximum time that can pass between operations within a single13

conversation. If more time than this passes, then the container may end the14conversation.15

m a x A g e - The maximum time that the entire conversation can remain active. If more16

time than this passes, then the container may end the conversation.17

s ing lePr inc ipa l If true, only the principal (the user) that started the conversation has18authority to continue the operation.19

20

Alternatively the conversation attributes can be specified on the implementation definition using21the conversationMaxIdleTime , conversationMaxAge and conversationSinglePrincipal of22

implementation.cpp.23

24

The two attributes that take a time express the time as a string that starts with an integer, is25

followed by a space and then one of the following: "seconds", "minutes", "hours", "days" or26"years".27

28

Not specifying timeouts means that timeout values are defined by the implementation of the SCA29

runtime, however it chooses to do so.30

31

Here is an example implementation header file of a conversational service (the implementation32

file is not shown).33

34

// @Conversation(maxAge="30 days")35class LoanServiceImpl : public LoanService36{37public:38

virtualvoid apply(LoanApplication application);39virtualvoid lockCurrentRate(unsignedint termInYears);40virtualvoid cancelApplication(void);41

virtualint getLoanStatus();42};43

44

The Conversation attributes may also be specified in the element of a45

component definition:46

47


22/70



485051

52

53

1.5.3.Methods that End the Conversation54A method of a conversational service interface may be marked with an @EndConversation55annotation. This means that once this method has been called, no further methods may be56

called so both the client and the target may free up resources that were associated with the57conversation. It is also possible to mark a method on a callback interface (described later) as58

@EndConversation, in order for the service provider to be the party that chooses to end the59conversation. If a method is called after the conversation completes a60

ConversationEndedException (which extends ServiceRuntimeException) is thrown. This may also61

occur if there is a race condition between the client and the service provider calling their62respective @EndConversation methods.63

64

Alternatively the endConversation=trueattribute can be specified on a method in the65interface.cpp element of a service.66

67

68

1.5.4.Passing Conversational Services as Parameters69

The service reference which represents a single conversation can be passed as a parameter to70

another service, even if that other service is remote. This may be used in order to allow one71

component to continue a conversation that had been started by another.72

A service provider may also create a service reference for itself that it can pass to other services.73

A service implementation does this with a call to74

75ComponentContext::getSelfReference()76

77

or78

79

ComponentContext::getSelfReference(const std::string& serviceName)80

8182

The second variant, which takes a serviceName parameter, must be used if the component83

implements multiple services.84

85

This may be used to support complex callback patterns, such as when a callback is applicable86only to a subset of a larger conversation. Simple callback patterns are handled by the built-in87

callback support described later.88

89


23/70



1.5.5.Conversation Lifetime Summary90

91

Starting conversations92

Conversations start on the client side when one of the following occur:93

A service is located using ComponentContext::getService() or94

ComponentContext::getServices().95

A service reference is obtained using ComponentContext::getServiceReference() or96ComponentContext::getServiceReferences().97

98

Continuing conversations99

The client can continue an existing conversation, by:00

Holding the service reference that was created when the conversation started.01

Getting the service reference object passed as a parameter from another service, even02

remotely.03

04Ending conversations05

A conversation ends, and any state associated with the conversation is freed up, when:06

A service operation that has been annotated @EndConveration has been called.07

The service calls an @EndConversation method on a callback interface.08

The service's conversation lifetime timeout occurs.09

The client calls ServiceReference::endConversation().10

The client calls ServiceReference::setConversationID() which implicitly ends any active11conversation.12

13

If a method is invoked on a service reference after an @EndConversation method has been called14

then a new conversation will automatically be started. If15ServiceReference::getConversationID() is called after the @EndConversation method is16called, but before the next conversation has been started, it will return null.17

18

If a service reference is used after the service provider's conversation timeout has caused the19

conversation to be ended, then ConversationEndedException will be thrown. In order to use that20service reference for a new conversation, its endConversation() method must be called.21

22

1.5.6.Application Specified Conversation IDs23

24

It is also possible to take advantage of the state management aspects of conversational services25

while using a client-provided conversation ID. To do this, the client would use the26

ServiceReference::setConversationID() method.27

28


24/70


25/70



Any method that returns "void" and has no declared exceptions may be marked by using the72

@OneWayannotation on the method in the interface header or by using the oneWay=true73attribute in the interface definition of the service. This means that the method is non-blocking74

and communication with the service provider may use a binding that buffers the requests and75

sends it at some later time.76

77

The following snippet shows an interface header for a service with the reportEvent() method78declared as a one-way method:79

80



86// @OneWay87virtualvoid reportEvent(int eventId) = 0;88

89

};9091

The following snippet shows the component type for a service with the reportEvent() method92declared as a one-way method:93

9495

969798

9900

01

02

SCA does not currently define a mechanism for making non-blocking calls to methods that return03

values or are declared to throw exceptions. It is recommended that service designers define04one-way methods as often as possible, in order to give the greatest degree of binding flexibility05

to deployers.06

07

1.6.2.Callbacks08

09

A callback service is a service that is used for asynchronous communication from a service10provider back to its client in contrast to the communication through return values from11

synchronous operations. Callbacks are used by bid i rec t ion a l serv i ces , which are services that12have two interfaces:13

1. an interface for the provided service14

2. an interface that must be provided by the client15

16


26/70



Callbacks may be used for both remotable and local services. Either both interfaces of a17

bidirectional service must be remotable, or both must be local. It is illegal to mix the two. There18are two basic forms of callbacks: stateless callbacks and stateful callbacks.19

20

A callback interface is declared by the callbackHeader and optionally callbackClass attributes21

in the interface definition of the service. The following snippet shows the component type for a22

service MyService with the interface defined in MyService.h and the interface for callbacks23defined in MyServiceCallback.h ,24

25

2627

29

3031

32

Alternatively the callback can be specified in the interface header using the @Callback33

annotation:34MyService.h file:35

// MyService interface36// @Callback(header=MyServiceCallback.h)37class MyService {38public:39

virtualvoid someMethod( unsignedint arg ) = 0;40};41

42

MyServiceCallback.h file:43

// MyServiceCallback interface44class MyServiceCallback {45

public:46virtualvoid receiveResult( unsignedint result ) = 0;47

}48

49

1.6.2 .1 . Stat e fu l Ca l lbacks50

51

A stateful callback represents a specific implementation instance of the component that is the52

client of the service. The interface of a stateful callback should be conversat iona l .53

A component gets access to the callback service by using the getCallback() method of the54

ServiceReference (obtained from the ComponentContext).55

56

The following is an example service implementation for the service and callback declared above.57

When the someMethod has completed its processing it retrieves the callback service from the58

ServiceReference and invokes a callback method.59

60

#include "MyServiceImpl.h"61#include "MyServiceCallback.h"62


27/70



#include "osoa/sca/ComponentContext.h"63usingnamespace osoa::sca;64

65MyServiceImpl::someMethod( unsignedint arg )66{67

68// do some processing69

70ComponentContextPtr context = ComponentContext::getCurrent();71ServiceReferencePtr serviceRef = context->getSelfReference();72MyServiceCallback* callback = (MyServiceCallback* ) serviceRef-73

>getCallback();74callback->receiveResult(result);75

}76

77

The following shows how a client component would to invoke the MyService service and receive78

the callback.79

80

#include "MyServiceImpl.h"81

#include "MyServiceCallback.h"82#include "osoa/sca/ComponentContext.h"83usingnamespace osoa::sca;84

85void clientMethod( unsignedint arg )86{87

// locate the service88ComponentContextPtr context = ComponentContext::getCurrent();89MyService* service = (MyService*)context->getService("myservice");90service->someMethod(arg);91

}9293

MyServiceCallback::receiveResult(unsignedint result)94{95

// code to process result96}97

98

99

Stateful callbacks support some of the same use cases as are supported by the ability to pass00service references as parameters. The primary difference is that stateful callbacks do not require01

that any additional parameters be passed with service operations. This can be a great02convenience. If the service has many operations and any of those operations could be the first03

operation of the conversation, it would be unwieldy to have to take a callback parameter as part04

of every operation, just in case it is the first operation of the conversation. It is also more05natural than requiring the application developers to invoke an explicit operation whose only06

purpose is to pass the callback object that should be used.0708

09

1.6.2 .2 . Stateless Cal lback s10

A stateless callback interface is a callback whose interface is not conversat iona l . Unlike stateful11services, the client that uses stateless callbacks will not have callback methods routed to an12


28/70



instance of the client that contains any state that is relevant to the conversation. As such, it is13

the responsibility of such a client to perform any persistent state management itself. The only14information that the client has to work with (other than the parameters of the callback method)15

is a callback ID that is passed with requests to the service and is guaranteed to be returned with16

any callback. The callback ID is retrieved from the ServiceReference.17

18

The following snippets show a client setting a callback id before invoking the asynchronous19service and the callback method retrieving the callback ID:20

21void clientMethod( unsignedint arg )22{23

// locate the service24ComponentContextPtr context = ComponentContext::getCurrent();25ServiceReferencePtr svcRef = context->getServiceReference(myservice);26svcRef->setCallbackID(1234);27MyService* service = (MyService*)svcRef->getService();28service->someMethod(arg);29

}3031

32MyServiceCallback::receiveResult(unsignedint result)33{34


ServiceReferencePtr serviceRef = context->getSelfReference();37std::string id = serviceRef->getCallbackID();38

39// code to process result40

}41

42

43

1.6.2 .3 . I m p l ement i ng Mu l t i p l e B id i r ec t i ona l I n t e r f aces 4445

Since it is possible for a single class to implement multiple services, it is also possible for46callbacks to be defined for each of the services that it implements. To access the callbacks the47

ServiceReference::getCallback(serviceName) method must be used, passing in the name of the48service for which the callback is to be obtained.49

50

1.6.2 .4 . Custom iz ing t he Callback51

52

By default, the client component of a service is assumed to be the callback service for the53

bidirectional service. However, it is possible to change the callback by using the54ServiceReference::setCallback() method. The object passed as the callback should55

implement the interface defined for the callback, including any additional SCA semantics on that56interface such as its scope and whether or not it is remotable.57

58


29/70



Since a service other than the client can be used as the callback implementation, SCA does not59

generate a deployment-time error if a client does not implement the callback interface of one of60its references. However, if a call is made on such a reference without the setCallback() method61

having been called, then a NoRegisteredCallbackException will be thrown on the client.62

63

A callback object for a stateful callback interface has the additional requirement that it must be64

serializable. The SCA runtime may serialize a callback object and persistently store it.65

66

A callback object may be a service reference to another service. In that case, the callback67messages go directly to the service that has been set as the callback. If the callback object is68

not a service reference, then callback messages go to the client and are then routed to the69specific instance that has been registered as the callback object. However, if the callback70

interface has a stateless scope, then the callback object must be a service reference.71

72

1.6.2 .5 . Cus tom i z ing t he Ca l l back I den t i t y 73

74

The identity that is used to identify a callback request is, by default, generated by the system.75However, it is possible to provide an application specified identity that should be used to identify76

the callback by calling the ServiceReference::setCallbackID() method. This can be used in77

either stateful or stateless callbacks. The identity will be sent to the service provider, and the78

binding must guarantee that the service provider will send the ID back when any callback79

method is invoked.80

81

The callback identity has the same restrictions as the conversation ID. It must be a std::string.82

83

1 .7 . C+ + A PI 8485

All the C++ interfaces are found in the namespace osoa::sca, which has been omitted from the86

following descriptions for clarity.87

88

1.7.1.Reference Counting Pointers89

These are a derived version of the familiar smart-pointer. The pointer class holds a real (dumb)90pointer to the object. If the reference counting pointer is copied, then a duplicate pointer is91

returned with the same real pointer. A reference count within the object is incremented for each92copy of the pointer, so only when all pointers go out of scope will the object be freed.93

RefCountingPointer defines methods raw pointer like semantics. This includes defining operators94

for dereferencing the pointer (*, ->), as well as operators for determining the validity of the95pointer.96

template 97class RefCountingPointer {98public:99

T& operator* () const;00T* operator-> () const;01


30/70



operator void* () const;02booloperator! () const;03

};04

05

The RefCountingPointer class has the following methods:06

o p er a t o r* ( ) Dereferences the underlying pointer, returning a reference to the value.07

This is equivalent to calling *p where p is the underlying pointer. If this method is08invoked on null pointer, an SCANullPointerException is thrown.09

o p e r a t o r - > ( ) Allows methods to be invoked directly on the underlying pointer. This is10

equivalent to invoking p->func() where func() is a method defined on the underlying11

pointer type. If this method is invoked on a null pointer, an SCANullPointerException is12thrown.13

o p e r at o r vo i d * ( ) Returns null if the underlying pointer is null, otherwise returns a14non-zero value. This method allow for checking whether a RefCountingPointer is set, i.e.15

if (p) { /* do something */ }.16

o p e r a t o r ! ( ) Returns true if the underlying pointer is null, false otherwise. This method17allows for checking wither is RefCountingPointer is not set, i.e. if (!p) { /* do something18

*/ }1920

Reference counting pointers in SCA have the same name as the type they are pointing to, with a21suffix of Ptr. (E.g. ComponentContextPtr, ServiceReferencePtr).22

23

24

1.7.2.Component Context25

The following shows the ComponentContext interface.26

27

class ComponentContext {28public:29

static ComponentContextPtr getCurrent();3031

virtualstd::string getURI() const = 0;3233

virtualvoid * getService(conststd::string& referenceName) const = 0;34virtual std::list getServices(conststd::string& referenceName)35

const = 0;3637

virtual ServiceReferencePtr getServiceReference(conststd::string&38referenceName) const = 0;39

virtual std::list getServiceReferences(conststd::string&40referenceName) const = 0;41

4243

virtual DataObjectPtr getProperties() const = 0;44virtual DataFactoryPtr getDataFactory() const = 0;45

4647

virtual ServiceReferencePtr getSelfReference() const = 0;48virtual ServiceReferencePtr getSelfReference(const std::string& serviceName)49


31/70



const = 0;50};51

52

The ComponentContext C++ interface has the following methods:53

ge tCur ren t ( ) returns the ComponentContext for the current component54

g e t U R I ( ) returns the absolute URI of the component.55

getServ i ce( ) returns a pointer to object implementing the interface defined for the56named reference. Input to the method is the name of a reference defined on this57

component. A MultipleServicesException will be thrown if the reference resolves to more58than one service.59

getServ i ces( ) returns a list of objects implementing the interface defined for the60

named reference. Input to the method is the name of a reference defined on this61component.62

getServ i ceReference( ) returns a ServiceReference for the specified service. A63

MultipleServicesException will be thrown if the reference resolves to more than one64service.65

getServ i ceReferences( ) returns a list of ServiceReferences for the named reference.66

ge tP roper t i es ( ) Returns an SDO from which all the properties defined in the67componentType file can be retrieved.68

ge tDa taFac to ry ( ) Returns an SDO DataFactory which can be used to create data69

objects.70

getSel fReference( ) Returns a ServiceReference that can be used to invoke this71

component over the designated service. The second variant, which takes a serviceName72

parameter, must be used if the component implements multiple services. A73MultipleServicesException is thrown if the first variant is called for a component74

implementing multiple services.75

76

77

1.7.3.ServiceReference78

The following shows the ServiceReference interface.79

80

class ServiceReference {81public:82

virtualvoid* getService() const = 0;8384

virtualstd::string getConversationID() const = 0;85virtualvoid setConversationID(const std::string& id) = 0;86

87virtualstd::string getCallbackID() const = 0;88virtualvoid setCallbackID(const std::string& id) = 0;89

90virtualvoid* getCallback() const = 0;91virtualvoid setCallback(void* callback) = 0;92

93virtualvoid endConversation() = 0;94

95


32/70


33/70



ge tFunc t i onName( ) Returns the function name in which the exception occurred.40

41

Details concerning this class and its derived types are described in the section on Error Handling42

in this document.43

44

1.7.5.SCANullPointerException45

The following shows the SCANullPointerException interface.46

47namespace osoa {48

namespace sca {4950

class SCANullPointerException : public SCAException {51};52

}53}54

55

1.7.6.ServiceRuntimeException56

The following shows the ServiceRuntimeException interface.57


namespace sca {6061

class ServiceRuntimeException : public SCAException {62};63

}64}65

66

1.7.7.ServiceUnavailableException67

The following shows the ServiceUnavailableException interface.68


namespace sca {7172

class ServiceUnavailablException : public ServiceRuntimeException {73};74

}75}76

77

1.7.8.NoRegisteredCallbackException78

The following shows the NoRegisteredCallbackException interface.79


34/70




namespace sca {8283

class NoRegisteredCallbackException : public ServiceRuntimeException {84};85

}86}87

8889

1.7.9.ConversationEndedException90

The following shows the ConversationEndedException interface.91


namespace sca {9495

class ConversationEndedException : public ServiceRuntimeException {96};97

}98}99

00

1.7.10. MultipleServicesException01

The following shows the MultipleServicesException interface.02


namespace sca {0506

class MultipleServicesException : public ServiceRuntimeException {07};08

}09}10

1112

13

1 .8 . C+ + A n n o t at i o n s 1415

This section provides definitions of the annotations which can be used in the interface and16implementation headers. The annotations are defined as C++ comments in interface and17

implementation header files, for example:18

19

// @Scope(stateless)2021

All meta-data that is represented by annotations can also be defined in .composite and22.componentType side files as defined in the SCA Assembly Specification and the extensions23

defined in this specification. Component type information found in the component type file must24

be compatible with any specified annotation information.25


35/70



26

1.8.1.Interface Header Annotations27

28

This section lists the annotations that may be used in the header file that defines a service29interface. These annotations can also be represented in SCDL within the 30

element.31

32

1.8.1 .1 . @Remotable33

Annotation on service interface class to indicate that a service is remotable.34

Format:35

// @Remotable36

37

The default is false (not remotable).38

39

Interface header:40// @Remotable41class LoanService {42

...43};44

45

Service definition:46

4748

4950

51

52

1.8.1 .2 . @Callback53

Annotation on a service interface class to specify the callback interface.54

Format:55

// @Callback(header=headerName, class=className)56

57

where headerName is the name of the header defining the callback service interface.58

className is the optional name of the class for the callback interface.59

60

Interface header:61

62

// @Callback(header=MyServiceCallback.h, class=MyServiceCallback)63class MyService {64public:65

virtualvoid someMethod( unsignedint arg ) = 0;66


36/70



};67

68

69


71

7275

7677

78

1.8.1 .3 . @OneWay79

Annotation on a service interface method to indicate the method is one way.80

Format:81

// @OneWay82

83

Interface header:84

85

class LoanService86{87public:88

// @OneWay89virtualvoid reportEvent(int eventId) = 0;9091

};92

93


9596

9798

9900

01

1.8.1 .4 . @EndConversat ion02

Annotation on a service interface method to indicate that the conversation will be ended when03

this method is called04

Format:05

// @EndConversation06

07

Interface header:08

09


37/70



class LoanService10{11public:12

// @EndConversation13virtualvoid cancelApplication( ) = 0;1415

};16

17Service definition:18

1920

2122

2324

25

26

27

1.8.2.Implementation Header Annotations28

29

This section lists the annotations that may be used in the header file that defines a service30

implementation. These annotations can also be represented in SCDL within the31 element.32

33

1.8.2 .1 . @Scope34

Annotation on a service implementation class to indicate the scope of the service.35

Format:36

// @Scope(value)37

38

where value can be stateless, composite, request or conversation. The default value is39stateless.40

41

Implementation header:42

// @Scope(composite)43class LoanServiceImpl : public LoanService {44

...45};46

47

Component definition:48

49

50


38/70



54

1.8.2 .2 . @Eager I ni t 55

Annotation on a service implementation class to indicate the implantation is to be instantiated56

when its containing component is started.57

Format:58

// @EagerInit59

60


// @EagerInit62class LoanServiceImpl : public LoanService {63

...64};65

66


68

6990

9192

93

94

1.8.2 .4 . @Conversat ion95

Annotation on a service implementation class to specify attributes of a conversational service.96


39/70



Format:97

// @Conversation(maxIdleTime=value, maxAge=value, singlePrincipal=boolValue)98

99

where value is a time expressed as an integer followed by a space and then one of the00following: "seconds", "minutes", "hours", "days" or "years".01

02


04

// @Conversation(maxAge="30 days", maxIdleTime=5 minutes,05// singlePrincipal=false)06class LoanServiceImpl : public LoanService07{08

09};10

11


13

1417

181920

1.8.2 .5 . @Property21

Annotation on a service implementation class data member to define a property of the service.22

Format:23

// @Property(name=propertyName, type=typeQName24

// default=defaultValue, required=true)25

26

where27

name (optional) specifies the name of the property. If name is not specified the28property name is taken from the name of the following data member.29

type (optional) specifies the type of the property. If not specified the type of the30property is based on the C++ mapping of the type of the following data member to an31

xsd type as defined in the appendix C++ to WSDL Mapping. If the data member is an32

array, then the property is many-valued.33 required (optional) specifies whether a value must be set in the component definition34

for this property. Default is false35

default(optional) specifies a default value and is only needed ifrequired is false,36

37

Implementation:38


40/70



// @Property(name=loanType, type=xsd:int)39long loanType;40

41

Component Type definition:42

43

444546

474849

1.8.2 .6 . @Reference50

Annotation on a service implementation class data member to define a reference of the service.51

Format:52

// @Reference(name=referenceName, interfaceHeader=LoanService.h,53

// interfaceClass=LoanService, required=true)54

55

where56

name (optional) specifies the name of the reference. If name is not specified the57

reference name is taken from the name of the following data member.58

interfaceHeader (required) specifies the C++ header defining the interface for the59reference.60

interfaceClass (optional) specifies the C++ class defining the interface for the61reference. If not specified the class is derived from the type of the annotated data62

member.63

required (optional) specifies whether a value must be set for this reference. Default is64

true65

66

If the annotated data member is a std::list then the implied component type has a reference67

with a multiplicity of either 0..n or 1..n depending on the value of the @Reference r equ i red 68attribute 1..n applies if required=true. Otherwise a multiplicity of 0..1 or 1..1 is implied.69

70

Implementation:71

// @Reference(interfaceHeader=LoanService.h required=true)72LoanService* loanService;73

74

// @Reference(interfaceHeader=LoanService.h required=false)75std::list loanServices;76

77

Component Type definition:78

79

80


41/70



8182

838485

8687

8889

90

9192

9394

1 .9 . WSDL to C+ + and C+ + t o W SDL Mapp ing 9596

The SCA Client and Implementation Model for C++ applies the WSDL to C+ + mapping rules as97

defined by the OMG WSDL to C++ Mapping Specification[3]and the C++ to WSDL mapping98

rules as defined in the appendix C++ to WSDL Mapp ing.99

00

01


42/70



2. Appendix 10203

2 .1 . Packag ing 0405

2.1.1.Composite Packaging06

The physical realization of an SCA composite is a folder in a file system containing at least one07.composite file. The following shows the MyValueComposite just after creation in a file system.08

09

MyValue/10MyValue.composite11

12

Besides the .composite file the composite contains artifacts that define the implementations of13components, and that define the bindings of services and references. Examples of artifacts would14

C++ header files, shared libraries (for example, dll), WSDL portType definitions, XML schemas,15WSDL binding definitions, and so on. These artifacts can be contained in subfolders of the16

composite, whereby programmers have the freedom to construct a folder structure that best fits17

the needs of their project. The following shows the complete MyValue composite folder file18structure in a file system.19

MyValue/20MyValue.composite21

22bin/23

myvalue.dll24services/myValue/25

MyValue.h26MyValueImpl.h27MyValueImpl.componentType28

MyValueService.wsdl29 services/customer/30CustomerService.h31CustomerServiceImpl.h32Customer.h33

services/stockquote/34StockQuoteService.h35StockQuoteService.wsdl36

37

Note that the folder structure is not architected, other than the .composite file must be at the38root of the folder structure.39

40

Address ing o f the resourcesinside of the composite is done relative to the root of the41composite (i.e. the location of the .composite file).42

Shared libraries (including dlls) will be located as specified in the element43

in the .composite file relative to the root of the composite.44

XML definitions like XML schema complex types or WSDL portTypes are referenced by composite45

and component type files using URIs. These URIs consist of the namespace and local name of46


43/70



these XML definitions. The composite folder or one of its subfolders has to contain the XML47

resources providing the XML definitions identified by these URIs.48

49


44/70



3. Appendix 25051

3 .1 . Types Suppor ted in Serv ice I n t e r faces 52A service interface can support a restricted set of the types available to a C++ programmer. This53

section summarizes the valid types that can be used.54

3.1.1.Local service55

For a local service the types that are supported are:56

Any of the C++ primitive types (for example, int, short, char). In this case the types will57

be passed by value as is normal for C++.58

Pointers to any of the C++ primitive types (for example, int *, short *, char *).59

The const keyword can be used for any pointer to a C++ primitive type (for example60

const char *). If this is used on a parameter then the destination may not change the61value.62

C++ class. The class will be passed by value as is normal for C++.63

Pointer to a C++ class. A pointer will be passed to the destination which can then modify64

the original contents.65

DataObjectPtr. An SDO pointer. This will be passed by reference.66

References to C++ classes (passed by reference)67

3.1.2.Remotable service68

For a remotable service being called by another service the data exchange semantics is by-value.69

In this case the types that are supported are:70

Any of the C++ primitive types (for example, int, short, char). This will be copied.71

C++ classes. These will be passed using the copy constructor. The copy constructor must72

make sure that any embedded references, pointers or objects are copied appropriately.73 DataObjectPtr. An SDO pointer. The SDO will be copied and passed to the destination.74

Not supported:75

Pointers.76

References.77


45/70



4. Appendix 37879

4 .1 . Rest r i c t i ons on C+ + header f i l es 80A C++ header file that is used to describe an interface has some restrictions. It must:81

Declare at least one class with:82

o At least one public method.83

o All public methods must be pure virtual (virtual with no implementation)84

85

The following C++ keywords and constructs must not be used:86

Macros87

inline methods88

friend classes89

90


46/70



5. Appendix 49192

5 .1 . XML Schem as93Two new XML schemas are defined to support the use of C++ for implementation and definition94

of interfaces.95

5.1.1.sca-interface-cpp.xsd96

9702

0304

0507

0809

1011

12141617181921 222324

2526

2728

2930

31323334

3536

3738


47/70



5.1.2.sca-implementation-cpp.xsd39

4045

4647

48


48/70



9596

9798

990001


49/70



6. Appendix 50203

6 .1 . C+ + to W SDL Mapp ing 0405

This section describes a mapping from C++ header interfaces to a WSDL description of that06interface. The intent is for implementations of this proposal to be able to deploy a service based07only on a C++ header definition and for a WSDL definition of that service to be generated from08

the C++, either at deploy or run time.09

10

This mapping currently only deals with producing document/literal wrapped style services and11WSDL from C++ header files.12

13


50/70



6 .2 . Par ame t e r and Re tu r n Type m app ings 14This section details how types used as parameters or return types in C++ method prototypes get15mapped to XML schema elements in the generated WSDL.16

6.2.1.Built-in, STL and SDO type mappings17

C++ built in, STL and SDO

types

Notes XML Type

bool xsd:boolean

char signed 8-bit1 xsd:byte

unsigned char unsigned 8-bit1 xsd:unsignedByte

short signed 16-bit1 xsd:short

unsigned short unsigned 16-bit1 xsd:unsignedShort

1 The size of this type is not fixed according to the C++ standard. The size

indicated is the minimum size required by the C++ specification.


51/70


52/70



8 encoded string

wchar_t* or wchar_t array2 Must be a null-terminated UTF-

16 or UTF-32 encoded string

xsd:string

std::string Must be a UTF-8 encoded string xsd:string

std::wstring2 Must be a UTF-16 or UTF-32

encoded string

xsd:string

commonj::sdo::DataObjectPtr xsd:any

18

19

For example, a C++ method prototype defined in a header such as:20

21

2 The encoding associated with a wchar_t variable is determined by the size ofthe wchar_t type. If wchar_t is a 16-bit type, UTF-16 is used, otherwise UTF-32

is used.


53/70


54/70



63

64

65

6.2.4.Multi-dimensional array mapping66

Multi-dimensional arrays will need converting into nested elements. E.g. a method prototype67such as68

69

long myMethod(int multiIdArray[][4][2]);70

71

would generate a schema like:72

73

74

75

76

7879

80

82

83

84

86

87

8889

90

91

92

93

94

95

6.2.5.Pointer/ reference mapping96

A C++ method prototype that uses the pass-by-reference style, defining parameters that are97

either references or pointers, is not meaningful when applied to web services, which rely on98

serialized data. A C++ method prototype that uses references or pointers will be converted to a99WSDL operation that is defined as if the parameters were pass-by-value, with the web-service00

implementation framework responsible for creating the value, obtaining its pointer and passing01that to the implementation class.02

E.g. a C++ method prototype defined in a header such as:03

04


55/70


56/70


57/70



6.2.8.Enum mapping86

In C++ enums define a list of named symbols that map to values. If a method uses an enum87

type, this can be mapped to a restricted element in the WSDL schema.88

For example, a method such as:89

90

std::string getValueFromType( ParameterType type );9192

with the ParameterType type defined as an enum:93

94

enum ParameterType95

{96

UNSET = 1,97

TYPEA,98

TYPEB,99

TYPEC00

};01

02

could convert to a schema like:03

04

05

06

07

08

09

10

11

12

13

14

15

16

17

18

19

The rest

sca client and implementation model cpp-v100

Documents