sca client and implementation model cpp-v100
TRANSCRIPT
-
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
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 -
8/6/2019 SCA Client and Implementation Model Cpp-V100
3/70
SCA Service Component Architecture
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.
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
4/70
SCA Service Component Architecture
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
5/70
SCA Service Component Architecture
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
6/70
SCA Service Component Architecture
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
7/70
SCA Service Component Architecture
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/6/2019 SCA Client and Implementation Model Cpp-V100
8/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 2 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
9/70
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
10/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 4 March 2007
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
virtualbool approveLoan(unsignedlong customerNumber,26unsignedlong loanAmount) = 0;27
};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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
11/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 5 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
12/70
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
13/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 7 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
14/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 8 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
15/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 9 March 2007
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
// LoanService interface45class LoanService {46public:47
virtualbool approveLoan(unsignedlong customerNumber,48unsignedlong loanAmount) = 0;49
};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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
16/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 10 March 2007
}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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
17/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 11 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
18/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 12 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
19/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 13 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
20/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 14 March 2007
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
ComponentContextPtr context = ComponentContext::getCurrent();7475
// 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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
21/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 15 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
22/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 16 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
23/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 17 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
24/70
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
25/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 19 March 2007
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
// LoanService interface81class LoanService {82public:83
virtualbool approveLoan(unsignedlong customerNumber,84unsignedlong loanAmount) = 0;85
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
26/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 20 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
27/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 21 March 2007
#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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
28/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 22 March 2007
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
ComponentContextPtr context = ComponentContext::getCurrent();3536
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
29/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 23 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
30/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 24 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
31/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 25 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
32/70
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
33/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 27 March 2007
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
58namespace osoa {59
namespace sca {6061
class ServiceRuntimeException : public SCAException {62};63
}64}65
66
1.7.7.ServiceUnavailableException67
The following shows the ServiceUnavailableException interface.68
69namespace osoa {70
namespace sca {7172
class ServiceUnavailablException : public ServiceRuntimeException {73};74
}75}76
77
1.7.8.NoRegisteredCallbackException78
The following shows the NoRegisteredCallbackException interface.79
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
34/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 28 March 2007
80namespace osoa {81
namespace sca {8283
class NoRegisteredCallbackException : public ServiceRuntimeException {84};85
}86}87
8889
1.7.9.ConversationEndedException90
The following shows the ConversationEndedException interface.91
92namespace osoa {93
namespace sca {9495
class ConversationEndedException : public ServiceRuntimeException {96};97
}98}99
00
1.7.10. MultipleServicesException01
The following shows the MultipleServicesException interface.02
03namespace osoa {04
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
35/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 29 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
36/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 30 March 2007
};67
68
69
Service definition:70
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
Service definition:94
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
37/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 31 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
38/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 32 March 2007
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
Implementation header:61
// @EagerInit62class LoanServiceImpl : public LoanService {63
...64};65
66
Component definition:67
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
39/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 33 March 2007
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
Implementation header:03
04
// @Conversation(maxAge="30 days", maxIdleTime=5 minutes,05// singlePrincipal=false)06class LoanServiceImpl : public LoanService07{08
09};10
11
Component definition:12
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
40/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 34 March 2007
// @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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
41/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 35 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
42/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 36 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
43/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 37 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
44/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 38 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
45/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 39 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
46/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 40 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
47/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 41 March 2007
5.1.2.sca-implementation-cpp.xsd39
4045
4647
48
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
48/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 42 March 2007
9596
9798
990001
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
49/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 43 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
50/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 44 March 2007
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.
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
51/70
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
52/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 46 March 2007
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.
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
53/70
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
54/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 48 March 2007
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
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
55/70
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
56/70
-
8/6/2019 SCA Client and Implementation Model Cpp-V100
57/70
SCA Service Component Architecture
SCA Client and Implementation Model for C++ 51 March 2007
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