A.   NOTICES TO SKIPPERS ENCODING GUIDE FOR EDITORS

CONTENTS

Abbreviations:

1.   Background, structure and purpose of NtS Encoding Guides

The NtS Standard is continuously being improved. A major step forward was the release of the NtS web service facilitating exchange of NtS messages between authorities as well as between authorities and NtS users.

Two documents have been developed to facilitate the harmonised encoding of NtS messages nationally and internationally: the NtS Encoding Guide for editors and the NtS Encoding Guide for application developers. These Guides apply to NtS XSD 4.0 and the NtS Web Service WSDL 2.0.4.0.

Considering increased use of the NtS web service, NtS messages shall be further harmonised to ensure proper display of content on third party systems. Uniform encoding of messages is also a prerequisite for consideration of messages in voyage planning applications.

Elements that would contain only standard or default values shall be omitted if they are conditional, because they lead to message overhead with no added value.

The NtS Encoding Guide for editors is intended for those editing (and publishing) of NtS messages, including step-by-step instructions to create the proper message types as well as an explanation of codes. The NtS Encoding Guide explains the applicability of the four NtS message types, provides filling instructions as well as codes to be used in certain events. The NtS Encoding Guide for editors is included in the present Appendix A.

The NtS Encoding Guide for application developers includes guidelines for NtS application development and implementation, explaining its logic, processes and auto/default values. The NtS Encoding Guide for application developers is included in Appendix B of the Annex to this Regulation.

2.   Selection of the NtS message type

3.   FTM basic considerations, steps towards publication of an FTM

Detailed information which codes have to be used is given in chapter 4. The considerations beginning from 3.3 are not necessarily in the input order of an FTM editor tool.

4.   FTM explanation of codes

4.1.   Subject_code:

Definition of use of Subject Codes:

4.2.   Reason_code

The Reason code should be filled to give additional information to the skippers.

Definition of use of Reason codes:

4.3.   Limitation_code:

Definition of use of Limitation codes:

4.4.   Limitation interval_code: Definition of use of interval codes:

4.5.   Indication_code:

The Indication_code is intended to be used for information about specific values with regard to certain limitations (e.g. speed limit, minimum power, available depth). In order to determine certain dimensions a reference to either an external reference system (geographical or hydrological) (e.g. clearance height, available depth, least depth sounded) or relative to known dimensions of artificial structures (e.g. available length, clearance width) is necessary.

4.6.   Position_code (objects):

Wherever possible the Position_code shall refer to the side of the fairway where the object is located relative to the fairway axis (left/middle/right) or other commonly known information (old/new) or geographic direction (north/south/east/west). The position_code for objects may be prefilled automatically from the RIS Index reference data. The left/right side of the fairway is defined looking downstream direction.

4.7.   Position_code (fairways/waterways):

A Position_code for an FTM (or a part of an FTM) that is related to a fairway or waterway is not provided. To indicate on which side of the fairway/canal/river/lake an incident occurs the limitation ‘special caution’ in combination with the proper limitation Position_code is used.

4.8.   Position_code (limitations):

4.9.   Target_group_code (see chapter 3.5)

4.10.   Reporting_code

4.11.   Communication_code

The following format shall be used (examples):

4.12.   Type_code:

A waterway is either a canal, lake or river.

5.   WRM basic considerations

Water related messages shall, as a general rule, be generated automatically. Where this is not possible the manual generation of WRM shall follow the processes set out for automatically generated WRM (see NtS Encoding Guide for Developers) as closely as possible.

6.   ICEM basic considerations, steps towards publication of an ICEM

Ice Messages depend on local observation and assessment and will usually be generated by authorised staff.

An ICEM shall be issued in case of ice. Ice does not necessarily cause limitation for navigation however information about ice condition not hindering navigation may be provided.

7.   WERM basic considerations

Taking into account the abundance of available Web Services and apps for weather forecasts and weather warnings WERM should only be used for weather information of specific importance for navigation which is not covered by general weather information services.

Weather related messages shall, as a general rule, be generated automatically. Where this is not possible the manual generation of WERM shall follow the processes set out for automatically generated WERM as closely as possible (see NtS Encoding Guide for application developers).

8.   Rules for certain elements

8.1.   Rules for the element ‘name’ related to objects

Object names are usually prefilled by the NtS editor tool based on RIS Index reference data. Names shall be entered in local language, thus also e.g. diacritics or Cyrillic letters may be used. (e.g. Baarlerbrücke, Volkeraksluis or Mannswörth).

Do not include information on characteristics of feature, the type of object shall not be repeated in the name unless additional information to the object type is given.

E.g.: The lock ‘Schleuse Freudenau’ shall only be named ‘Freudenau’, the object type ‘lock’ is added automatically based on the type_code.

E:g.: The object name for the Railway bridge in Krems (AT) is ‘Eisenbahnbrücke Krems’. The information ‘railway bridge’ is included in the object name as it adds information in addition to the type_code ‘bridge’.

E.g.: The object name for a bridge in Linz (AT) is ‘Nibelungenbrücke’. The word ‘brücke’ stays within the object name as it is part of the bridge name itself.

E.g.: The waterway gauge ‘Pegelstelle Wildungsmauer’ is named ‘Wildungsmauer’ as the information that this object is a gauge is already coded in the type_code.

If a waterway section is the borderline between two countries with different languages, the national object name can be provided in both languages (e.g. ‘Staatsgrenze AT-SK/Statna hranica AT-SK’).

8.2.   Rules for the element ‘name’ related to fairways

Fairway names are usually prefilled by the NtS editor tool based on RIS Index reference data. The field ‘name’ shall contain the local name of the respective fairway section (e.g. ‘Rhein’) Depending on national processes it may be possible to edit the fairway name to include commonly used local names or additions (e.g. ‘Rhein am Deutschen Eck’).

8.3.   Rules for the elements ‘value’ and ‘unit’ within limitations

Unless stated otherwise only cm, m3/s, h, km/h and kW, m/s (wind), mm/h (rain) and degree Celsius are allowed to be used as units within NtS messages.

B.   NOTICES TO SKIPPERS ENCODING GUIDE FOR APPLICATION DEVELOPERS

CONTENTS

1.   Background & Structure

Notices to Skippers (NtS) were being implemented in various European countries based on Commission Regulation 416/2007/EC of the European Parliament and of the Council concerning the technical specifications for Notices to Skippers as referred to in Article 5 of RIS directive 2005/44/EC. The NtS standard is in the continuous process of enhancement, a major step forward was the release of the NtS Web Service facilitating exchange of NtS messages between authorities as well as between authorities and NtS users as well as NtS XSD 4.0 streamlining the encoding of NtS messages.

1.1.   Purpose of NtS Encoding Guide

The NtS Encoding Guide explains the applicability of the four NtS message types as well as codes to be used in case of certain events. It provides NtS editors with NtS message filling instructions, thus allows nationally and internationally harmonised encoding of NtS messages.

Considering increased use of the NtS web service, NtS messages shall be further harmonised to ensure proper display of content on third party systems. Uniform encoding of messages is also a prerequisite for consideration of messages in voyage planning applications. The NtS Encoding Guide version 1.0 applies to NtS XSD 4.0 and the NtS Web Service WSDL 2.0.4.0.

1.1.1.   NtS Encoding Guide for editors

The NtS Encoding Guide for editors is intended for personnel editing (and publishing) NtS messages including step-by-step creation instructions for the proper message types as well as explanation of codes. The encoding guide for editors also includes relevant information for application developers.

1.1.2.   NtS Encoding Guide for application developers (this document)

The NtS Encoding Guide for developers includes guidelines for NtS application implementation explaining logic, processes and auto/default values.

2.   NtS messages and sections

An NtS message consists of the following:

Figure 2

Visualisation of the NtS message structure: mandatory element (1), mandatory element that may occur one or two times (1…2), mandatory element that has to occur two times (2), mandatory elements that may occur as often as necessary (1-n), optional element that may occur as often as necessary (0…n)

The identification section is mandatory and includes general information about the message originator, sender, date issue, country and original language and is provided together with one of the four different NtS message section types:

In addition, the ISRS Location Code (International Ship Reporting Standard) is used to define the applicable object(s) or fairway section(s) the message is related to.

The ISRS location code is defined in point 4.3 of the Annex to this Regulation.

3.   WRM basic considerations

Water level information is very important for voyage planning as well as safety. At the moment there is no common standard of referencing water level information. The values of gauges are referring to different sea-levels or to special reference points. To provide a proper reference, the respective ‘reference_code’ shall always be provided together with the value. WRM may be used to provide the following information:

Clarifications for translations in the spreadsheet ‘reference_code’ are provided in chapter 7.11.

Usually WRM are created and published automatically based on information received from sensor equipment or information received from infrastructure (e.g. predictions, barrage status). There may be different triggers for WRM publication, e.g. periodically or when certain values are reached.

3.1.   Filling of nts_number section in the WRM

In NtS XSD 4.0 the NtS number is optional within WRM messages. If it is provided every number has to be unique (Organisation/Year/Number/Serial) per message type and it is up to the organisation providing the WRM to ensure unique numbers (it is not required to have consecutive numbers).

3.2.   Filling of WRM including predictions

The date_start of validity_period has to be filled with present date (date_issue) and the date_end of validity_period has to be filled with the next day after date_issue.

To provide changes in e.g. water level in a user-friendly way the difference to a previous comparative measurement may be provided in the WRM difference section. Besides the change in the value (e.g. - 5 [cm]) also the time difference to the comparative measurement has to be provided.

In case of predictions the ‘measure_date’ is the date/time the prediction is valid for.

Water level predictions always include a factor of uncertainty. Usually models with different parameters (e.g. weather forecast) are calculated leading to different predicted water level values. To enable provision of a minimum and maximum predicted value e.g. visualisation of a water level prediction confidence interval, two additional optional data fields are included in the WRM ‘measure’ section.

An illustration of water level prediction confidence interval is given in the following figure:

Figure 3

Visualisation of water level prediction confidence interval: most probable value (black), confidence interval upper boarder (violet), confidence interval lower boarder (red), measured water level (blue)

(The x-axis shows the time; the y-axis shows the water level in cm)

Two elements are available in the NtS XSD:

Besides predicted water levels the confidence interval may also be used to state the uncertainty of published least sounded depth and vertical clearance information.

The confidence interval value_min and value_max enable provision of WRM value confidence interval via standardised NtS WRM Message to use it in graphs. The raw data itself shall not be displayed to IWT users (e.g. in code format).

The measure_code ‘NOM’ must not be used. In case there is no measurement for a certain type of WRM the value elements have to be omitted if a message should be sent anyhow.

4.   ICEM processes

Ice Messages depend on local observation and assessment and will usually be generated manually (in case of automatic generation the rules for manual creation have to be followed, see NtS Encoding Guide for editors).

The ICEM is published for a certain fairway_section defined by its begin and end ISRS Location Codes and contains the ice_condition at a certain measurement date.

The validity of the ICEM starts at the date of publication (automatically set by the NtS application). In order to avoid ICEM being displayed to users that are not valid any more, the validity date_end has to be filled automatically by the NtS application with the day after publication (unless it is ensured by national processes that messages will get a validity date end as soon as the information included in the message is not up-to-date any more).

In the NtS Encoding Guide for editors it is described under which circumstances an NtS editor creates a new ICEM or updates an existing ICEM. The following processes apply:

4.1.   New ICEM

4.2.   Update of an existing ICEM

5.   WERM basic considerations

Usually WERM are created and published automatically based on information received from sensor equipment or information received from infrastructure. The date_start of validity_period has to be filled with present date (date_issue) and the date_end of validity_period has to be filled with the next day after date_issue.

The fairway section in WERM is indicated as a stretch between two points on the fairway, i.e. area of applicability of the weather station (gauge).

Date and time of measurement/forecast have to be provided even if it is not mandatory in WERM messages.

In case of forecasts the ‘measure date’ is the date/time the forecast is valid for.

5.1.   Filling of nts_number section in the WERM

In NtS XSD 4.0 the NtS number is optional within WERM messages. If it is provided every number has to be unique (Organisation/Year/Number/Serial) per message type and it is up to the organisation providing the WERM to ensure unique numbers (it is not required to have consecutive numbers).

5.2.   Filling of WERM ‘weather_category_code’

The wind speed in ‘weather_category_code’ (values 0 to 12) shall be provided in line with the Beaufort scale published by the World Meteorological Organization in its Manual on Marine Meteorological Services ‘WMO-No 558’.

The visibility in ‘weather_category_code’ (values 13 to 22) shall be provided as defined in the following table:

6.   FTM processes

In the NtS Encoding Guide for editors it is described under which circumstances an NtS editor creates a new FTM or updates an existing FTM. The following processes apply:

6.1.   New FTM

6.2.   Update/withdrawal of an existing FTM

6.3.   Waterway and/or object related FTM

A waterway related FTM contains information about one or several stretches of waterway. A waterway stretch is defined in the ‘fairway_section’ part by its begin and end ISRS Location Codes.

An object related FTM contains information about one or several specific objects on the waterway. An object is defined in the ‘object’ part by its ISRS Location Code.

One FTM has to refer

6.4.   Automatic ordering of limitation codes

Different limitations have different impact on navigation. In order to allow display of the most severe limitation e.g. in an FTM list overview, the following order shall be considered starting with the most severe limitation having Rank 1:

6.5.   Handling of limitation period

7.   General implementation rules

The following is to be considered:

7.1.   Filling of the ‘number_section’

Every number (Organisation/Year/Number/Serial) has to be unique per message type. That means that messages of different types can have the same NtS Number.

For users the message numbers are only relevant for FTM and ICEM, for all other message types display of the message number can be skipped depending on national requirements.

To users the message number shall be displayed in the following format ‘Message Type/Country/Organisation/Year/Number/Serial’ (it can be shortened depending on applied filters if no information gets lost).

7.2.   Filling of elements ‘from’, ‘originator’, ‘organisation’ and ‘source’

The element ‘from’ in the identification section is filled with the name of the national system that provides the message (e.g. ELWIS, DoRIS, SLOVRIS, FLARIS).

The element ‘originator’ is the organisation which enters the messages into the national systems.

The element ‘source’ is the authority for which the FTM are published.

The element ‘organisation’ within the nts_number section is the name of the organisation assigning the nts_number (NtS Provider).

7.3.   Omission of elements

Elements that would contain only standard or default values shall be omitted if they are conditional, they lead to message overhead with no added value.

Following elements are concerned:

7.4.   Automatic filling of date_issue

FTM and ICEM

For FTM and ICEM the value of date_issue element is the actual date and time of publishing. In case of updated messages date_issue is the date and time when the update was published.

WRM and WERM

For WRM and WERM the value of date_issue element is the date and time of the processing request, because there can be several measurements with different issuing time stamps within one W(E)RM message.

7.5.   Handling of time zone information in NtS messages

Date and time shall always be provided in local time including time zone information within the NtS XML messages.

The only exceptions from this provision are the ‘time_start’ and the ‘time_end’ within the ‘limitation_period’ section. This is because in the limitation section an interval can be applied. If date start and date end have different time regimes (e.g. CEST and CET) this would result in a change of the time zone information within this interval. This change cannot be expressed via a single limitation period. Instead of creating different limitation periods for each time change only a single limitation period without time zone information is used to reduce overhead in message processing and transmission.

7.6.   Handling of Seconds in NtS messages

As a general rule seconds have to be provided in (date)/time fields but shall not be displayed to NtS users. Minutes are sufficient for NtS granularity.

7.7.   Format of decimals in NtS messages

Decimals in numeric fields are indicated with a . (period). No thousand separators are used.

The number of decimals used for values shall be limited to a feasible amount to ensure user-friendly display.

7.8.   Units to be used in NtS messages

Only cm, m3/s, h, km/h and kW, m/s (wind), mm/h (rain) and degree Celsius are allowed to be used as units within NtS messages, applications may convert the units for user friendliness.

In case the input units differ from the standardised units the entered values have to be converted by the application accordingly.

7.9.   Rules for the elements ‘name’, ‘position_code’ and ‘type_code’

The element ‘name’ shall be prefilled automatically from the RIS Index reference data ‘national object name’ (NtS editors might amend the prefilled name if this is a national requirement). Naming conventions for object names are included in the RIS Index Encoding Guide version 2.0 or higher. Examples for proper object names are also given in the NtS Encoding Guide for editors.

The type code is added to the object by the NtS application in front of the object name.

The position of objects is encoded via position code and added to the object by the NtS application out of the RIS Index. Editors may change prefilled type and position codes. An object position code shall not be provided for geo_objects in the fairway_section.

A full object name is composed of its position code, type code and name.

To ease the work of NtS editors the following mapping may be implemented in NtS editor tools supporting editors in finding / selecting the proper objects based on the RIS Index function_code or the NtS type_code:

Table 1

Matching ‘RIS Index function_code’ — ‘NtS type_code’

7.10.   Rules for the element ‘fairway_name’

To avoid application logic / necessity of proper reference data at the receiving system (software displaying the notice to the user) the optional element ‘fairway_name’ shall always be included in the ‘geo_object’ and automatically filled by the NtS application with the ‘Waterway name’ from the RIS Index. NtS editors shall not alter the content of the element fairway_name.

7.11.   Clarifications for translations in the spreadsheet ‘reference_code’

The following definition shall be used for reference_code values provided in the NtS Reference Tables:

7.12.   Recommendation for the element ‘coordinate’

Although the element coordinate within the geo object section is conditional, the geo coordinates shall be given in WGS84 in format [d]d mm.mmm[m] N (latitude) and [d][d]d mm.mmm[m] E (longitude). This is to refer the NtS messages geographically.

7.13.   Handling of target groups

The target group section consists of target group code and direction code. If both have the value ALL the whole section shall be omitted if there are no other specific target groups within the message. If just one of these two is given the other must be filled with the default value ALL because both elements are mandatory.

Further information concerning target groups can be found in the NtS Encoding Guide for editors.

7.14.   Display of valid messages at a given time

The validity_period shall be used by applications to select the messages, which are to be displayed to users for a requested time.

If subject_code is INFSER (Info service) the validity period is used to specify the time the Info service Message is displayed to the users, not for the period of validity of the provided information (e.g. 1 month).

7.15.   Optional functions to increase user friendliness of NtS editor tools

The following functions may be offered to NtS editors depending on national requirements:

8.   NtS XML Message Structure

The NtS XML Message Structure and the content and purpose of data elements are defined and further explained in Appendix C: NtS XML Schema Definition (XSD).

9.   NtS Web Service

9.1.   Objective

The NtS Expert Group identified the web service technology as an appropriate means to provide the Notices to Skippers.

This chapter constitutes the specification of the web service for the provision of the Notices to Skippers, short NtS Web Service. Particular emphasis was placed on the use of well-established international standards.

One goal of the conceptual design was to ensure a good balance between flexibility and robustness of the resulting web service. The filter parameters provided in the requests are essentially the criteria specified in the NtS standard (waterway section with optional river km, time of validity, date of publication of the notice). This seems sufficiently expressive considering the use cases of the web service and at the same time limits the complexity of the implementation.

The core result is a contract for the web service, in which the requests and responses are specified. The consumers of the web service can rely on this contract and the providers have to comply with it. This contract is specified using the international standard WSDL.

Every participating Member State shall implement one or more web services for the different message types of the NtS (FTM, WRM, ICEM, WERM) and provide them via the internet (‘NtS Message Service’),

The technical details of the implementation of the NtS WS, e.g. choice of appropriate data pools, applications and platforms, are not in the scope of this specification and are in the responsibility of each individual participating Member State.

In order to define a secure communication one has to consider various security aspects and protection objectives. Depending on the circumstances not all of these aspects have to be considered. The priority of the various security aspects and the degree of their fulfilment can vary. Also the feasibility of a certain measure can be limited by the capabilities of the technical implementation. In the context of NtS all information are public. So there is no need to secure the NtS data themselves in terms of data protection. Therefore every provider has to decide on its own in how far this aspect will be implemented in its service.

9.2.   Basic Principles and constraints

9.2.1.   Web standards

The NtS Web Service has to comply with the WS-I Basic Profile 1.1. This profile ‘provides interoperability guidance for a core set of non-proprietary web services specifications, such as SOAP, WSDL and UDDI’  (1). The most relevant standards herein are

The response message of the NtS WS is an NtS message which is defined in XML Schema Definition (XSD) in Appendix C of this Commission Regulation.

9.2.2.   Interaction model and encoding method for NtS WS

The encoding method Document-literal wrapped is used for the NtS Web Service, because it allows for validation against an XML schema and the operation names defined in the WSDL specification are used directly as XML tag names in the SOAP messages.

9.3.   General specifications and recommendations

9.3.1.   Specification: Version information

The version information of the NtS Web Service consists of two sections:

The section of the web service itself consists of two parts:

The major version is given as a positive integer denoting the major version of the web service.

The minor version is given as a non-negative integer denoting the minor version of the web service within the major version.

The section of the NtS schema contains the version of the NtS schema as defined by the NtS Expert Group.

Hence, the version of the NtS Web Service specified here is 2.0.4.0, where 2.0 is the version of the web service itself and 4.0 is the version of the NtS schema used.

Explicit version information is not necessary in the requests or responses of the NtS Web Service. There are only a few versions of the services expected to be online at the same time. Different versions shall be provided with different URLs. Hence, each instance of an NtS Web Service implementation shall support one specific version of the NtS Web Service.

9.3.2.   Specification: Structure of namespaces

The namespaces in the NtS Web Service are based on the web domain of the RIS Expert Groups, http://www.ris.eu/

The namespaces contain a particle indicating the corresponding service and version information. Hence, the service specified here uses the following namespace:

NtS Message Service: http://www.ris.eu/nts.ms/2.0.4.0

9.3.3.   Recommendation: Use of namespaces

For higher transparency of XML documents it is recommended to define namespaces in the outmost suitable element in the schemas as well as the instance documents and not to use local namespace definitions in nested elements.

9.3.4.   Recommendation: Use of namespace prefixes

Requests and responses in the NtS Web Service shall use XML elements in qualified form, i.e. with an explicit namespace prefix, and XML attributes in unqualified form, i.e. without a namespace prefix.

It is recommended to use intuitive namespace prefixes like ‘nts’ for better human readability.

9.3.5.   Specification: Use of ISRS Location Codes

The ISRS Location Code is explained in chapter 2 of the NtS Encoding Guide for application developers as well as the RIS Index Encoding Guide.

Querying an NtS Web Service, the client can reference various objects, e.g. fairway sections, gauges or locks. If the corresponding parameters, the id elements, are used, they must contain ISRS Location Codes. These parameters are typically given in id elements, each containing one or two ids.

When using these parameters, the following general conventions have to be observed:

For the provision of waterway stretches (id element pairs within the fairway_section geo_object) in NtS messages, the following has to be considered with respect to the ISRS Location Codes:

In case a message touches more than one waterway or fairway sections all fairway sections have to be defined by their begin- and end-point in separate ‘fairway_section’ XML elements.

For some countries/regions it is required to build filter functionality. For example if ISRS Location Code (1-2) is BE use ISRS Location Code (6-8) as the ID for linear referencing with the fairway hectometre (ISRS Location Code 16-20). Examples for fairway stretches (valid id element pairs within the fairway_section) that include above defined exceptions:

The following figure shows counter-examples of ISRS Location Code usage for each of the general conventions (no exceptions to the general conventions apply to SK waterway stretches):

Invalid ISRS Location Code queries

General remark: A service to query valid ISRS Location Codes is not supported by the NtS Web Service. The ISRS Location Codes are provided within the European Reference Data Management System (ERDMS).

The correct usage of ISRS Location Codes in queries and their interpretation is given in the following five cases.

Case 1: No ids element in request

The ids element is an optional part of the request, i.e. a query without any ids elements is allowed:

Valid query without ids parameter

If no ids element is given, all messages shall be returned (depending, of course, on other filter criteria like validity_period or dates_issue).

Case 2: One id element in request

Each ids element can contain one or two id elements. The case of one id element is shown in the following figure:

Valid query with one id parameter

If such a query is received, the server shall return all matching messages with a start hectometre ≤ the given value (240,7 in the example) and an end hectometre ≥ this value. The figure below depicts this selection of messages: The position queried lies between the start and end hectometre values of messages 1, 3 and 4, which would be returned. Messages 2, 5 and 6 do not overlap with the query position, so they would not be returned.

If the given ISRS Location Code denotes a singular object, e.g. a gauge or a lock, the web service should return the messages involving this object.

Matching and not matching messages for one id parameter

Case 3: Two id elements in request

Each ids element can contain one or two id elements. The case of two id elements is shown in the following figure:

Valid query with two id parameters

All hectometre values queried shall be treated as valid, even if the corresponding fairway section has different start or end points. For instance, if the fairway section starts at hectometre 100,0 and ends at hectometre 300,0, a request querying hectometres 20,0 up to 400,0 would be valid. Internally, of course, only the ‘real’ extent of the fairway section is searched.

Doing so also enables the search for all messages on a fairway without knowing its exact hectometre range (one would send its ISRS Location Code with hectometres set to ‘00000’ or ‘99999’ respectively).

All matching messages intersecting the given hectometre interval shall be returned. The following diagram illustrates this situation:

Matching and not matching messages for two id parameters

The figure above shows, how ‘intersecting’ is defined. While the extents of the messages 1 to 4 overlap with the extent of the queried hectometre range (partially or completely), the extents of messages 5 and 6 do not, therefore messages 1 to 4 will be returned, 5 and 6 will not be returned.

The technical condition for a message to intersect with an interval [A, B] is: The start hectometre of the message is ≤ B and its end hectometre is ≥ A.

Combination: Multiple ids elements in request

Valid query with multiple ids elements

The combination of several ids elements in the request leads to a union of the corresponding messages. All the ids elements are treated individually and a message will be returned, if it matches at least one of them. Therefore, the following messages would be returned for the given example:

9.4.   NtS Message Service (implementation specification)

In this chapter the implementation specification of the NtS message service is given, deduced from the considerations and choices in the preceding chapters.

The NtS message service provides the four types of messages in the NtS:

An implementation of the NtS message service can support all message types or just a selection. It is allowed that a participating Member State provides more than one service for a specific message type, that complement each other.

9.4.1.   Request

In order to achieve a maximum robustness of the service while keeping the complexity on a low level no additional query language is used for the NtS Web Service. Instead the constructs provided by WSDL itself are applied. The specific operations together with their parameters are specified entirely within the WSDL specification. In the case of the NtS Message Service a single operation is defined.

The subject-specific filter criteria are taken from the NtS standard, but extended concerning multiplicity of the parameters:

Only the messages matching the given criteria are returned by the service.

Paging mechanism

In order to control the amount of data a paging mechanism is supported. The paging parameter is defined with a complex type containing the following elements:

The complex paging parameter is optional, but if it is present, all elements within have to be given. Then, the paging mechanism works in the following way:

The total number of messages will not exceed the value of the parameter limit, with the exception that a value of 0 means ‘no limit’. The response skips as many messages as defined in the parameter offset. In order to provide this mechanism, the service has to observe a temporarily stable (but otherwise arbitrary) sequence of the messages, e.g. between two updates of message data on the underlying data set of the web service. This means that two consecutive identical calls must return the same messages in the same order. The parameter total count determines whether the response shall provide the total number of messages matching the subject-specific criteria. Usually it should be sufficient to request this information with the first response, but omit it in all consecutive responses. This should result in a better performance of the web service.

The paging mechanism provides a means to request the messages iteratively in ‘pages’. In order for the paging mechanism to work properly, the same subject-specific parameters have to be provided in each call.

9.4.2.   Response

In case of a successful request the NtS Web Service response contains the NtS messages that match the request parameters. The NtS messages have to comply with the NtS schema and can be validated against that schema. Since the message type is a compulsory request parameter, each response can contain only NtS messages of the same message type, FTM, WRM, ICEM or WERM respectively.

If the service detects errors while processing the request it can return an arbitrary number of error messages, using the error codes listed in the following subchapter.

One response of an NtS Web Service can contain NtS messages and error messages at the same time.

Optional paging information is returned if the request contained paging parameters. In this case the offset and number of contained messages are mandatory, the total count needs only be present if it has been requested.

Please note: It is assumed that the communication between the web service and the user is technically established, i.e. the service receives the request and the user receives the corresponding response. Technical errors, e.g. breakdown of the internet connection or inaccessibility of the web service due to maintenance or crash, are not considered here. Only error situations that happen ‘behind’ the web service layer from the users point of view are considered here.

Error messages

The error codes for the expected error situations are given below, together with an explanation. Only the error code is contained in the response, which is the usual procedure in the XML schema of the NtS.

Error codes for the NtS message service

9.5.   Generation of services and clients

If the contract-first approach is consequently observed, i.e. one or more contracts with complete descriptions of the interfaces are given in the form of WSDL documents, an implementation of the service(s) as well as an implementation of a corresponding client can be automatically generated using appropriate software tools. In an ideal situation no manual changes have to be made in the generated source code.

However, in most cases several iterations are necessary until the WSDL specification meets the precise requirements of such a tool. Typically the tool makes individual demands on the use of the WSDL standard in order to work smoothly. As a consequence changes to the WSDL specification may be necessary, although the WSDL specification was a valid specification according to the WSDL standard in the first place. If the WSDL specification of the web service is changed after the service or the client have been generated, a new generation process may be necessary, depending on the changes made.

Glossary

(1)  Description cited from the WS-I Website: http://www.ws-i.org

Appendix C