Ask Reuben

Starting With Genero Web Services (part 3 of 3)

How is a Genero Web Service launched by Genero Application Server?

What is the pooling concept with regards to Genero Web Services?

In this last part of this series on starting out with Genero Web Services, I look at how Genero Web Services and Genero Application Server fit together.  We will take the example from the last article and run it in the Genero Application Server.


Role of Genero Application Server

In production it is expected you would use Genero Application Server (GAS) and a Web Server to manage web service requests.  Like with a Web Application, GAS takes the URL and interprets it to indicate what program to use.  Only this time instead of starting the program, the program may already be running and listening, and if the program is busy the request maybe queued.

Section 9 of this earlier Ask Reuben article is relevant only instead of ua to indicate a Universal Rendering Web Application to start, ws will appear in the URL and indicate what web service to look for.  That is if a program needs to be started, the EXECUTION node parameters  ENVIRONMENT, PATH, DVM, MODULE, PARAMETERS will be used to start the web service program.

export ENVIRONMENT 
cd PATH
DVM MODULE PARAMETERS

To get calculator running via GAS, create the following xcf named “calculator.xcf” and place it in $FGLASDIR/appdata/services


<?xml version="1.0"?>
<!--
  FOURJS_START_COPYRIGHT(U,2000)
  Property of Four Js*
  (c) Copyright Four Js 2000, 2021. All Rights Reserved.
  * Trademark of Four Js Development Tools Europe Ltd
    in the United States and elsewhere

  Four Js and its suppliers do not warrant or guarantee that these samples
  are accurate and suitable for your purposes. Their inclusion is purely for
  information purposes only.
  FOURJS_END_COPYRIGHT
-->
<APPLICATION Parent="ws.default"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:noNamespaceSchemaLocation="https://www.4js.com/ns/gas/3.00/cfextws.xsd">
  <EXECUTION>
    <PATH>!!REPLACE_WITH_YOUR_LOCATION!!</PATH>
    <MODULE>calculator_server_main.42m</MODULE>
  </EXECUTION>
</APPLICATION>

With httpdispatch running using the default port, if you type into the browser or into curl the following URL

http://localhost:6394/ws/r/calculator/Calculator/add?a=2&b=3

then you should get the same behaviour as in last weeks article.  The web service will respond with the result of the calculation.

The first calculator is the name of the .xcf that is in the default .xcf that GAS will look for.  The second Calculator is the entry from the RegisterRestService call we saw in the previous article.

After the request has run if you do a ps -ef | grep "gwsproxy" you should see that there is a gwsproxy process started.

if you do a ps -ef | grep "fglrun" you should see the fglrun process that has been started.  The program is waiting for the next request.

The gwsproxy is similar to the uaproxy process only it is what manages the web service requests.  It differs in that for each web service program there will be a single gwsproxy process.  Again this is where the architecture diagram comes in handy to see the relationship between these processes.

If you enter the monitor URL http://localhost:6394/monitor you will see that there is an active  GWS proxy …



… and if you drill down you can see the data held about the web service proxy details and statistics …



Assuming the default directories, if you look in $FGLASDIR/appdata/log/httpdispatch you will the log files for these web services as well.

At this point you have taken a Web Service and started and made a request to it via GAS, and can look in the monitor and log to analyse more detail.

For more .xcf examples, in $FGLDIR/demo/WebServices there are a number of .xcf for web services demos.  Also if you dig down into $FGLDIR/web_utilities/services there are a number of .xcf files to run the various GIP and related web services.


Services Pool

When it comes to hosting Web Services, an important concept to understand is the concept of the Services Pool.  This is discussed in this article with some good diagrams.

When managed by Genero Application Server, the important difference between a web service and a web application is that when a web application request is received a new Genero program is started.  With a web service request, there can instead be a Genero program already running that will be used to service the request or in times of high demand a new program can be started to service the request.  If demand gets too high, the request can be queued and processed when one of the Web Service programs finishes processing its current request.

Inside a Web Service .xcf this is controlled by the POOL entry.    Its values I like think are failr self-explanatory

START – how many fglrun processes to start when the Genero Application Server is started

MIN_AVAILABLE – the minimum number of fglrun processes to keep running to service that Web Service

MAX_AVAILABLE – the maximum number of fglrun processes that are allowed to run that can be dedicated to servicing that Web Service

MAX_REQUESTS_PER_DVM – stop an fglrun process once it has processed that many requests.

There are three more settings  in the TIMEOUT node that you will need to be aware of

DVM_AVAILABLE – how long to wait for a web service process to start

KEEP_ALIVE – how long to keep a gwsproxy running when there is no requests

REQUEST_RESULT -how long to wait for a web service process to return a result before assuming that something bad has happened.

Within these constraints the Genero Application Server takes it upon itself to start and stop the fglrun processes as necessary to meet the demand of requests coming in.  It measures how long it takes on average to start another fglrun processes, how long the average request takes to return a value, and what the current demand is.  Based on this it may start another process upto the maximum of MAX_AVAILABLE, or it may stop an idle Web Service process until only MIN_AVAILABLE are running.  If there is no activity at all for KEEP_ALIVE then it may stop the Web Service gwsproxy and fglrun processes all together.

If you want to do exercises with this, using the calculator add example, add a SLEEP into the add function so that the add function takes some time to return a value.

For example, add a SLEEP 10 and set MAX_AVAILABLE to 1.  Then in two terminal sessions (or two browser tabs)  make two requests to the same web service in close succession.  What you should see is one response after 10 seconds and then the second response another 10 seconds later.  The second request had to wait for the first one to finish.

Using SLEEP like this you can do some experimentation and understand how the POOL process works by slowing the responses down so that you can see them.

Normally Web Services are quite quick to respond and it can be surprising how quick they are.  In the GAS Monitoring page you can view the average request time and it will normally be in the region of a tenth or a hundredth of a second.


Summary

Hopefully these three articles have given you an insight into Genero Web Services.  The key point is to get an example like the calculator one I used and have that as the building block of your web service knowledge.  The second example I would move onto is one that has a number of end points to perform the CRUD operations on a database table, and then start adding complexity for error handling.  Then from there add more examples as you need, perhaps uploading files/downloading files.  Also look at the examples around, not just what we have beneath $FGLDIR/demo/WebServices and $FGLDIR/web_utilities/services but also in the popular API’s out there.

What you will also find is that although there are standards, not everyone confirms to them.  Not all web service hosts will be able to provide an openapi or wsdl from which you can generate a client.  At that point you will have to use the low level framework like developers in other languages.  Using the generated code from the high-level framework will give you an insight into the code patterns required, and FGLWSDEBUG and the logs can show you what is being passed backwards and forwards.

Finally as per my article on DVM_AVAILABLE, Web Service invalidation is something you are likely to encounter at some point.  You are also likely to not get the environment right at some point for your launched Web Service via Genero Application Server (point 10 here).  So make sure they are part of your troubleshooting routine before contacting support.