ANNEX¶

General WSDL definition¶

In WSDL the normative part shall apply only to method names and input and output message type definition: URLs path and internal variable names definition may vary for any implementation.

Overall presentation¶

Based on Basic Exchange Data Model and data dictionary defined in ANNEX C of CEN/ISO TS 19468, the information related to exchange is modelled in a Message Container which allows for inclusion

• Payload Publication content: the payload which is modelled in each domain, e.g. DATEX II payload content

• Exchange Information: information related to describe the exchange environment and its behaviour as PIM and PSM, with includes all data which enables the exchange features implementation.

• Information Management: class and attributes which enable the management of information such as lifecycle management

• CIS Information: classes and attributes which enable a service provider to implement services as requested by a service requester as modelled in collaborative ITS service description and PIM.

In the scope of the present work the Basic Exchange Data Model has been taken as input and based on DATEX II methodology and tools XML Schemas had been derived to implement the Basic Exchange Data Model in its equivalent CEN EN 16157 compliant schemas to enable data delivery and collaborative ITS services based on DATEX II EN 16157 family standard.

Overall presentation¶

This profile is compliant to Snapshot Pull FEP+EP PIM, it is derived from DATEX II version 2.0 Exchange Specification and it states all requirements to implement Snapshot Pull by simple http server profile, i.e. implemented by pure http/get, within the following clauses which implement all PIM specified features.

Snapshot Pull FEP+EP PIM defines the “pull message” received to be a “MessageContainer” according to Basic Exchange Data Model defined in Exchange 2020 PIM Annex C, which is implemented in XSD schema defined in this document Annex B.

Despite this rule, which always applies to Snapshot Pull implemented by WSDL, some implementation of “Snapshot Pull with simple http server” may consider to implement as delivery only the “PayloadPublication” without wrapping it in a “MessageContainer”, this is assumed implicititely defined by subscription agreement among client and suppliers.

This clause uses the term “Message” to refer either a “Message Container” or a single “Payload Publication”.

Describing payload and interfaces¶

The profile can handle different information to be delivered (such as different payloads), named information products by assigning a specific URL (potentially plus access credentials) per information product.

The information product itself is denoted by all but one path segments in the URL, while the ‘filename’ (i.e. the middle path segment) is “content.xml” per definition. This convention was introduced to allow the definition of related meta-data for this information product in other files in the same directory.

The end of this clause may sound awkward. It strives at maintaining all the regulations of the URI RFC, thus not constraining URLs for information products, but incorporating the need to have the final path element (the ‘filename’) being “content.xml” by convention.

To support authentication, the servers has to provide the credentials required to perform authentication for any particular information product.

Server requiring authentication MUST provide the required access credentials for BASIC authentication (i.e. user name & password) together with the URL for the Information Product.

Metadata for link management¶

Scenarios exist where the “If-Modified-Since” mechanism is not preferred to avoid redundant downloads. This will happen if the server provides information products by updating files on a standard, file-based www server (like Apache or Microsoft Internet Information Servers). In this option, the server would have two possible update regimes:

1. Periodical update of the information product’s payload file independent from any changes in the data.

2. Update the information product’s payload file on demand, when changes relevant to this product have occurred in the server’s database.

With updating regime 1, the file based www server would cyclically send the file content to the clients, as he will derive the last-modified value from the file modification times. So the client would receive redundant downloads!

Implementation based upon standard www servers and files as information products SHOULD update information product payload files only when their traffic domain content has changed.

This means that the file may stay unmodified for some time after an update. This regime has one serious drawback: the Client will not be able to determine whether the file remains unchanged because the (road) traffic situation is stable or because the backend server system itself (not the WWW server) is not operating properly. In fact, the response of the (intermediate) WWW system does not have the quality of an end-to-end acknowledgement.

This information is given in a small XML document that is periodically updated, even if the (potentially huge) content file is unchanged. The file is required to refer to an XML Schema that contains an Element called MetaData as root element with two required attributes of type xsd:dateTime called confirmationTime and confirmedTime, with confirmationTime giving the time the acknowledgement was created and confirmedTime giving a value equal to the value the Last-Modified header field would have if the payload file (i.e. content.xml) had been requested.

The following XML Schema gives a valid example:

The acknowledgement file shall be put in the information product’s directory, besides the content.xml file containing the payload, with a filename of metadata.xml. A sample file for the schema above would be:

This leads to the following specifications:

Implementation based upon standard www servers and files as information products SHOULD provide a cyclically updated acknowledgement, accessible as:

• D2LCP_infop_ack = “http:” “//” host [ “:” port ] infop_path “/metadata.xml” [“?” query]

• If an acknowledgement is provided, it SHALL be a well-formed XML document with a XML Schema reference. The acknowledgement SHALL validate successfully against the referenced XML Schema.

• The XML Schema referenced by an acknowledgement SHALL contain a root element called “MetaData”. This element SHALL contain two attributes, one named “confirmationTime” and one named “confirmedTime”, both of type “xsd:dateTime”.

• If used, acknowledgements shall be updated cyclically, with best effort update cycle, but not less than once every three minutes.

• An acknowledgement update SHALL indicate that the data server is operating properly at the time it is generated and that the content of that payload file – as last updated with modification time givenin the “confirmedTime” attribute of the “MetaData” – element iscurrently still valid.

• The “confirmationTime” attribute of the “MetaData” element SHALL contain the current time when an acknowledgement is updated.

• The “confirmedTime” attribute of the “MetaData” element SHALL contain the same value that a HTTP RESPONSE to an authorised HTTP REQUEST issued at the time of writing the acknowledgement would contain in the “Last-Modified” header field.

• A server that is based upon standard WWW servers and files as information products SHALL indicate in the subscription negotiation process whether the acknowledgement option is supported.

• Clients SHOULD use the acknowledgement option – if provided – to determine whether payload download is required.

Use of HTTP¶

This profile exchange uses HTTP Request (GET or POST) / Response dialogs to convey payload and status data from the Supplier to the Client. Note though that this profile supports POST requests only for interoperability with the Web services profile based on SOAP over HTTP exchange Information potentially included in the body of an HTTP POST request, is not processed.

This section stipulates how to use HTTP options for the Suppliers and the Clients of this profile.

Basic request / response pattern¶

1. Suppliers and Clients SHALL use the HTTP/1.1 protocol. Clients and Suppliers shall fully comply with the HTTP/1.1 protocol specification in RFC 2616, as of June 1999.

This protocol is based upon a request / response pattern, where the request can take one of several possible forms, among them the GET and POST methods for retrieving data. The GET and POST differ essentially in how the parameters of a request can be conveyed to the Supplier. While these parameters are conveyed as part of the URL in the HTTP GET request, the POST request allows specifying an “entity” (i.e. a message body) that contains these parameters, thus enabling less restricted parameters. POST requests were originally intended for server upload functionality.

As the specification foresees no complex request parameters, HTTP GET requests are preferred. Since other exchange systems sometimes require HTTP POST requests, they are also accepted. Nevertheless, it is not the intention to establish another exchange protocol layer on top of HTTP, and thus systems are not obliged to process the content of the body of an HTTP POST request.

2. Clients SHALL use the HTTP GET or POST method of the HTTP REQUEST message to request data from the Supplier

   The HTTP GET or POST request is served by the Supplier by generating an HTTP response message. The “Message” conveyed in this response is passed in the entity-body.

3. Suppliers SHALL use an HTTP RESPONSE message to respond to requests. If applicable, one “Message” is contained in the entity-body.

4. Suppliers SHALL NOT respond to HTTP REQUEST messages using the GET or POST methods by responding with 405 (Method Not Allowed) or 501 (Not Implemented) return codes.

   All communication is initiated by the client. Any data flow from supplier to client can only happen as the Supplier’s response to a Client’s request. When requesting data, the Client is not able to know whether the data he would receive would be exactly the same as the one he had received in response to his last request. This would lead to a serious amount of redundant network traffic, with potential undesired impact on communication charges and supplier/client workload. HTTP supports avoiding this by letting the Client specify the modification time of the last received update of a resource in an HTTP header field (If-Modified-Since). If no newer data is available, the response message will consist only of a header without an entity, stating that no new data is available. Clients are therefore recommended to set this header field in case they already hold reasonably recent information from the accessed URL.

5. Suppliers shall set the ‘Last-Modified’ header field in HTTP RESPONSE messages that provide payload data (response code 200) to the value that the information product behind the URL was last updated.

6. Clients may set the ‘If-Modified-Since’ header field in all HTTP REQUEST messages if they already hold a consistent set of data from a particular URL in their database and the last modification time of that data is known from the ‘Last-Modified’ header field of the HTTP header of the HTTP RESPONSE message within which the payload data was received.

   It shall be understood that the semantics of the timestamps used within the If-Modified-Since header field are calculated in the server. Therefore, times generated by the Client according to his own system clock may not be used here but must be filled using the content of the Last-Modified header field of the most recently received HTTP RESPONSE message. If Clients connect to a resource for the first time or want to resynchronise, they simply don’t set this header field.

7. When setting the ‘If-Modified-Since’ header field, the Client SHALL copy the value of the ‘Last-Modified’ header field received within the last successful HTTP RESPONSE containing a message (response code 200) into this field.

8. Suppliers SHOULD provide XML coded DATEX II payload as “text/xml” media type. Suppliers SHOULD state the used character set via the “charset” parameter; Suppliers SHOULD use the UTF-8 character set, i.e. the “Content-Type” response-header field SHOULD state “text/xml; charset=utf-8”.

   Character sets, media types, etc. are a vast area that is notoriously underestimated as a source of potential interoperability problems. This clause aims at recommending the most widely used set of options, namely the use of the UTF-8 character set for XML payload. The “text/xml” is preferred to “application/xml” following a recommendation in RFC 3023 (“If an XML document – that is, the unprocessed, source XML document – is readable by casual users, text/xml is preferable to application/xml.”). Although in principle the profile is solely devoted to B2B communication, readability of the exchange payload has often proved to be beneficial for testing and educational purposes.

   It should be noted that omitting the “charset” attribute in HTTP/1.1 for “text/*” type content implies the use of “ISO-8859-1” which is different from the UTF family (UTF-8, UTF-16) that are the minimum requirement for XML processors, and can thus be seen as the de-facto standard for XML. Consequently, sending typical XML payload like this:

   

   If “text/xml” without parameter would be sent, HTTP/1.1 would be violated.

1. Clients MUST accept “identity” content-coding; Clients SHOULD (and if they do, prefer to) accept “gzip” content-coding; Clients MAY accept other “content-coding” values registered by the Internet Assigned Numbers Authority (IANA) in their content-coding registry as long as they also accept “identity” and “gzip” content-coding.

10. When including an “Accept-Encoding” request-header field in an HTTP REQUEST message, the Client MUST NOT exclude acceptance of “identity” content-coding.

11. Suppliers MUST provide “identity” content-coding of the payload; Suppliers SHOULD provide “gzip” content-coding of the payload; Suppliers MAY provide other “content-coding” values registered by the Internet Assigned Numbers Authority (IANA) in their content-coding registry as long as they also provide “identity” and “gzip” content-coding.

This set of clauses essentially ensures that a confused situation where the Supplier is not able to provide payload in a content-coding that the client understands can not exist, as all suppliers are enforced to support “identity” (which means unmodified text/xml content) content-coding, and clients are enforced to understand this content-coding.

Furthermore, these clauses include a policy that recommends the use of compression and ensures that compression is always interoperable because it requires all clients/suppliers that do support compression to support “gzip” at least as an option. This means that:

• All client/supplier interaction will work at least with “identity”

• Clients/Suppliers supporting compression will always be able to agree on “gzip”

• Clients can request preferred other compression (“deflate” or “compress”), and Suppliers will respond accordingly if they support these content-codings.

Implementers should be aware that non-transparent web caches may perform media type transformations on behalf of their clients. Thus Client running over such a cache might notice that compressed response content is automatically decompressed. However this is only problematic if there is a low bandwidth connection between the client and the cache, such as a dial up access point. If a service has a significant number of such users then the addition of the no-transform directive to the Cache-Control header field of the generated responses should be considered. For more details on the use of the Cache-Control field, please consult Section 14.9 of RFC 2616.

Servers may use the ‘no-transform’ directive in the ‘Cache-Control’ header field to avoid non-transparent caches from sending non-compressed content.