Commission Regulation (EC) No 416/2007 of 22 March 2007 concerning the technical specifications for Notices to Skippers as referred to in Article 5 of Directive 2005/44/EC of the European Parliament and of the Council on harmonised river information services (RIS) on inland waterways in the Community

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.

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

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.

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.

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:

— ISRS Location Codes have to be submitted as full-length 20-character codes, i.e. without truncating trailing zeros,

— If two ids are used within an id element, both ISRS Location Codes have to refer to the same waterway. This means, that the codes include some identical digits located in the fairway_section part of the ISRS Location Code. The fairway section code together with the fairway hectometre defines a waterway stretch provided as pair of id elements.

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:

— digits 1 to 2 (Country code): — have to be identical within the id pair, but — different country codes may be defined within one id pair in case neighbouring countries are using the same fairway section code for a specific waterway and the same system for defining the hectometres,

— digits 3 to 5 (UN Location code): — are not relevant, may contain different content within the id pair,

— digits 6 to 10 (Fairway section code): — have to be identical within the id pair, but — [exception]: in case of using the Belgian ISRS codes within NtS WS, one should use only digits 6 to 8 to identify the fairway section, because NtS messages will be published across different sections within one fairway,

— digits 11 to 15 (Object Reference Code). — are not relevant, may contain different content within the id pair,

— digits 16 to 20 (Fairway Hectometre): — consist of five numerical digits defining the hectometre thus will usually contain different content within the id pair. Example: ‘00235’ for fairway km 23,5 ; ‘00001’ for fairway km 0,1 , — [exception]: in case of the Netherlands there is not always a direct connection between the Fairway hectometre and the physical kilometre of the fairway due to the definition of the start of the fairway stretch in the network model and in the real world, in such cases the Object Reference Code for objects of the type ‘dismar’ starts with Kxxxx (xxxx includes the physical kilometre, e.g. NLSVG00130K000300191 (km 3)). But for other types of objects there is no direct relation to the physical fairway km in the ISRS codes, e.g. the bridge of Sas van Gent on the same fairway at km 2,5 has the ISRS code NLSVG001300521600186. For the Kanaal Gent-Terneuzen the physical km 0,0 starts at the border of Belgium and the Netherlands and the Fairway Hectometre 0,0 starts at the beginning of the canal in Gent.

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 two NL ISRS Location Codes are a valid definition of a waterway stretch (showing NL exception with respect to the kilometre of the fairway): NLSVG00130K000300191 (km 3,0 at Sas van Gent on the Kanaal Gent-Terneuzen) — NLWDP00130K000400200 (km 4,0 at Westdorpe on the Kanaal Gent-Terneuzen),

— The two BE ISRS Location Codes are a valid definition of a waterway stretch (showing BE exception with respect to the fairway section code (‘020’ Albertkanaal)): BEGNK02016L010100414 (lock of Genk located at km 41,4 on the Albert Canal) — BEOSH02033L010500772 (lock of Ham located at km 77,2 on the Albert Canal).

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):

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.

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

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

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

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.

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

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:

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.

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:

— All messages for the object with the ISRS Location Code SKXXX0000010000^* with start hectometre =0 and end hectometre ≥ 0 (see Case 2)

— All messages for the object with the ISRS Location Code SKXXX0000500000^* which intersect the hectometre interval [11,0 , 15,0 ] (see Case 3)

— All messages for the object with the ISRS Location Code SKXXX0000200000^* with start hectometre ≤ 110,5 and end hectometre ≥ 110,5 (see Case 2)

— All messages for the object with the ISRS Location Code SKXXX0000500000^* which intersect the hectometre interval [220,0 , 300,0 ] (see Case 3)

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.

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:

— type of message (compulsory; one of ‘FTM’, ‘WRM’, ‘ICEM’, ‘WERM’),

— specific waterway sections or parts thereof, or specific objects (optional; described by single ISRS Location Codes and/or pairs of ISRS Location Codes),

— time of validity (optional; start date and end date),

— date of publication of the notice (optional; single dates and/or intervals of dates).

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:

— offset: serial number of the first returned message (integer ≥ 0),

— limit: max. number of messages (integer ≥ 0),

— total count: flag, if total number of messages shall be returned (Boolean value).

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.

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.

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

Appendix C

Rules applicable to table "NtS XSD V.4.0.4.0":

Appendix D

<wsdl:definitions

— "nts:RIS_MessageType", arbitrary number, defined in the NtS-xsd (see www.ris.eu)

— "nts-ms:error_code_type", arbitrary number, defined in this schema

— "nts-ms:paging_result_type", optional, defined in this schema -->