Ask Reuben

Structuring GAS .xcf

Do I have to restart GAS everytime I change .xcf ? 

Do I have to redefine a GAS configuration entry multiple times in every individual .xcf ?

On the support desk, we see some .xcf that could be structured better.  There are some concepts that you should consider when working on your GAS configuration.

  • Configuration for GAS vs Configuration for Web and Service applications
  • Abstract Parent Application
  • Overriding resources with -E argument

Configuration for GAS vs Configuration for Web and Service Applications

The GAS configuration file allows you to define Web Applications and Web Service applications in it.  This is done inside the APPLICATION_LIST and SERVICE_LIST elements.  However if you define all your web applications and web service applications in your GAS configuration file then every-time you want to make a change to a Web Application or a Web Service including adding or removing a Web Application or Web Service then you have to stop/start the GAS dispatcher in order for that change to take effect.

A better approach is to define every individual Web Application and Web Service in its own individual specific configuration file. You can make changes to these individual configuration files without having to stop/start the GAS dispatcher.

If you look in $FGLDIR/web_utilities/services and $FGLDIR/demo/WebServices you will notice that we ship a number of these individual specific configuration files.

The key element in the main GAS configuration .xcf is the GROUP element (defined separately for Web Applications and Web Services).  This tells the GAS where to look for these individual web application and web service configuration files.  For instance the entry below in the SERVICE_LIST element of $FGLASDIR/etc/as.xcf …


<GROUP Id="demo">$(res.path.fgldir.demo.services)</GROUP>

… says that if the URL contains “demo” then it will look for the Web Service .xcf files in $FGLDIR/demo/WebServices.


Abstract Parent Application

When it comes to the individual Web application and Web service .xcf file you should not need to repeat configuration values . In fact the only unique thing in these .xcf files should be what is unique to the Web Application or Web Service, and what configuration settings you may want to change often.  If we look at the Web Services demo calculator file ($FGLDIR/demo/WebServices/Calculator.xcf) …


<APPLICATION Parent="ws.default"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:noNamespaceSchemaLocation="https://4js.com/ns/gas/5.00/cfextws.xsd">
  <EXECUTION>
    <PATH>$(res.path.fgldir.demo.services)/calculator/server</PATH>
    <MODULE>CalculatorServer.42r</MODULE>
    <ACCESS_CONTROL>
       <ALLOW_FROM>$(res.access.control)</ALLOW_FROM>
    </ACCESS_CONTROL>
  </EXECUTION>
</APPLICATION>

… we see that the only unique entries are the PATH value (directory where the application is located), the MODULE (the name of the application file), and there is an ACCESS_CONTROL to allow access to this individual web service application to be overridden.  (Typically access would be denied on a production server but occasionally you may want to allow access to this web service to troubleshoot).

Everything else is defined by the value of the Parent attribute (Parent=”ws.default”) in the APPLICATION node.  In $FGLASDIR/etc/as.xcf we will find …


<APPLICATION Id="ws.default" Abstract="TRUE">
        <PROXY>$(res.gwsproxy)</PROXY>
        <EXECUTION Using="cpn.ws.execution.local"/>
        <TIMEOUT Using="cpn.ws.timeout"/>
</APPLICATION>

… which is what is known as an Abstract Application.  Note the Abstract=’TRUE” attribute.  In this Abstract Application we have defined the PROXY, EXECUTION, TIMEOUT values once and these will be reused by any Web Service application that has Parent=”ws.default” specified.

Your configuration is expected to be similar.  In the GAS configuration file, you define one or more Abstract Applications that hold the configuration you expect to be common for all your Web Applications and Web Services.  Then for every accessible Web Application and Web Service in your solution, you would reference the appropriate Abstract Application via the Parent attribute value.


Overriding Resources with -E argument

With multiple dispatchers running on the same server, care should be taken with the configuration so that the dispatchers are independent on one another.  However it does not make sense to make near identical copies of 100+ line files when only 4 things are different.  This means everytime you change something, you have to change it in multiple near identical files.

By careful definition of resources and use of the -E argument when the dispatcher is launched, you can have one GAS configuration file and override values in this file by use of the -E argument.

In the GAS configuration, define values as a RESOURCE .  Then at runtime override the resource value with the -E argument.   For example, the following two commands …

httpdispatch -f /gas/my_config.xcf -E res.ic.server.port=6301 -E res.ic.admin.port=6311 -E res.appdata.path=/gas/appdata1 -E=/gas/socket1  
httpdispatch -f /gas/my_config.xcf -E res.ic.server.port=6302 -E res.ic.admin.port=6312 -E res.appdata.path=/gas/appdata2 -E=/gas/socket2

… starts two instances of httpdispatch using the same configuration file except for the things that should be  unqiue when using multiple dispatchers.


Summary

For developers, laziness is a virtue.  Why write something a hundred times when you can refer to it once and refer to it many times. Same principal applies in configuration.  If you find yourself writing the same configuration in multiple places, ask yourself can I define it one place and refer to it.  If it seems odd that you have to do something, such as stopping and starting GAS to make a change, look to see if there is something that looks and feels right.