Excerpt | ||
---|---|---|
| ||
an overview |
scrollbar |
---|
Info |
---|
This is an overview of some of the requirements for developing a Delft-FEWS compliant adapter. This list is not by no means exhaustive and so before starting to develop an adapter always please contact fews.support@deltares.nl |
Info |
---|
Since 2014.01 it is possible to write a NetCDF-CF based adapter, see Developing a FEWS Model Adapter (NetCDF-CF) |
Table of Contents |
---|
Development of FEWS Adapter
...
- The general adapter is that part of DELFT-FEWS which exports model input, imports model output data, and executes the pre-adapter, module and post-adapter.
- Export and import of model data is done in datafiles following the Published Interface (PI) XML format.
- The preAdapter, Module and postAdapter together form the model adapter. The model adapter is initiated from the general adapter.
- The preAdapter is that part of the model adapter which converts input data in PI XML format to native model input data.
- The postAdapter is that part of the model adapter which converts native model output data to PI XML format to be imported by FEWS.
- The Module is that part of the model adapter which starts a model simulation.
...
External Modules and their adapters can be written in any programming language. However, in case Java is used, they have to implement the interface ModuleAdapterRunnable. Modules and module adapters can only communicate with the General Adapter via the Published Interface. The only 2 means to exchange information with the General Adapter are:
- A diagnostic file written in the Published Interface format. If such a diagnostic file is available the General Adapter will read it and write corresponding logs to the FEWS system.
The return code indicating the result of an execution.
0return code
meaning
1non Zero
graceful failure - read message
0
successful execution
all other
non graceful failure
Modules and their adapters cannot use exception or event handling as a means to communicate with the General Adapter.
Return code error information
The GA distinguishes between two types of failures of a module or module adaptor, graceful and non graceful.
- On non graceful failure the GA expects a non-zero return codeOn graceful failure the GA expects a zero return code. The type of error and the accompanied message are stored in the diagnostics file according to the GA.
- On non graceful failure the stack trace will be written for adapter (applies to adapters written within FEWS only) otherwise generic message will be given that adapter has crashed.
- On successful execution the GA expects a zero return code.
Actions taken by the GA on:
...
Diagnostics file
The published interface documentation describes the (simple) xml file format. Per batch (pre processing - module run - post processing) one diagnostics file is always expected. Each line/message in this file contains the actual text and the warning level attached to this text. The warning levels in the diagnostics file will be interpreted by the general adapter. according to the following table:
Level | Name | Description | Example |
---|---|---|---|
4 | debug | debug logging | version: 1.0 |
3 | info | information, all is well | Module PreProcessor : program ended |
2 | warning | warning information | Module Processor : unresolved symbol |
1 | error | critical problems | Module Processor: module fails (returns 1) |
0 | fatal | fatal error, complete module crash | Module Processor: division by zero |
All levels higher than 3 are regarded as non-essential (debug) information. The warnings are recorded in the system, but no actions will be taken.
In memory file transfer
The Java adapters should check if a file is transferred in memory to the adapter by FEWS.
public static BufferedInputStream newInputStream(File file) throws IOException { |
---|
Validating xml
When an adapter reads xml written by FEWS according to its own xsd there is no need for validation, it is an unnecessary step because in the creation process FEWS uses those xsd's and therefore the xml will be valid.
Since FEWS 2022.02 access to external xsd's from other xsd's is closed off for the Java xml package which is included in the jdk. This is done by setting the javax.xml.accessExternalSchema sytem property to an empty string for security reasons.
When existing adapters do use this and it is not an option to update the adapter, since FEWS stable2022.02 patch #118458 in clientConfig.xml the javax.xml.accessExternalSchema system property can be overruled via
<jvmOption>-Djavax.xml.accessExternalSchema=all</jvmOption>
Children Display | ||
---|---|---|
|
Example model adapter (includes source code)
Download the example adapter as a quick start to develop your own adapter.
FEWS_Example_Model_Adapter..zip