OpenGTS configuration mechanism

So far we've gained a good insight how the Tracking System is deployed from sources to binaries. Before analyzing the Java code it is necessary to look at the multitude of configuration possibilities. Basically the configuration is controlled by the seven *.conf and five *.xml (and implicitly *.dtd) files in the %GTS_HOME% folder. Anyhow you should be aware that these configuration files are distributed to different web applications with the deployment process and accessed on different levels.

The web applications are packaged in war files to become totally independent of any files in %GTS_HOME%.   Although they do depend on a GTS Database (Entity Relation Model) reachable via URL and portnumber. The ...OpenGTS_2.4.3\build\<webapp> folders represent the intermediate results with all files except the jar libraries in ...build\lib, which are then added in the packaging step to a war archive - as described earlier.

config file distribution

A peek into the web archives reveals that events .war,  gc101.war and gprmc.war
include common.conf, config.conf, custom.conf, system.conf, webapp.conf and private.xml
and that track.war additionally holds timezones.conf, dcservers.xml and reports.xml
and all wars include the standard web.xml - one file source for all apps!

You have to be aware of this file redundancy, before starting any modification; and that besides the distribution via ant build the war files the deployment to Tomcat adds two more versions of the original configuration: a copy of the war file from GTS to Tomcat and the unpacked version in the ...\Tomcat\webapps folder. Some modifications can be tested by simply changing the config in the webapps folder, but all modifications will be destroyed with the next ant build and Tomcat deploy process described below!

interactive configuration

It is important to realize that the ant build process is part of the installation on the target system and that the process should not only work for the initial installation! The process can always be applied to introduce small modifications, which also have to transferred to and from the development version.

This is pointed out in the OpenGTS_Config.pdf:

5.3.b) IMPORTANT: Redeploy all servlets after modifying any runtime configuration file Changes to any of "private.xml", "reports.xml", "webapp.conf", "common.conf", "system.conf", or "custom.conf" files (or other ".xml" or ".conf" file) will require that the "track.war" (as well as the other servlets) file be re-built and re-deployed.

In order to experience the configuration changes interactively the ant build script provides a useful setup to look at the changes after a quick recompilation. The track deployment is described in 

5.4) Compiling/Installing the "track.war" Java Servlet. 

The ant track.deploy target is not part of the ant all compilation. It provides a helpful setup with Tomcat and browser without using an IDE.

Here's what you should do

open a console and change directory: >cd %GTS_HOME%
test the installation with >ant all 
or > ant -buildfile buildLite.xml all

If you get an BUILD SUCCESSFUL you can start with the configuration setup

open another console and change directory: >cd %CATALINA_HOME%\bin
start Tomcat >startup.bat
click on this URL: http://localhost:8080/track/Track

Now you should see the logon starting page to the Tracking Frontend with english descriptions,
i.e.'Enter your Login ID and Password'.

Next you should follow the instructions at the beginning of the private.xml file:

For instance, the "locale" attribute on the "Domain" tag currently specifies the following: locale="en" If you wanted to set the current locale to Spanish, you replace this value with locale="es"

If you execute: > ant -buildfile buildLite.xml track.deploy 
the output should show

track.prepare:
     [copy] Copying 1 file to C:\prox\OpenGTS_2.4.3.lite\build\track\WEB-INF
track.war:
   [delete] Deleting: C:\prox\OpenGTS_2.4.3.lite\build\track.war
      [war] Building war: C:\prox\OpenGTS_2.4.3.lite\build\track.war
track.deploy:
     [copy] Copying C:\prox\OpenGTS_2.4.3.lite\build\track.war
           to C:\prox\Tomcat\webapps\track.war

This means that ant has copied only the new version of private.xml to the \track folder, rebuild the track.war and copied it to the Tomcat destination. If you can rely on Tomcats autodeploy (set autoDeploy="true" in server.xml) feature the web app should be redeployed after a few seconds, but you can't. You can check the Tomcat\webapps\track folder to see, if it is in/complete and you should keep an eye on the Java console:

INFO: Undeploying context [/track]
The web application [/track] created a ThreadLocal ... but failed to remove it
when the web application was stopped. This is very likely to create a memory leak.
[C:\prox\...\webapps\track\images\led] could not be completely deleted.
The presence of the remaining files may cause problems
INFO: Deploying web application archive track.war

You can manually assist the deployment by deleting the ...Tomcat\webapps\track.war and give Tomcat about 10 seconds time to remove the ...Tomcat\webapps\track folder automatically. The you can re/run ant track.deploy to finally refresh the browser and see the Logon page with 'Teclee su usuario y contraseña'.

So this is a good way to get familiar with some settings in the configuration files - as long as you keep an eye on the console outputs and help out with deleting the track.war file from the webapp directory. Later we will see that this process is more comfortable by giving Tomcat control to the IDE. With Eclipse you can modify the resources (which will be described in detail later) wait a few seconds and refresh the browser to see the changes - even, if a user is already logged on to the GTS the current view will be updated!

collecting i18n properties

Besides the configuration files listed above there is another pseudo configuration issue you should be aware of. In the 'default' configuration of the OpenGTS distribution you will see several 'vehicle' captions (vehicle map, vehicle detail, vehicle admin etc.). Of course it is convenient to extract these captions to the external LocalStrings_??.properties, where ?? stands for the ISO language code, which is an international standard.

A problem that could occur is that you want to track people, vehicles and other real objects with one Tracking System. In this case there is no mechanism in OpenGTS to switch the captions accordingly. The property files are tied to the compiled java class files. But as this is only a superficial observation the conclusion goes deeper. With the current OpenGTS you have to setup a complete Tracking System for different 'real objects' you will want to track. This is acceptable, since not only the caption, but the database attributes and their frontend representations would have to be adopted accordingly.

org.opengts.tools 

As analyzed earlier the tools package is not part of the GTS runtime.
It provides useful tools to validate the GTS installation.

MergeLocalStrings

If you want to modify the predefined language and tracking domain (vehicles, people..) the tools package provides a convenient tool to look for the property files. With the command line:

MergeLocalStrings -scan=D:\wsp.mp\OpenGTS\src

you will get a list of all language property files hidden in the Java source file directories. On the other hand this can also be achieved easily with a find on commandline ;)

Note that the "en" files represent the full set provided with the distribution. Now you can choose a language and modify the files according to your domain. You might as well modify the "en" files from vehicles to people, but before doing so it's always a good idea to save a backup of the original files. This can also be done with MergeLocalStrings, but there is a little catch. If you run:

MergeLocalStrings -merge=D:\wsp.mp\OpenGTS\src

the special characters masked with a UTF8 escape sequence will be read as UTF8 characters and written to LocalStrings_??.properties.old with UTF8 characters:

Passwort \u00E4ndern    -> Passwort ändern
Ger\u00E4te-Administration -> Geräte-Administration

So you can loose a lot of work. And also the merge mode only works once, otherwise you'll get

Scan error: Old 'LocalStrings_XX.properties' already exists: ...

It's probably better to copy the LocalStrings_??.properties files to LocalStrings_??.org before modifying them to your own application.

PrintProperties

This class is simply a little Helper to list the system properties with the method System.getProperties(); provided by Java. The same little for loop is being applied in CheckInstall (below).

CheckInstall

CheckInstall is a very useful to list the current GTS configuration with a single command. The class needs to be launched with the CheckInstall.bat or -.sh to compose the command line, which indicates the usage of the one conf file not covered on this page yet: default.conf.

Looking into default.conf provides more clues to the configuration:

This runtime-config file establishes global system-level attributes
(the 'private.xml' file establishes domain-level atributes).

and all it does it to begin the cascade to more configuration files,

%include=file:common.conf

which will be analyzed from inside the Java code later.

You should always take care that the ant build process and the CheckInstall can be executed any time. The output indicates more details on the GTS configuration details:

Runtime Configuration:
  (Default cfg dir)      ==> C:\prox\OpenGTS_2.4.3.lite
  (Default cfg file)      ==> C:\prox\OpenGTS_2.4.3.lite\default.conf
  (WebApp cfg file)    ==> C:\prox\OpenGTS_2.4.3.lite\webapp.conf
private.xml:
  (XML file)             ==> C:\prox\OpenGTS_2.4.3.lite\private.xml
  (Class)                ==> org.opengts.war.tools.PrivateLabelLoader
 

From this info we can conclude that the config files are not only distributed over the GTS components as described above. The files are also accessed by other components in their original location.

conclusion

The analysis on this page provides an initial and external view on the GTS configuration.

If you want to understand the step from the configuration files into the org.opengts... Java classes you should follow the submenu CheckInstall to see how the configuration settings are actually transferred into the GTS runtime.

The analysis was performed with the Java code installed in the Eclipse IDE, which is described in the next higher level menu Eclipse. So you might as well install Eclipse first and then come back to follow the white rabbit into the GTS Java runtime.

 

  « web apps ↓ CheckInstall Eclipse »