SCA C++, C and COBOL

1. www.oasis-open.org SCA C++, C and COBOL Bryan Aupperle (aupperle@us.ibm.com) David Haney (haney@roguewave.com) 13 Dec. 2007

2. Specification Status • C and C++ specification development proceeding in OASIS • Based on work started in Open SOA (OSOA) • Now proceeding in the SCA-C-C++ TC • COBOL specification remains under OSOA • SCA-C-C++ TC work will influence

3. SCA-C-C++ TC Work • Updated conformance statements • Definition of a conformance test suite • Formal definition of C/C++ Annotations • Updated C++ -> WSDL, WSDL -> C++ Mapping • Incorporation of SCA Policy

4. SCDL for C++ • interface.cpp • header – C++ header file describing the interface • class – (optional) Class defining the interface • callbackHeader – (optional) C++ header describing the callback interface • callbackClass – (optional) Class defining the callback interface • remotable – (optional) Indicates whether the service can be called from a remote system • implementation.cpp • library – Shared library defining the service factory • path – (optional) Path to search for the library • header – C++ header file describing the implementation • class – (optional) Class defining the implementation • scope – (optional) Specifies the lifetime and reuse options for an implementation instance

5. C++ APIs • ComponentContext • Primary interface for accessing SCA defined components. • Component Meta Information • getCurrent(), getURI(), getProperties(), getDataFactory() • Service Lookup • getService(), getServices() • Service References • getServiceReference(), getServiceReferences() • getSelfReference()

6. C++ APIs (cont) • ServiceReference • Interface for interacting with service instances • Conversational interface • getConversationID(), setConversationID() • Asynchronous interface • getCallbackID(), setCallbackID() • getCallback(), setCallback()

7. C++ WSDL Mapping • Defines a translation from a C++ class interface to a WSDL • Uses comment annotations to control the conversion • Defines mapping rules for: • primitive types • C++ Standard Library types • SDO • classes, structs, arrays, enums • Defines a mapping from a WSDL to a C++ class interface • Currently defers to the OMG WSDL to C++ Mapping • Alternative mappings are being reviewed.

8. C++ Example • Interface SCDL <service name=“LoanService”> <interface.cpp header=“LoanService.h”/> </service> • Implementation SCDL <component name=“LoanServiceImpl”> <implementation.cpp library=“loan” header=“LoanServiceImpl.h”/> </component>

9. C++ Example (cont) • LoanService Interface class LoanService { public: virtual bool approveLoan( unsigned long customerNumber, unsigned long loanAmount) = 0; };

10. C++ Example (cont) • LoanServiceImpl Interface class LoanServiceImpl : public LoanService { public: virtual bool approveLoan( unsigned long customerNumber, unsigned long loanAmount) { // … } };

11. C++ Example (cont) • SCA Application int main(void) { ComponentContextPtr context = ComponentContext::getCurrent(); LoanService* service = (LoanService*) context->getService(“LoanService”); bool result = service->approveLoan(12345, 100); return 0; }

12. SCDL for C • Interface defined by a set of functions • interface.c • header – header file describing the interface • callbackHeader – (optional) header file describing the callback interface • remotable – (optional) Indicates whether the service can be called from a remote system • implementation.c • module – binary executable for the component implementation • library – (optional) indicates whether the service is implemented as a library or a program • location – (optional) location of the module • scope – (optional) Specifies the lifetime and reuse options for an implementation instance

13. C APIs • Synchronous Programming • SCALocate(), SCALocateMultiple() – get handle(s) to services • SCAInvoke() – invokes an operation of a service • SCAProperty<PropertyType>() – get the value of a property • SCAGetFaultMessage(), SCASetFaultMessage() – get or set a fault message for a service operation • Asynchronous Programming • SCAGetCallback() – get handle of callback instance • SCACallback() – invoke a callback operation • SCASetCallback() – set a callback function for a reference • SCASetCallbackID(), SCAGetCallbackID() – get or set the callback ID for a service instance • Conversation Services • SCAGetConversationID(), SCASetConversationID() – get or set a user provided conversation ID • SCAEndConversation() – end a conversation

14. C Example • Interface SCDL <service name="LoanService"> <interface.c header="LoanService.h"/> </service> • Implementation SCDL <component name="LoanService"> <implementation.c module="loan"/> </component>

15. C Example (cont) • LoanService Interface char approveLoan( long customerNumber, long loanAmount); • LoanService Implementation char approveLoan( long customerNumber, long loanAmount) { … }

16. C Example (cont) • SCA Application void clientFunction() { … SCALocate(L”customerService”, &serviceToken, &compCode, &reason); SCAInvoke(serviceToken, L“getCreditRating”, sizeof(custNum), (void *)&custNum, sizeof(rating), (void *)&rating, &compCode, &reason); }

17. SCDL for COBOL • interface.cobol • copybook – copybook file describing the interface • callbackCopybook – (optional) copybook file that describing the callback interface • location – (optional) location of library containing the copybook files • remotable – (optional) Indicates whether the service can be called from a remote system • implementation.cobol • program –binary executable for the component implementation • location – (optional) location of library containing the binary executable • scope – (optional) Specifies the lifetime and reuse options for an implementation instance

18. COBOL APIs • Same functions as in C • Synchronous Programming • SCAProperty is not typed • Program-Based Implementation Support • Asynchronous Programming • Conversation Services

19. Implementation as Program • Support environments where function is provided by programs • API • SCAService() – get name of invoked service • SCAOperation() – get name of invoked operation • SCAMessageIn() – get input message SCAMessageOut() – set output message

20. COBOL Example • LoanService Interface 01 LoanServiceInf. * @Operation name="LoanApplication" * input="CustomerName" * output="LoanAmount" 03 LoanApplication. 05 CustomerName PIC X(255). 05 LoanAmount PIC 9(4).

21. COBOL Example (cont) • LoanService Implementation PROCEDURE DIVISION. IN-THE-BEGINNING. PERFORM GET-MY-CONTEXT. EVALUATE My-Operation WHEN ApproveLoanOperation * Get service request MOVE length of CustomerNumber of ApproveLoan To InputMessageLength CALL "SCAMessageIn" using by content SCA-COMPCODE, SCA-REASON, My-Service, My-Operation, InputMessageLength, CustomerNumber of ApproveLoan PERFORM CUSTOMER-SERVICE * Return service response CALL "SCAMessageOut" using by content SCA-COMPCODE, SCA-REASON, My-Service, My-Operation, OutputMessageLength, LoanAmount of ApproveLoan WHEN OTHER CONTINUE END-EVALUATE. * Return to SCA runtime GOBACK. GET-MY-CONTEXT. CALL "SCAService" using by content SCA-COMPCODE, SCA-REASON, My-Service. CALL "SCAOperation" using by content SCA-COMPCODE, SCA-REASON, My-Operation.

22. COBOL Example (cont) • SCA Application PROCEDURE DIVISION. . CALL "SCALocate" using by content SCA-COMPCODE, SCA-REASON, CustomerServiceReference, CustomerServiceToken. CALL "SCAInvoke" using by content SCA-COMPCODE, SCA-REASON, My-CustomerServiceToken, CreditRatingOperation, InputMessagelength, CustomerNumber, OutputMessageLength, Rating.

23. C & COBOL WSDL Mapping • Defines a translation between language structures and WSDL • Defines type mapping rules for: • Primitive types • Structs or Groups • Variable length strings and unbounded arrays • Defines mapping rules between operations and functions

24. Annotations • Contained in comments, processed by tools • Interface • Invocation attribute • OneWay • Remotable • Callback • EndConversation • Implementation • Scope • Lifecycle • Conversation information • Property • Reference

25. Open Implementations • Apache Tuscany Native • http://incubator.apache.org/tuscany/sca-native.html • Implements pre-1.0 C++ specification • Working towards 1.0 compliance

26. OASIS References • Open CSA Member Section • http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=opencsa-ms • SCA-C-C++ Technical Committee • http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=sca-c-cpp • SCA-C-C++ Charter • http://www.oasis-open.org/committees/sca-c-cpp/charter.php

27. OSOA References • OSOA SCA Specifications • http://www.osoa.org/display/Main/Service+Component+Architecture+Specifications • Specifications • SCA C++ Client and Implementation • SCA C Client and Implementation • SCA COBOL Client and Implementation

28. Thai Traditional Chinese Gracias Russian Spanish Thank You English Merci Obrigado French Brazilian Portuguese Arabic Danke Grazie Italian German Simplified Chinese Japanese

29. Backup

30. C++ APIs (cont) • Supplemental APIs • RefCountingPointer • Defines a reference-counted pointer interface • SCAException • Provides a hierarchy of exception classes for use with the SCA API. • SCANullPointerException • ServiceRuntimeException • ServiceUnavailableException • NoRegisteredCallbackException • ConversationEndedException • MultipleServicesException

31. C++ Annotations • Contained in comments, processed by tools • Interface Header File • @Remotable, @Conversational • @Callback, @OneWay • @EndsConversation • Implementation Header File • @Scope • @EagerInit • @AllowsPassByReference • @ConversationAttributes • @Property • @Reference

32. C Annotations • Contained in comments, processed by tools • Header File • @Interface • @Operation, @Callback, @OneWay • @Remotable, @Conversational • @EndsConversation • Implementation File • @Service • @Reference • @Property • @Scope • @Init, @Destroy, @EagerInit • @AllowPassByReference • @ConversationAttributes

33. COBOL Annotations • Contained in comments, processed by tools • Interface File • @Interface • @Operation, @Callback, @OneWay • @Remotable, @Conversational • @EndsConversation • Implementation File • @Service • @Reference • @Property • @Scope • @Init, @Destroy, @EagerInit • @AllowPassByReference • @ConversationAttributes