Project

General

Profile

Wiki » Documentation » Conversion Handbook »

Converting REST and SOAP

Introduction

FWD provides support for REST and SOAP (a.k.a. Web Services Adapter or WSA) in both "classic appserver" and PASOE modes. This support was added in FWD v4.0. The support is available for both conversion and runtime. For details on the configuration of the runtime, see Runtime Configuration for REST and SOAP.

This chapter describes how to configure the conversion to properly handle the REST and SOAP services.

The REST support is a mechanism to export REST APIs and to map their execution into 4GL procedures/functions. Support for REST (REST adapter for classic appserver and REST transport for PASOE) was implemented in #3855.

The WSA is a mechanism to export SOAP APIs and to map their execution into 4GL procedures/functions. Support for Web Services Adapter (classic appserver) / SOAP transport (PASOE) was implemented in #3310.

Source Code

The configuration specified in this chapter does not add any new source procedures or classes to the conversion. It is important that you setup the source file list properly as specified in Running the Front End Conversion.

REST via .paar Files

In addition to the normal conversion process, it is necessary to provide all of the REST artifacts to FWD so that these can be transformed (during conversion) into Java annotations in the converted Java code. Those annotations are necessary for the FWD runtime to properly expose those converted procedures as REST services.

  • Place all REST artifacts (.paar files) in the project at some location (e.g. ./abl/rest/).
  • Add a rest-cfg entry in cfg/p2j.cfg.xml to point to the artifacts and activate the REST conversion processing. There are 2 forms of this parameter.
    • single file mode: <parameter name="rest-cfg" value="./abl/rest/my-awesome-rest-service.paar" />
    • project relative directory which can hold one or more .paar files: <parameter name="rest-cfg" value="./abl/rest/" />

After the conversion is done, all the REST mapping and API exports will be defined as annotations in the converted Java source code. Additional runtime configuration will be needed to activate these APIs. See REST.

REST via WebHandler

In 4GL, custom services can be written by explicitly implementing the request/response for a HTTP request, in a WebHandler implementation.

The conversion will rely on a .properties files describing the web services and their handlers. A standard section looks like:

[srv.goldencode.WEB]
handler1=FwdHandler: /fwdHandler/{id}/{value}
handler2=FwdHandler: /fwdHandler/{id}
handler3=FwdHandler: /fwdHandler

  • The .properties file describing the handler(s) must be placed in some location like abl/web
  • In cfg/p2j.cfg.xml, add a webhandler-cfg entry to point to this file, like <parameter name="webhandler-cfg" value="abl/web/webhandlers.properties" />.

Multiple .properties files are not supported at this time.

The conversion will emit annotations to each class (e.g FwdHandler) configured in the property file, describing its path (e.g. /fwdHandler/{id}/{value})and its lookup priority index.

SOAP / Web Services Adapter (WSA)

In addition to the normal conversion process, it is necessary to provide all of the WSA artifacts to FWD so that these can be transformed (during conversion) into Java annotations in the converted Java code. Those annotations are necessary for the FWD runtime to properly expose those converted procedures as SOAP endpoints.

  • Place all WSA artifacts (.wsm files) in the project at some location (e.g. ./abl/wsa/).
  • Add a soap-cfg entry in cfg/p2j.cfg.xml to point to the artifacts and activate the WSA conversion processing (<parameter name="soap-cfg" value="./abl/wsa/"/>).

After the conversion is done, all the SOAP mapping and API exports will be defined as annotations in the converted Java source code. For each service associated with a .wsm file, FWD will also generate a <service-name>.wsdl file, which will be loaded at runtime; this file will be placed in the root Java package for the converted Java code. To ensure it is available at runtime, make sure it is included in the application jar file.

Additional runtime configuration will be needed to activate these APIs. See SOAP.

Generating WSDL

One of the outputs of a conversion run (full or incremental) will be .wsdl files. Starting in FWD v4, there is a tool which, when run on a completely converted project, will re-generate all WSDL files. While in the conversion project, it can be run using (no arguments required):

java -classpath /path/to/p2j.jar com.goldencode.p2j.convert.GenerateWsdl -DP2J_HOME=.

It will process all program files marked 'with_services' and will generate the WSDLs for them. The process is read-only in AST terms, only .wsdl files will be re-generated.

Incremental and full conversion already will generate all WSDL files, keeping them up-to-date. This tool is only used if the WSDL files need to be re-generated on demand. For example, if FWD has changes in the WSDL generation code which do not otherwise affect the project conversion.

© 2018-2021 Golden Code Development Corporation. ALL RIGHTS RESERVED.