Runtime Configuration for REST, SOAP and WEB¶

Runtime Configuration for REST, SOAP and WEB

Introduction¶

FWD supports both the conversion and runtime for 4GL web services. For details on how to convert REST and SOAP services, please see Converting REST and SOAP.

FWD will expose the REST and SOAP endpoint URLs, and once the target is found, it will delegate the call to an AppServer Agent. See Configuring Legacy Appservers how to setup the runtime for these.

The runtime support for SOAP and REST requires a FWD process account to be configured. This account can be shared between these configurations, as it will be used solely for establishing a FWD context so that it can connect to the AppServer and delegate the calls.

A process account exists in the directory under the /security/accounts/processes/ node. Its simple structure is this:

          <node class="process" name="<process-name>">
            <node-attribute name="enabled" value="TRUE"/>
            <node-attribute name="description" value="This is a sample process account"/>
            <node-attribute name="master" value="FALSE"/>
            <node-attribute name="server" value="FALSE"/>
            <node-attribute name="alias" value="<certificate-alias>"/>
          </node>

Once the FWD process account(s) have been added, a certificate must be loaded in the FWD Server's directory, for each added account. If you are using self-signed certificates and these were previously generated with FWD's Cryptography Setup Helper tool, you can use the same tool to generate the certificates and private keys for the newly added accounts (or, you can (re)generate self-signed certificates for all accounts, using the same tool). Otherwise, you must configure each process account with a certificate, following the Certificates instructions.

In the next sections, this chapter will describe how to configure the runtime such that properly converted REST, REST via WebHandler and SOAP services will execute in FWD.

REST¶

Service registration is being performed at FWD server startup, which loads and maps all the programs annotated as REST services.

The implicit basepath is /rest, and the implicit timeout is 10 seconds (which can be set to 0 to disable it). This timeout is inherited from the appserver's timeout.

The directory configuration is read from a rest/ node, which must exist under the server/default or server/<server-ID>. The values which need to be configured are:

rest/enabled, to explicitly enable the REST runtime support. Defaults to false.
rest/basepath, to specify the basepath. Defaults to /rest.
rest/alias, a process certificate alias associated with the worker's process account which will process the SOAP requests; this is the caller's process which will delegate the call to an Appserver agent process for execution. In FWD, this alias is needed to authenticate the worker thread with the FWD server, and to obtain a security context.
rest/keyStore, the key store with the certificate to authenticate this process. If is missing, the store will be built from the directory.
rest/storePassword, the store password, only if rest/keyStore is set.
rest/entryPassword, the key entry password, only if rest/keyStore is set.
rest/poolSize - the pool size of workers. Defaults to 10.
rest/appserver - the name of the appserver handling the requests. In FWD, this must be one of the entries in /server/default/appservers/ or /server/<id>/appservers. In OpenEdge configuration this will be specified as appservername.ROOT.REST.

Each queue of REST workers is ordered by the number of pending tasks to be executed - for each incoming request, the worker with the smallest number of pending tasks will be chosen.

The full directory node will look like:

        <node class="container" name="rest">
          <node class="boolean" name="enabled">
            <node-attribute name="value" value="TRUE"/>
          </node>
          <node class="string" name="basepath">
            <node-attribute name="value" value="rest/"/>
          </node>
          <node class="string" name="alias">
            <node-attribute name="value" value="<process-id>"/>
          </node>
          <node class="string" name="keyStore">
            <node-attribute name="value" value="/path/to/process/keystore"/>
          </node>
          <node class="string" name="storePassword">
            <node-attribute name="value" value="<password>"/>
          </node>
          <node class="string" name="entryPassword">
            <node-attribute name="value" value="<password>"/>
          </node>
          <node class="integer" name="poolSize">
            <node-attribute name="value" value="10"/>
          </node>
          <node class="string" name="appserver">
            <node-attribute name="value" value="<appserver-name>"/>
          </node>
        </node>

and the minimal configuration is:

        <node class="container" name="rest">
          <node class="boolean" name="enabled">
            <node-attribute name="value" value="TRUE"/>
          </node>
          <node class="string" name="alias">
            <node-attribute name="value" value="<process-id>"/>
          </node>
          <node class="string" name="appserver">
            <node-attribute name="value" value="<appserver-name>"/>
          </node>
        </node>

In the above examples, the following values must be specified and/or configured:

<appserver-name> - the name of the AppServer which will handle the requests. See Configuring Legacy Appservers
<process-id> - the name of a Process FWD account, which will be used to authenticate the REST handler threads and allow them to connect to the AppServer (running in the same FWD server). See
/path/to/process/keystore - if this is missing, it means the keystore is configured in the FWD directory. Otherwise, provide a full path to the process keystore with its private key.
<password> - only if an explicit keystore is used, must be the password for the key store or store entry, in clear-text.

To access a REST endpoint, use the secure port for the server followed by the service path, like https://localhost:7443/rest/path/to/service, where path/to/service is an explicit path for a certain REST service.

REST via WebHandler¶

Service registration is being performed at FWD server startup, which maps all the legacy classes configured as handlers.

The implicit basepath is /web, and the implicit timeout is 10 seconds (which can be set to 0 to disable it). This timeout is inherited from the appserver's timeout.

The directory configuration is read from a WebHandler/ node, which must exist under the server/default or server/<server-ID>. If the legacy application has only one legacy webapp deployed, then the values which need to be configured are:

WebHandler/enabled, to explicitly enable the web handler runtime support. Defaults to false.
WebHandler/basepath, to specify the basepath. Defaults to /web. This can be found in an existing OpenEdge configuration in an entry like wsRoot=http://host:port/static/webspeed and the basepath in this example would be /static/webspeed.
WebHandler/alias, a process certificate alias associated with the worker's process account which will process the web requests; this is the caller's process which will delegate the call to an Appserver agent process for execution. In FWD, this alias is needed to authenticate the worker thread with the FWD server, and to obtain a security context.
WebHandler/keyStore, the key store with the certificate to authenticate this process. If is missing, the store will be built from the directory.
WebHandler/storePassword, the store password, only if WebHandler/keyStore is set.
WebHandler/entryPassword, the key entry password, only if WebHandler/keyStore is set.
WebHandler/poolSize - the pool size of workers. Defaults to 10.
WebHandler/appserver - the name of the appserver handling the requests. In FWD, this must be one of the entries in /server/default/appservers/ or /server/<id>/appservers. In OpenEdge configuration this will be specified as appservername.ROOT.WEB.

WebHandler/handlers - a container with each handler from openedge.properties, following this structure:

            <node class="container" name="handlers">
              <node class="container" name="handler1">
                <node class="string" name="class">
                  <node-attribute name="value" value="oo.MyHandler"/>
                </node>
                <node class="string" name="path">
                  <node-attribute name="value" value="/fwd2"/>
                </node>
              </node>
              <node class="container" name="handler2">
                <node class="string" name="class">
                  <node-attribute name="value" value="oo.MyHandler2"/>
                </node>
                <node class="string" name="path">
                  <node-attribute name="value" value="/fwd3"/>
                </node>
              </node>
            </node>

where:

handlers is the name of the container node
handler# is the handler ID from openedge.properties
the class node is the fully-qualified name of the 4GL class
the path is the path served by this handler

optional WebHandler/defaultHandler, which specifies the fully qualified name of the 4GL class acting as default handler (added as lowest priority to the handlers list when FWD initializes the services)

Each queue of web service workers is ordered by the number of pending tasks to be executed - for each incoming request, the worker with the smallest number of pending tasks will be chosen.

The full directory node will look like:

        <node class="container" name="WebHandler">
          <node class="boolean" name="enabled">
            <node-attribute name="value" value="TRUE"/>
          </node>
          <node class="string" name="basepath">
            <node-attribute name="value" value="web/"/>
          </node>
          <node class="string" name="alias">
            <node-attribute name="value" value="<process-id>"/>
          </node>
          <node class="string" name="keyStore">
            <node-attribute name="value" value="/path/to/process/keystore"/>
          </node>
          <node class="string" name="storePassword">
            <node-attribute name="value" value="<password>"/>
          </node>
          <node class="string" name="entryPassword">
            <node-attribute name="value" value="<password>"/>
          </node>
          <node class="integer" name="poolSize">
            <node-attribute name="value" value="10"/>
          </node>
          <node class="string" name="appserver">
            <node-attribute name="value" value="<appserver-name>"/>
          </node>
          <node class="string" name="defaultHandler">
            <node-attribute name="value" value="<default-handler>"/>
          </node>
          <node class="container" name="handlers">
            <node class="container" name="handler1">
              <node class="string" name="class">
                <node-attribute name="value" value="oo.MyHandler"/>
              </node>
              <node class="string" name="path">
                <node-attribute name="value" value="/fwd2"/>
              </node>
            </node>
            <node class="container" name="handler2">
              <node class="string" name="class">
                <node-attribute name="value" value="oo.MyHandler2"/>
              </node>
              <node class="string" name="path">
                <node-attribute name="value" value="/fwd3"/>
              </node>
            </node>
          </node>
        </node>

and the minimal configuration is:

        <node class="container" name="WebHandler">
          <node class="boolean" name="enabled">
            <node-attribute name="value" value="TRUE"/>
          </node>
          <node class="string" name="alias">
            <node-attribute name="value" value="<process-id>"/>
          </node>
          <node class="string" name="appserver">
            <node-attribute name="value" value="<appserver-name>"/>
          </node>
          <node class="string" name="defaultHandler">
            <node-attribute name="value" value="<default-handler>"/>
          </node>
        </node>

In the above examples, the following values must be specified and/or configured:

<appserver-name> - the name of the AppServer which will handle the requests. See Configuring Legacy Appservers
<process-id> - the name of a Process FWD account, which will be used to authenticate the web service handler threads and allow them to connect to the AppServer (running in the same FWD server).
/path/to/process/keystore - if this is missing, it means the keystore is configured in the FWD directory. Otherwise, provide a full path to the process keystore with its private key.
<password> - only if an explicit keystore is used, must be the password for the key store or store entry, in clear-text.
the 4GL class names acting as handlers, as they appear in openedge.properties
the optional <defaultHandler>

To access a web service endpoint, use the secure port for the server followed by the service path, like https://localhost:7443/web/path/to/service, where path/to/service is an explicit path for a certain web service.

If multiple legacy webapps are deployed in OpenEdge, FWD configuration for this requires explicitly adding them under WebHandler node - in such case, each node will have the same syntax as the main WebHandler node, and it will be mandatory to specify a basePath for each node. The main WebHandler node will require only:

optional WebHandler/enabled, to explicitly disable the web handler runtime support. Defaults to false.
WebHandler/basepath, to specify the basepath. Defaults to /web. This can be found in an existing OpenEdge configuration in an entry like wsRoot=http://host:port/static/webspeed and the basepath in this example would be /static/webspeed.
all the other nodes will not be interpreted

Each webapp will be configured in their explicit node, like WebHandler/<webapp1>, WebHandler/<webapp2>, ... WebHandler/<webappN> nodes, each one for a different webapp, for which:

webAppX (the node name) can not be handlers or authentication
WebHandler/<webAppX>/basePath is mandatory - this will be a basepath which will be appended to the WebHandler/basePath value, resulting in i.e. /web/fwd1
all the other configurations are the same as specified above for the main WebHandler node.
each webapp can have its own appserver and authorization configured

An example for a configuration with two webapps in FWD:

        <node class="container" name="webHandler">
          <node class="boolean" name="enabled">
            <node-attribute name="value" value="TRUE"/>
          </node>
          <node class="container" name="fwdhandler">
            <node class="boolean" name="enabled">
              <node-attribute name="value" value="TRUE"/>
            </node>
            <node class="string" name="appserver">
              <node-attribute name="value" value="app_server"/>
            </node>
            <node class="string" name="alias">
              <node-attribute name="value" value="appserver_agent"/>
            </node>
            <node class="string" name="basepath">
              <node-attribute name="value" value="/gcd1"/>
            </node>
            <node class="integer" name="poolSize">
              <node-attribute name="value" value="3"/>
            </node>
            <node class="container" name="handlers">
              <node class="container" name="handler1">
                <node class="string" name="class">
                  <node-attribute name="value" value="FwdHandler"/>
                </node>
                <node class="string" name="path">
                  <node-attribute name="value" value="/fwdHandler/{id}/{value}"/>
                </node>
              </node>
              <node class="container" name="handler2">
                <node class="string" name="class">
                  <node-attribute name="value" value="FwdHandler"/>
                </node>
                <node class="string" name="path">
                  <node-attribute name="value" value="/fwdHandler/{id}"/>
                </node>
              </node>
              <node class="container" name="handler3">
                <node class="string" name="class">
                  <node-attribute name="value" value="FwdHandler"/>
                </node>
                <node class="string" name="path">
                  <node-attribute name="value" value="/fwdHandler"/>
                </node>
              </node>
            </node>
          </node>
          <node class="container" name="myhandler">
            <node class="string" name="appserver">
              <node-attribute name="value" value="app_server"/>
            </node>
            <node class="string" name="alias">
              <node-attribute name="value" value="appserver_agent"/>
            </node>
            <node class="integer" name="poolSize">
              <node-attribute name="value" value="3"/>
            </node>
            <node class="string" name="basepath">
              <node-attribute name="value" value="/gcd2"/>
            </node>
            <node class="container" name="handlers">
              <node class="container" name="handler1">
                <node class="string" name="class">
                  <node-attribute name="value" value="oo.MyHandler"/>
                </node>
                <node class="string" name="path">
                  <node-attribute name="value" value="/fwd2"/>
                </node>
              </node>
            </node>
            <node class="string" name="defaultHandler">
              <node-attribute name="value" value="oo.DefaultHandler"/>
            </node>
            </node>
          </node>

In this example, the two webapps will be available via https://localhost:7443/web/gcd1/path/to/service and https://localhost:7443/web/gcd2/path/to/service. Note that in OpenEdge, the webapps are deployed on different ports, but in FWD there is a single port, and the basepath for each webapp will be used to distinguish between them.

SOAP / Web Services Adapter (WSA)¶

Service registration is being performed at FWD server startup, which loads and maps all the programs annotated as SOAP services.

The implicit basepath is /ws, and the implicit timeout is 10 seconds (which can be set to 0 to disable it). This timeout is inherited from the appserver's timeout.

The directory configuration is read from a soap/ node, which must exist under the server/default or server/<server-ID>. The values which need to be configured are:

soap/enabled, to explicitly enable the SOAP runtime support. Defaults to false.
soap/basepath, to specify the basepath. Defaults to /ws. This can be found in an existing OpenEdge configuration in an entry like wsaUrl=http://host:port/soap and the basepath in this example would be /soap.
soap/alias, a process certificate alias associated with the worker's process account which will process the SOAP requests; this is the caller's process which will delegate the call to an Appserver agent process for execution. In FWD, this alias is needed to authenticate the worker thread with the FWD server, and to obtain a security context.
soap/keyStore, the key store with the certificate to authenticate this process. If is missing, the store will be built from the directory.
soap/storePassword, the store password, only if soap/keyStore is set.
soap/entryPassword, the key entry password, only if soap/keyStore is set.
soap/poolSize - the pool size of workers. Defaults to 10.
soap/appserver - the name of the appserver handling the requests.In FWD, this must be one of the entries in /server/default/appservers/ or /server/<id>/appservers. In OpenEdge configuration this will be specified as appservername.ROOT.SOAP.
soap/wsdl - comma-separated list of wsdl file names.
soap/wsdlHost - the host added at runtime to the wsdl soap:address location. Used to specify the external host/IP used to access the soap resources.
soap/wsdlPort - the port added at runtime to the wsdl soap:address location. Used to specify the external port used to access the soap resources. 443 by default.

Each queue of SOAP workers is ordered by the number of pending tasks to be executed - for each incoming request, the worker with the smallest number of pending tasks will be chosen.

The full directory node will look like:

        <node class="container" name="soap">
          <node class="boolean" name="enabled">
            <node-attribute name="value" value="TRUE"/>
          </node>
          <node class="string" name="basepath">
            <node-attribute name="value" value="ws/"/>
          </node>
          <node class="string" name="alias">
            <node-attribute name="value" value="<process-id>"/>
          </node>
          <node class="string" name="keyStore">
            <node-attribute name="value" value="/path/to/process/keystore"/>
          </node>
          <node class="string" name="storePassword">
            <node-attribute name="value" value="<password>"/>
          </node>
          <node class="string" name="entryPassword">
            <node-attribute name="value" value="<password>"/>
          </node>
          <node class="integer" name="poolSize">
            <node-attribute name="value" value="10"/>
          </node>
          <node class="string" name="appserver">
            <node-attribute name="value" value="<appserver-name>"/>
          </node>
          <node class="string" name="wsdl">
            <node-attribute name="value" value="<def.wsdl,def2.wsdl>"/>
          </node>
          <node class="string" name="wsdlHost">
            <node-attribute name="value" value="<external-host>"/>
          </node>
          <node class="integer" name="wsdlPort">
            <node-attribute name="value" value="<external-port>"/>
          </node>
        </node>

and the minimal configuration is:

        <node class="container" name="soap">
          <node class="boolean" name="enabled">
            <node-attribute name="value" value="TRUE"/>
          </node>
          <node class="string" name="alias">
            <node-attribute name="value" value="<process-id>"/>
          </node>
          <node class="string" name="appserver">
            <node-attribute name="value" value="<appserver-name>"/>
          </node>
        </node>

In the above examples, the following values must be specified and/or configured:

<appserver-name> - the name of the AppServer which will handle the requests. See Configuring Legacy Appservers
<process-id> - the name of a Process FWD account, which will be used to authenticate the SOAP handler threads and allow them to connect to the AppServer (running in the same FWD server).
/path/to/process/keystore - if this is missing, it means the keystore is configured in the FWD directory. Otherwise, provide a full path to the process keystore with its private key.
<password> - only if an explicit keystore is used, must be the password for the key store or store entry, in clear-text.

To access a SOAP endpoint, use the secure port for the server followed by the base path, like https://localhost:7443/ws.

The WSDL can be accessed using the base path following the service name, like https://localhost:7443/ws/ServiceName/wsdl.

Project

General

Profile

FWD

Wiki

Runtime Configuration for REST, SOAP and WEB¶

Introduction¶

REST¶

REST via WebHandler¶

SOAP / Web Services Adapter (WSA)¶