It is possible to publish your own Web Service using OpenEdge. The Web Service Adapter (WSA) has been designed for this purpose and is a Java based solution which requires a Java Servlet Engine (JSE) to work. The WSA can be managed via the Progress or OpenEdge Explorer tool or via the WSAMAN command-line utility. This article will only discuss the Progress or OpenEdge Explorer as a means of managing the WSA. For further details and proper syntax for the WSAMAN utility, please refer to the "OpenEdge Application Server: Administration" documentation.
There are a couple of steps which are required to publish your own Web Service. The general steps are as follows (with an example where possible):
Configure the WSA with a JSE of your choice (Tomcat being the most commonly used): How to setup the Web Services Adapter (WSA) with Tomcat How to configure the WSA with ServletExec Servlet Engine 4.x as a Web application How to setup Macromedia JRun 4 with the sample Web Services Adapter (WSA)
- Develop an AppServer application which you would like to publish as a Web Service. For example:
/* roundtrip.p */
DEFINE INPUT PARAMETER ipcText AS CHARACTER NO-UNDO.
DEFINE OUTPUT PARAMETER opcText AS CHARACTER NO-UNDO.
opcText = ipcText + "- Ok!".
/* end */
Note: The WSA requires an AppServer to function properly. When using the WSA, State-Free is the recommended Operating Mode for an AppServer. We will be using a State-Free AppServer for this example. We will also make use of a NameServer, so make sure it's started and that the AppServer has registered itself with the Name Server.
- Compile your AppServer application to get the r-code, e.g.: roundtrip.r
- Generate the Web Service Mapping (WSM)
Using the r-code from the AppServer application, generate the Web Service Mapping (WSM) file through the Proxy Generator (ProxyGen). The WSM maps the Progress 4GL procedures that run on an AppServer so they are readily callable from any client that can access a standard Web Service, e.g.:
- Open the Proxy Generator.
- Choose File / New from the menu.
- On the AppObject tab enter "WSTest".
- Click on the "New" button next to the "Propath Components" section.
- Choose the directory where your AppServer application r-code is located.
- Choose Procedure / Add / Non-persistent from the menu.
- Add roundtrip.r
- Choose File / Generate from the menu.
- In the General tab only select "Web Services".
- Uncheck the "Use Default" option and enter the name of your AppServer in the "AppService" field.
- Enter the directory where you want the WSM to be output in the "Output Dir" section.
- Go to the Web Services tab.
- Enter a Namespace for your Web Service.
- Enter the "URL for the WSA" which was configured in step 1.
- Choose "Free" for the Session Model.
- Choose "Document/Literal" in the WSDL Settings.
- Click on "OK" to generate the WSM file.
- Add the roundtrip.r to the AppServer working directory
- Deploy and enable your Web Service by using the WSM file created by the ProxyGen, e.g.:
- Open the Progress or OpenEdge Explorer (OEE) tool and connect to the AdminServer.
- Expand the Web Services Adapter node. (Progress Explorer) or Select Resources and then Sort by: Name (if using OEE).
- Right-click on "wsa1" and choose Status. (Progress Explorer) or Select "wsa1" and look at WebServices Adapter (if using OEE).
- This should return a message saying that the WSA is running (Progress Explorer) or if using OEE go into Control to see if it is running.
- Right-click on "wsa1" and choose Properties (Progress Explorer) or if using OEE select Configuration.
- Go to Security and make sure "Enable Web Services" is checked. If not enabled in OEE, then select Edit and make the recommended changes and then Save.
- Make sure "Enable WSA Administration" is checked.
- Restart your JSE if you made any changes here.
- Expand "wsa1".
- Right-click on the "Web Services" node and choose "Deploy A New Web Service". (Progress Explorer). If using OEE, then select Deploy to deploy a new Web Service.
- Select the WSM file which was created earlier by ProxyGen.
- Your Web Service (WSTest) should now be displayed as a child node.
- Right-click on WSTest and choose Enable.
- In OEE, under the "Deployed Web Services" section, select the "Status Enablement" button, then click the ENABLE button. This sets the serviceAvailable property in the <tomcat-dir>\webapps\wsa\wsa1\<web service name>.props file. Verify that under "Status Enablement" and "Application Properties" the location and info for the AppServer is correct, more specifically the host information.
To verify that your Web Service is available, access its WSDL document through the WSA URL. The URL syntax to retrieve the Web Services WSDL list from the WSA is:
http[s]://host:port[/web-server-context]/wsa-webapp-context/wsa-instance/wsdl?
The URL syntax to retrieve the Web Services WSDL from the OpenEdge Web Services Adapter is:
http[s]://host:port[/web-server-context]/wsa-webapp-context/wsa-instance/wsdl?targetURI=<your target URI>
Examples:
http://localhost:8080/wsa/wsa1/wsdl?
http://localhost:8080/wsa/wsa1/wsdl?targetURI=urn:tempuri-org
You can now use the WSDL document to access your Web Service from a Web Service client.
Note: Please use the same steps when upgrading the WSA to a new OpenEdge version.
Consuming the Webservice:
OpenEdge has native ABL support for Web Services. In order to access a Web Service via ABL, you will need to follow these general steps:
Use the WSDL Analyzer to provide HTML documentation on the interface that the WSDL describes. This documentation includes 4GL sample code to use.
Based on the documentation of the WSDL Analyzer develop your 4GL application which accesses the Web Service.
Note: For in-depth information on how to access a Web Service through ABL, please refer to the "OpenEdge Development: Web Services" documentation.
- Run the WSDL Analyzer within a Proenv window: bprowsdldoc http://<tomcat host>:8080/wsa/wsa1/wsdl?targetURI=<URI name chosen at proxygen> DOC
- Open the index.html document inside the DOC directory which is created by the WSDL Analyzer.
- By clicking on a link in the Port types section you will get to the documentation which explains how to access this Web Service via 4GL.
- On the page for a specific Port type, the connection details will contain code samples on how to connect to this specific service. The Operation (internal procedure) detail section documents the ABL signatures for the operations provided by the WebService.
- By using this generated documentation you will be able to create an ABL application, e.g.:
DEFINE VARIABLE hWebService AS HANDLE NO-UNDO.
DEFINE VARIABLE hWSTestObj AS HANDLE NO-UNDO.
DEFINE VARIABLE ipcText AS CHARACTER NO-UNDO.
DEFINE VARIABLE result AS CHARACTER NO-UNDO.
DEFINE VARIABLE opcText AS CHARACTER NO-UNDO.
CREATE SERVER hWebService.
hWebService:CONNECT("-WSDL 'http://<tomcat host>:8080/wsa/wsa1/wsdl?targetURI=<URI name>'").
RUN WSTestObj SET hWSTestObj ON hWebService.
FUNCTION roundtrip RETURNS CHARACTER
(INPUT ipcText AS CHARACTER,
OUTPUT opcText AS CHARACTER)
IN hWSTestObj.
RUN roundtrip IN hWSTestObj(INPUT ipcText, OUTPUT result, OUTPUT opcText).
DISP opcText.
