Skip to content

source-client-server.md

Latest commit

 

History

History
executable file
·
69 lines (49 loc) · 4.51 KB

source-client-server.md

File metadata and controls

executable file
·
69 lines (49 loc) · 4.51 KB

Standalone and Client Server Configuration

The adapter can be configured to call Source as either a standalone program or in client server mode. Importantly, this distinction is independent of the FEWS configuration: A standalone FEWS can call the client server Source and vice versa.

The client server mode of Source requires more configuration, but offers faster performance, particularly when running models multiple times, such as in river operations scenarios. Client-server mode requires setting up one instance of the Source server software for each Source model linked to FEWS. This setup can be handled externally to FEWS, or can be configured to occur on startup of FEWS using the Explorer plugin.

The performance gains from client server mode will vary depending on the characteristics of the Source model, but speedups of a factor of five have been observed. This is due to the time that the standalone version of Source takes to load the model files on each run.

Configuring the Source Servers

The Source Server Monitor is a FEWS Explorer plugin for starting and stopping Source servers for use with the core adapter. The Monitor needs to be (a) configured to run when FEWS starts up (from Explorer.xml) and (b) a mapping of Source project files (.rsproj) to Server port numbers.

In Explorer.xml, add an explorerTask to run the Monitor. The Monitor should be passed the name of a CSV configuration file, as described below

<explorerTask name="Source Server Monitor">
	<arguments>SourceServers.csv</arguments>
	<taskClass>au.flowmatters.fews.plugins.source.SourceServiceController</taskClass>
	<toolbarTask>false</toolbarTask>
	<menubarTask>false</menubarTask>
	<allowMultipleInstances>false</allowMultipleInstances>
	<permission>forecaster</permission>
	<toolWindow>true</toolWindow>
  	<loadAtStartup>true</loadAtStartup>
</explorerTask>

The CSV configuration file should be placed in the PiClientConfigFiles folder and should be populated with two column rows, where each row corresponds to an instance of the Source server:

  1. The path to a Source project file (.rsproj), typically referenced relative to a system variable such as %REGION_HOME, and
  2. A port number for the Source server to listen to.
%REGION_HOME%\Modules\source\catchment1\model\catchment1.rsproj,8765,
%REGION_HOME%\Modules\source\catchment2\model\catchment2.rsproj,8766,

Required Global Properties

The Monitor will check for the following global properties (eg defined in sa_global.properties or in oc_global.properties):

  • SOURCE_ADAPTER_PATH containing the path the Source Adapter
  • SOURCE_32EXE_PATH containing the path to the 32 bit RiverSystem.CommandLine.exe (required for 32 bit installations) and
  • SOURCE_64EXE_PATH containing the path to the 64 bit RiverSystem.CommandLine.exe (required for 64 bit installations)

These are required for the startup of the Monitor, but they are also convenient properties to reference from the General Adapter.

Multi-User Environments

When multiple users run FEWS Operator Clients on the same machine, for example, by using terminal services or Citrix to connect to the same Windows Servers, there would be a risk that multiple users would try to access the same instances of the Source service, causing conflicts. The Source Server Monitor and the Adapter can work around this by using Port 'offsets' based on username. With this scheme, the port number for a given Source model service is the configured port number + a port offset for the current user. So, for example, if ModelA.rsproj is configured for port 9100 and the current user, Bob, has a port offset of 3, the service for ModelA will be started on port 9103.

Configuring the Source server environment in a multi-user environment is a three step process:

  1. Enter a series of per user, port offsets, in Config/PiClientConfigFiles/UserSourceServerPorts.csv. Each line should contain a username (ie the Windows logon) and a port offset.
  2. List the mappings of Source model to network ports, as described above (eg SourceServers.csv),
  3. Add a UserPortOffsets property to the <exportRunFileActivity> in the general adapter to tell the adapter about the offsets.

The two CSV files need to be constructed to avoid clashes. So, if the user offsets increment by 1, then the project port numbers need to step by at least the number of users:

joel,1,
butcher,2,
baker,3,
candlestickmaker,4,
%REGION_HOME%\Modules\source\catchment1\model\catchment1.rsproj,8760,
%REGION_HOME%\Modules\source\catchment2\model\catchment2.rsproj,8770,