Platform Specific Model¶

Datex II documentation¶

RFC - documents produced by the Internet Society – IETF¶

The IETF ( http://www.ietf.org ) RFC reference documents are listed in Appendix A.

W3C documents¶

The W3C(www.w3c.org) reference documents describing Web Services and associated technologies are listed in Appendix B.

Web Services interoperability organization (WSI) reference documents¶

Basic Profile 1.1 – Second Edition – 2006-04-10

http://www.ws-i.org/Profiles/BasicProfile-1.1-2006-04-10.html

Attachments profile 1.0 – Second Edition – 2006-04-20

http://www.ws-i.org/Profiles/AttachmentsProfile-1.0-2006-04-20.html

Relevant Exchange Information in Exchange Data Model¶

Reference to Exchange PIM

General PSM Exchange Messages format¶

Reference to Exchange PIM

Web Services Supplier description¶

In this profile, the Supplier uses Web Services classes, automatically generated, to set data and encode the message.

The corresponding WSDL file is given in Appendix 1.

Each DATEX II Supplier web service SHOULD be built with the reference WSDL document. If a Supplier modifies the schema which is imported in the WSDL, he MUST manage and keep interoperability with his DATEX II Clients.

This Pull service WSDL has been built with the following choices :

• define one unique reference WSDL as stable as possible,

• define one WSDL for Pull DATEX II exchange valid for all DATEX II exchanged data,

• reference to Web Services Interoperability (WS-I) Organization (Re [DOC 1]),

• binding SOAP : style=document, use=literal, following WS-I recommendations.

Remark: SOAPAction http header field (Rule coming from the WSI Basic profile (Re. [DOC 1])): « The HTTP request MESSAGE MUST contain a SOAPAction HTTP header field with a quoted value equal to the value of the soapAction attribute of soapbind:operation ».

2.3.2 Client system implementation options¶

The Client gets data from the Supplier. For that, like for the Supplier system, two technologies can be used for the Pull Client system:

• One, using Web Services and the Web Service Description Language (WSDL),

• Another, using directly http requests.

In order to keep interoperability, despite these two technologies, solutions have been found:

• at the Supplier level (the solution is to respond messages with a SOAP envelope, even if the Supplier is only an http Server),

• at the Client level: the Client which doesn’t use Web Services ignores the SOAP envelope.

The “Web Services profile” is described in the following paragraph.

The Client using directly http requests is described in the following chapter.

2.3.3 Web Services Client description¶

In this profile, the Client uses automatically generated Web Services classes, to get data and decode the message.

“2018 DATEX II Exchange reference set” contains a reference WSDL description of the Supplier Web Service which must be used by the Client to build access to the services.

The corresponding WSDL file is given in Appendix 1.

This WSDL file imports the 2018 Exchange Generic Exchange Model reference XML schema.

Each 2018 DATEX II Exchange Client web service SHOULD be built with the reference WSDL document. If a Client modifies the schema which is imported in the WSDL, he MUST manage and keep interoperability with his 2018 DATEX II Exchange Suppliers.

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 essentially 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. NOTE: systems MAY decide not to process the body of HTTP POST requests!

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 payload data – if any – conveyed in this response is passed in the entity-body. The payload data has to conform to the DATEX II data serialisation rules. The exact structure of the DATEX II content payload is beyond the scope of this specification. It should be noted thought that for interoperability reasons (in particular with Web Services profile Clients that require a SOAP wrapper around the XML payload) the profile does not stipulate the DATEX II content payload to be the root element of the XML content.

3. Suppliers SHALL use an HTTP RESPONSE message to respond to requests. If applicable, payload data according to DATEX II payload encoding specifications is contained in the entity-body. The DATEX II payload element MAY be embedded into other XML elements (‘wrapper’) in the contained XML document, but this XML document MUST contain exactly one DATEX II root element.

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 work load. 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 MUST 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 SHOULD 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 must 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 payload (response code 200) message 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:

<payload modelBaseVersion="3" xmlns="http://datex2.eu/schema/3/d2Payload"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://datex2.eu/schema/3/d2Payload http://www.datex2.eu/schema/3/3_0/DATEXII_3_D2Payload.xsd">

[..]
via HTTP/1.1 actually requires the use of the “charset” attribute:
HTTP/1.x 200 OK
[..]
Content-Type: text/xml;charset=UTF-8
[..]

If “text/xml” without parameter would be sent, HTTP/1.1 would be violated. (Quote from RFC 2616: “When no explicit charset parameter is provided by the sender, media subtypes of the “text” type are defined to have a default charset value of “ISO-8859-1” when received via HTTP. Data in character sets other than “ISO-8859-1” or its subsets MUST be labelled with an appropriate charset value.”)

9. 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.

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

List of requirements implemented¶

We resume from Exchange PIM

Basic Exchange Pattern¶

We resume from Exchange PIM

The “Snapshot Push” exchange pattern can be described by the following behaviors

The Client provides a mechanism to receive current data, also called “snapshot” of information, i.e. currently available information content of Supplier System, such as active elements or last retrieved information for Sampled data.

This mechanism is referred in this document as “putSnapshotData”.

Figure 6 — Snapshot Push Exchange subsystems and interfaces interactions and method

The Supplier takes the initiative to deliver the data to the Client based on some rules, normally when some condition defined at Supplier side are triggered or in a periodic way; specifically:

• Periodic Push, based on fixed or variable time cycle, depending on application logic at Supplier System

• On Occurrence (Triggered Push), on any condition stated by the Supplier

Relevant Exchange Information in Exchange Data Model¶

Reference to Exchange PIM

General PSM Exchange Messages format¶

Reference to Exchange PIM

Web Services Client description¶

In this profile, the Client uses Web Services classes, automatically generated, to set data and encode the message.

The corresponding WSDL file is given in the Appendix 2 - Snapshot Push WSDL

Each DATEX II Client web service SHOULD be built with the reference WSDL document. If a Client modifies the schema which is imported in the WSDL, he MUST manage and keep interoperability with his DATEX II Suppliers.

This Snapshot Push service WSDL has been built with the following choices:

• define one unique reference WSDL as stable as possible,

• define one WSDL for Snapshot Push DATEX II exchange valid for all DATEX II exchanged data,

• reference to Web Services Interoperability (WS-I) Organization (Re [DOC 1]),

• binding SOAP : style=document, use=literal, following WS-I recommendations.

Remark: SOAPAction http header field (Rule coming from the WSI Basic profile (Re. [DOC 1])) : « The HTTP request MESSAGE MUST contain a SOAPAction HTTP header field with a quoted value equal to the value of the soapAction attribute of soapbind:operation ».

Web Services Supplier description¶

In this profile, the Supplier uses automatically generated Web Services classes, to encode the message and put data.

“2018 DATEX II Exchange reference set” contains a reference WSDL description of the Client Web Service which must be used by the Supplier to build access to the services.

The corresponding WSDL file is given in Appendix 2 - Snapshot Push WSDL

This WSDL file imports the 2018 Snapshot Push Exchange Data Model reference XML schema.

List of requirements implemented¶

Basic Exchange Pattern¶

We resume from Exchange PIM

The Client provides a mechanism to receive data from action taken at Supplier site, Supplier so “pushes” Messages to the Client. The Client will acknowledge what received by a Return Information to the Supplier. So this return message is available to take some information back from Client to the Supplier, these are considered to be encapsulated in D2Container having no Payload but Exchange and CIS related information.

Figure 9 — Simple Push Exchange subsystems and interfaces interactions and method

The mechanisms available are referred in this document as “putData”, “keepAlive” and optional “putSnapshotData”.

Exchanged data can either be current valid data, also called “snapshot” of information, or, after a first transfer of currently valid data, only a set of information which had changed since the last push is exchanged to align the Client System Status. Those including single updated element messages or all updated information elements depending on Update Method chosen.

Relevant Exchange Information in Exchange Data Model¶

Reference to Exchange PIM

Web Services Client description¶

In this profile, the Client uses Web Services classes, automatically generated, to set data and encode the message.

The corresponding WSDL file is given in Appendix 2 Simple Push WSDL.

Each DATEX II Client web service SHOULD be built with the reference WSDL document. If a Client modifies the schema which is imported in the WSDL, he MUST manage and keep interoperability with his DATEX II Suppliers.

This Stateful Push service WSDL has been built with the following choices:

• define one unique reference WSDL as stable as possible,

• define one WSDL for Stateful Push DATEX II exchange valid for all DATEX II exchanged data,

• reference to Web Services Interoperability (WS-I) Organization (Re [DOC 1]),

• binding SOAP : style=document, use=literal, following WS-I recommendations.

Remark: SOAPAction http header field (Rule coming from the WSI Basic profile (Re. [DOC 1])) : « The HTTP request MESSAGE MUST contain a SOAPAction HTTP header field with a quoted value equal to the value of the soapAction attribute of soapbind:operation ».

Web Services Supplier description¶

In this profile, the Supplier uses automatically generated Web Services classes, to encode the message and put data.

“2018 DATEX II Exchange reference set” contains a reference WSDL description of the Client Web Service which must be used by the Supplier to build access to the services.

The corresponding WSDL file is given in Appendix 3 – Simple Push WSDL.

This WSDL file imports the 2018 Stateful Push Exchange Data Model reference XML schema.

List of requirements implemented¶

We resume from Exchange PIM

Basic Exchange Pattern¶

We resume from Exchange PIM

The Client provides a mechanism to receive data from action taken at Supplier site, Supplier so “pushes” Messages to the Client. The Client will acknowledge what received by a Return Information to the Supplier. So this return message is available to take some information back from Client to the Supplier, these are considered to be encapsulated in D2Container having no Payload but Exchange and CIS related information.

Figure 12 — Stateful Push Exchange subsystems and interfaces interactions and method

The mechanisms available are referred in this document as **openSession*, “putData”, “keepAlive” and optional “putSnapshotData”, closeSession.*

Exchanged data can either be current valid data, also called “snapshot” of information, or, after a first transfer of currently valid data, only a set of information which had changed since the last push is exchanged to align the Client System Status. Those including single updated element messages or all updated information elements depending on Update Method chosen.

Relevant Exchange Information in Exchange Data Model¶

Reference to Exchange PIM

General PSM Exchange Messages format¶

Reference to Exchange PIM

Web Services Client description¶

In this profile, the Client uses Web Services classes, automatically generated, to set data and encode the message.

The corresponding WSDL file is given in Appendix 4.

Each DATEX II Client web service SHOULD be built with the reference WSDL document. If a Client modifies the schema which is imported in the WSDL, he MUST manage and keep interoperability with his DATEX II Suppliers.

This Stateful Push service WSDL has been built with the following choices:

• define one unique reference WSDL as stable as possible,

• define one WSDL for Stateful Push DATEX II exchange valid for all DATEX II exchanged data,

• reference to Web Services Interoperability (WS-I) Organization (Re [DOC 1]),

• binding SOAP : style=document, use=literal, following WS-I recommendations.

Remark: SOAPAction http header field (Rule coming from the WSI Basic profile (Re. [DOC 1])) : « The HTTP request MESSAGE MUST contain a SOAPAction HTTP header field with a quoted value equal to the value of the soapAction attribute of soapbind:operation ».