diff options
Diffstat (limited to 'tags/cpp-0.1.incubating-M1-RC3b/sca/doc/WSEntrypoint.txt')
| -rw-r--r-- | tags/cpp-0.1.incubating-M1-RC3b/sca/doc/WSEntrypoint.txt | 272 |
1 files changed, 0 insertions, 272 deletions
diff --git a/tags/cpp-0.1.incubating-M1-RC3b/sca/doc/WSEntrypoint.txt b/tags/cpp-0.1.incubating-M1-RC3b/sca/doc/WSEntrypoint.txt deleted file mode 100644 index 7e59008cae..0000000000 --- a/tags/cpp-0.1.incubating-M1-RC3b/sca/doc/WSEntrypoint.txt +++ /dev/null @@ -1,272 +0,0 @@ -Web Services EntryPoint -======================= - -This section of the document describes the use of the Web Service EntryPoint -(WS EntryPoint) support in the Apache Tuscany SCA C++ runtime. - -The WS EntryPoint code is based on Apache Axis2C version 0.92 -(http://ws.apache.org/axis2/c) and allows SCA components to be invoked via Web -Service calls. - -WS EntryPoint currently supports Document/literal Wrapped style Web Services -only. There are also restrictions about the parameter and return types of the -operations in SCA components that can be exposed as Web Services, see below -for more details. - - -Defining and deploying an SCA Module with a WS EntryPoint -========================================================= - -In this section we will use the Calculator sample as a worked example. -The Calculator code and files can be found at sca/samples/Calculator. - -Pre-requisites: - - o A working component within a module and subsystem, with SCAGEN generated - Proxy and Wrapper classes and a DLL or SO library compiled from these and - the component class files. The sca.module, *.componentType, *.fragment and - sca.subsystem files must also be available and working - -1. Create the WSDL that defines the interface of your SCA component. See the -table "XML Schema Type to C++ Type Mapping" and "Notes on creating WSDL" below -for mapping the parameters and return types of the component operations to XML -schema types in the WSDL. This file needs to be accessible from the component, -so place it in the same directory as the component or in a subdirectory. - -See the sca/samples/Calculator/CalculatorModule/Calculator.wsdl file as an -example. - - -2. Add an EntryPoint definition to the sca.module file, setting the -interface.wsdl interface attribute to the WSDL file defined above, the -reference element to the name of the component to be invoked and the binding.ws -port attribute to the namespace, service and port name specified in the -WSDL, in the form: "<namespace>#wsdl.endpoint(<service-name>/<port-name>)". -Also give the EntryPoint a name and set the multiplicity. - -E.g. for the Calculator component, based on the Calculator.wsdl file: - -<!-- Expose as a web service --> -<entryPoint name="WSCalculatorEntrypoint" multiplicity="1..1"> - <interface.wsdl interface="Calculator.wsdl" /> - <binding.ws port="tuscany/c/Calculator#wsdl.endpoint(CalculatorService/CalculatorServicePort)"/> - <reference>CalculatorServiceComponent</reference> -</entryPoint> - - -3. Create a file named Tuscany-model.config in the same directory as your -component. This file defines which WSDL and XML Schema files to include in the -Tuscany runtime environment for this module. Set the contents of the file -using the example below and use the path and name of the WSDL file created -above. - -E.g. for the Calculator component - -<?xml version="1.0" encoding="utf-8" ?> -<tuscany-model xmlns="http://org.apache.tuscany/xmlns/cpp/1.0"> - <wsdl> - <file name="Calculator.wsdl"/> - </wsdl> -</tuscany-model> - - - -These changes are all that are required in the Tuscany runtime environment to -expose a component as a Web Service; the following steps detail how to add the -Web Service to the list of Axis2C services. - - -4. Create a new directory within the Axis2C services directory. The name of -this directory defines the URL of your service. For example, if you create a -directory named "CalcWebService", the URL of the service will be -http://localhost:9090/axis2/services/CalcWebService - - -5. Create a file named services.xml within the new directory. This file defines -the library to use that contains the service code and the operations that the -service exposes. For the Tuscany WS EntryPoint, you also need to add some -Tuscany specific parameters to identify the Tuscany System Root directory and -the EntryPoint that will be invoked. - -The TuscanySystemRoot parameter requires the full path to your system root -directory - this is the directory that contains the "modules" and "subsystem" -directories; which in turn contain your modules and subsystems. - -The TuscanyEntryPoint parameter is of the form -"<subsystem-name>/<service-name>/<entrypoint-name>", with the subsystem and -service names defined in your sca.subsystem file and the EntryPoint name -defined in the EntryPoint definition you added to your sca.module file above. - -Set the ServiceClass parameter to "tuscany_sca_ws_service" as this library -(tuscany_sca_ws_service.dll on Windows and libtuscany_sca_ws_service.so on -Linux) contains the service code that will invoke your component. - -Finally, add all of the operations that your component defines that you want -to expose as Web Service operations. - -E.g. for the Calculator WS EntryPoint, -axis2c/services/CalcWebService/services.xml contains: - -<service name="CalcWebService"> - - <parameter name="ServiceClass" locked="xsd:false">tuscany_sca_ws_service</parameter> - <parameter name="TuscanySystemRoot" locked="xsd:false">C:/tuscany/cpp/sca/samples/runtime</parameter> - <parameter name="TuscanyEntryPoint" locked="xsd:false">CalculatorSubsystem/CalculatorService/WSCalculatorEntrypoint</parameter> - - <operation name="add"/> - <operation name="sub"/> - <operation name="mul"/> - <operation name="div"/> - -</service> - - -6. Copy the tuscany_sca_ws_service.dll file (or the -libtuscany_sca_ws_service.so file, if on Linux) to the new service directory -you created above. This library contains the code that Axis2C requires to call -a service implementation and links to the tuscany_sca.dll library (or -libtuscany_sca.so on Linux) which manages the invocation of your component. - - -7. Ensure the TUSCANY_SCACPP, TUSCANY_SDOCPP, AXIS2C_HOME and PATH environment -variables are correctly set - -E.g. on Windows run the following commands with the correct directories: -set TUSCANY_SCACPP=C:/path_to_tuscany/sca/deploy -set TUSCANY_SDOCPP=C:/path_to_tuscany/sdo/deploy -set AXIS2C_HOME=C:/path_to_axis2c0.92 -set PATH=%PATH%;C:/path_to_tuscany/sca/deploy/bin;C:/path_to_tuscany/sdo/deploy/bin;C:/path_to_axis2c0.92/lib - - -8. Optionally, enable logging in Tuscany by setting the TUSCANY_SCACPP_LOGGING -environment variable with the level you wish to log at (0 for minimal -logging, up to 9 for more detailed logging) and the TUSCANY_SCACPP_LOG -environment variable to define the file to log to (if this is not set, logging -will go to the console) - -E.g. on Windows run the following commands: -set TUSCANY_SCACPP_LOGGING=5 -set TUSCANY_SCACPP_LOG=C:/tuscany/mylogfile.txt - -Additionally, Axis2C automatically writes logging files to the Axis2C logs -directory (e.g. C:/path_to_axis2c0.92/logs). In particular the Axis2.log file -may contain useful information about your service. - - -9. Start the Simple Axis server, or your Apache HTTP server if you have -deployed Axis2C to Apache. - -E.g. on Windows run the following commands: -cd C:/path_to_axis2c0.92/bin -./axis2_http_server.exe - - -Your component should now be exposed as an Axis2C Web Service, via the WS -EntryPoint you created. See the Axis2C documentation for writing clients to -invoke the Web Service, or you can use any other Web Service client platform -(e.g. Axis2 for Java: http://ws.apache.org/axis2), or you can invoke your -component from another Tuscany runtime by using Tuscany's WS External Service -support. - - - -XML Schema Type to C++ Type Mapping -=================================== - -To help define the WSDL that describes the interface of your component, the -table below lists how incoming XML data in Web Service messages is mapped to -C++ types used in the parameters and return types of your component operations. - -This lists the only C++ types that can currently be used on the operations of a -component exposed as a Web Service. For other types, use an SDO DataObject to -wrap the data, and define that wrapping as a complexType in the WSDL. See the -SDO specifications (available from the Tuscany website) for the C++ types that -SDO supports. - - - XML Schema Type | C++ Type -------------------------------------------------------------- - | - string | char* - | - int | long - | - integer | long - | - short | short - | - float | float - | - double | long double - | - boolean | bool - | - hexBinary | char* - | - base64Binary | char* - | - byte | char - | - complexType | SDO DataObjectPtr - | - any | SDO DataObjectPtr with OpenDataObjectType - - - -Notes on creating WSDL -====================== - - o Currently only Document/literal Wrapped style Web Services are supported by - WS EntryPoint, support for RPC style Web Services is planned for future - releases. - - See the article at http://www.ibm.com/developerworks/webservices/library/ws-whichwsdl/ - for an explanation of Document/literal Wrapped style WSDL and Web Services - - o Operation parameter and return messages that are defined in the WSDL must be - XML Schema elements containing a complexType - there is currently no - support for simpleTypes or single-level elements. Also, Document/literal - Wrapped services require that the operation name is used as the name of the - incoming element that wraps the operation parameters. - - For example, a component operation defined in C++ as: - - long myOperation(char* arg1, short arg2, DataObjectPtr arg3); - - will need to be described in WSDL with messages like: - - <wsdl:message name="myOperationRequestMsg"> - <wsdl:part element="tns:myOperation" name="myOperationRequestPart"/> - </wsdl:message> - <wsdl:message name="myOperationResponseMsg"> - <wsdl:part element="tns:myOperationResponse" name="myOperationResponsePart"/> - </wsdl:message> - - and will need an XML schema to define the types like: - - <xsd:element name="myOperation"> - <xsd:complexType> - <xsd:sequence> - <xsd:element name="arg1" type="xsd:string" minOccurs="1"/> - <xsd:element name="arg2" type="xsd:short" minOccurs="1"/> - <xsd:element name="arg3" minOccurs="1"> - <xsd:complexType> - <xsd:sequence> - <xsd:element name="dataObjectFloatData" type="xsd:float"/> - <xsd:element name="dataObjectStringData" type="xsd:string"/> - <xsd:element name="dataObjectIntData" type="xsd:int"/> - </xsd:sequence> - </xsd:complexType> - </xsd:element> - </xsd:sequence> - </xsd:complexType> - </xsd:element> - - <xsd:element name="myOperationResponse"> - <xsd:complexType> - <xsd:sequence> - <xsd:element name="result" type="xsd:int" minOccurs="1"/> - </xsd:sequence> - </xsd:complexType> - </xsd:element> - |