| Oracle Agile Engineering Data Management Web Services Guide for Agile Release e6.2.0.0 E52562-01 |
|
 Previous |
 Next |
| Oracle Agile Engineering Data Management Web Services Guide for Agile Release e6.2.0.0 E52562-01 |
|
Previous |
Next |
Each wrapper has to implement the Web Service Wrapper interface, which prescribes the following method:
StringList callWebService(WrapperContext context, CallableParam args) WrapperPackage.Custom.2 = another.custom.wrapperpackage
The context contains all relevant information for the wrapper to perform the call. The wrapper then transforms the arguments to an XML payload for the outbound Web Service and finally makes the call.
If it is an asynchronous Web Service, the wrapper returns a string list with the correlation ID. Otherwise, it transforms the XML payload returned by the Web Service into a string list that is expected by the calling EDM Server process.
In case the wrapper is implemented in BPEL (or in any other external Web Service language), you require a special wrapper called the ExternalWrapper. This wrapper delegates the call to the respective external Web Service Wrapper.
For the outbound calls, you are required to use the ExternalWrapper to call an external Web Service or a BPEL process. However, you need to first implement an interface to adapt the External Wrapper. This interface is called BPEL facade.
Normally, this facade must be a BPEL process that you implement. In this facade, you can invoke an external Web Service or BPEL process and create their business logic. All the facades must implement a standard WSDL. The External wrapper uses this standard WSDL to generate the proxy. It can then use different endpoints to call different BPEL facades.
All the endpoints for the external wrapper are defined in the properties file ExternalWrapper.properties. This file resides in the directory APP-INF/classes together with the file application.properties for the Web Services.
Example:
bpel.wrapper.SampleExternalService2.wsdl=http://<server><port>/soa-infra/services/default/SOAComposite2/BPELFacadeService?WSDL
In the example above, when we pass the service name as SampleExternalService2 in xutil_call_ws, the wrapper manager first looks for an internal wrapper named as SampleExternalService2. If this internal wrapper does not exist, then the wrapper manager calls the external wrapper and gets the endpoint with the key value bpel.wrapper.SampleExternalService2.wsdl in the ExternalWrapper.properties file.
|
Note: You are required to use the custom staging mechanism of the Agile e6 installer to add your own mappings to the file ExternalWrapper.properties. |
In order to compile a custom wrapper, you need the libraries contained in the Web Services application. These libraries can be found at ${ep_root}/staging/product/WebServices/WebServices.ear/APP-INF/lib.
If your wrapper calls an external or internal Web Service, you also need to add the generated client classes or any other infrastructure classes needed. This depends on the Web Service client framework that you use.
|
Caution: We highly recommend using the WebLogic Web Service framework when implementing a wrapper for a Web Service because the wrapper is run inside WebLogic. |
The name of the wrapper class must be <ID>Wrapper, as the wrapper manager looks for this string when the EDM Server tries to call it.
The imports used by the wrapper are in the libraries contained in the lib directory inside the file WebServices.ear (at APP-INF/lib). By default, the wrapper class must be in the package com.agile.ws.e6.wrappers so that the wrapper manager can find it at the runtime. However, it is also possible to add other package names to the search path by adding them to the application.properties file of the Web Services application:
WrapperPackage.Custom.1 = some.custom.wrapperpackage
More sample details can be found in the Appendix at EchoServiceWrapper.Java and SampleWrapper.java.
A new C/C++ userexit is provided that can be called from LogiView or C/C++ to make an outbound Web Service call. The request is sent as an ECI call to the ECI server embedded in the application server, which then calls the respective wrapper for XML processing.
To limit any XML parsing in LogiView and C/C++, the userexit sends a string containing a userexit parameter as an input to the wrapper and it expects a list of string as a result from the wrapper.
The userexit accepts an input argument that uses the syntax prescribed by CallableParam and zag_cnv_arg. This argument is passed to the ECI callable Eci_call Web Service in the application server.
This userexit is called xutil_call_ws and can be used in LogiView as follows:
EP_APP_CMD = "EchoService"
EP_APP_CID_STRING = ""
EP_APP_CONTENTS = "Please echo: something"
RES = #xutil_call_ws(EP_APP_CMD, EP_APP_CID_STRING, EP_APP_CONTENTS, EP_APP_RESULT, EP_APP_ERROR)
if (RES == 0)
put(strprint("Web service %s returned: %s", EP_APP_CMD, EP_APP_RESULT))
else
put(strprint("Error %d when calling web service %s, error message is:\n%s", RES, EP_APP_CMD, EP_APP_ERROR))
endif
This LogiView code uses four existing string variables and two new ones to call the wrapper for the EchoService. The EchoService returns the input arguments as a result, which is provided as a standard wrapper to test the infrastructure.
The userexit xutil_call_ws consists of the following parameters:
| EP_APP_CMD | Wrapper Name |
|---|---|
| EP_APP_CID_STRING | Correlation ID.
This is used to correlate a later response, which may come in asynchronously, to the initiating request. |
| EPP_APP_CONTENTS | Any string value that the wrapper must interpret. |
| RES | Result string from the Wrapper |
| EP_APP_RESULT | A new string variable that needs to be created to call the wrapper for the EchoService. |
| EP_APP_ERROR | A new string variable that needs to be created to call the wrapper for the EchoService. |
| The userexit provides a return code - "0" for success and any other number for errors. | |
Identify the classes you need for your wrapper and create a JAR file containing them.
Give your JAR files proper names to avoid naming conflicts with existing wrapper implementations.
For example, use a unique prefix that identifies your company.
If you need third party JAR files.
Ensure that they are not already provided by WebLogic server or the Agile e6 Web Services application. Do not use JAR files that duplicate features or come in conflict with the WebLogic server, like using different Web Service client frameworks.
|
Note: Your wrapper implementation will run inside and as part of a Web Service application deployed into WebLogic server. |
Copy all JAR files needed by your wrapper implementation to the custom staging directory for the Web Services application. This must be:
${ep_root}/staging/custom/WebServices/${app_name}.ear/APP-INF/lib.
|
Note: Do not copy any library that are already part of the Web Services application into the custom staging area. These libraries are only replaced by updates from Oracle, and are always put in the product staging area. |
Redeploy the Web Services into the WebLogic Server.
For complete details on how to deploy an application, see the Administration Guide for Agile e6.2.0.0 or the Hotfix Readme.
