Platform Specific Model

Platform Specific Model

Introduction

Based on the DATEX II Platform Independent Model for data exchange (Exchange PIM), this document specifies the Exchange Platform Specific Model (Exchange PSM) for Web Services over http included a simplified option for simple XML retrieval by http/get implementation. The term Web Services is used generically here, since profiles for the Web Services protocol stack (WSDL & SOAP) as well as plain HTTP exchange options are provided.

Reference documents

Datex II documentation

Reference in this document DATEX II documentation
2018 Exchange PIM Exchange PIM
Basic Exchange Data Model Exchange PIM ANNEX

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

Key words

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119:« Key words for use in RFCs to Indicate Requirement Levels ».

Platform Independent model (PIM) Methodology

The Platform Independent Model (Exchange PIM) is described in reference documentation Exchange PIM.

We shortly remind what is needed to fully understand the current specification:

image0

Figure 1 - Exchange PIM/PSM modeling approach

Exchange Global Business Scenarios in the context of Traffic Control Centres are derived abstracting from several use cases and requirements collection.

General Exchange PIM and Platform specific Model (PSM) concepts havebeen identified in

  • Business Scenarios: which refer the context and global purpose for which Exchange is needed, 2 main business scenarios have been identified as:
    • Information Delivery
    • Collaborative ITS Services
  • Requirements: list of general properties of systems which should be implemented in a real environment to grant functionalities based on selected use cases: not all requirements are applicable or needed to all Use Cases or even consistent among themselves, this allow that a subset of requirements leads to different Features needed and consequent choices in Platform.
  • Exchange Environment: list of systems and subsystems which are needed to implement Exchange.
  • Exchange Pattern (EP): a combination of Systems/Subsystems and means of communication among them which enable information exchange which can be combined to implement the Exchange Environment and its requirements.
  • Features: available characteristics implemented in the Exchange Environment, Features can satisfy one or more requirements.
  • Functional Exchange Profile (FEP): based on a specific Exchange Pattern a subset of features may be selected and a subsequent list of requirements can be implemented.
  • FEP/EP based Platform Independent Model (FEP/EP PIM): a description of interaction among actors (systems/subsystems) which describes an Exchange based on the implementation of features, in a way that is independent of specific technology.
  • Platform Specific model (PSM): a definite Implementation of a FEP/EP based PIM which describes subsystems and means of communication under a specific chosen technology / Platform

In the PIM document specific FEP/EP PIM had been defined abstracting from specific technologies. This document deals with PSM description for Stateful Pull and Stateful Push implemented by WebServices.

Web Services definition and options

Web Services provide standard means of interoperating between different software applications, running on a variety of platforms and/or frameworks.

Definition (W3C - Web Service architecture - http://www.w3.org/TR/2004/NOTE-ws-arch-20040211/ ) : « A Web Service is a software system designed to support interoperable machine-to-machine interaction over a network. It has an interface described in a machine-processable format (specifically WSDL). Other systems interact with the Web Service in a manner prescribed by its description using SOAP messages, typically conveyed using HTTP with an XML serialisation in conjunction with other Web-related standards. »

Web Services definitions offer several options. The following table shows the options chosen by DATEX II.

Web Service Options Decision
Discovery Not dynamic : UDDI is not used, the Web Services are described in this DATEX II document which is the reference for development
Security The security set-up has to be decided by the Supplier, should be negotiated with the Clients, and is outside the scope of this specification|
Encryption This has to be agreed between the Supplier and the Client, before starting data exchange

Snapshot Pull based on WebServices

Introduction

Referring to FEP/EP PIM description in PIM document the Snapshot Pull may be implemented by means of SOAP WebServices by implementing a WSDL method Pull at Supplier side. Pull Service enable the Client to retrieve Snapshot Payload content from the Supplier. Pull Messages are implemented by SOAP protocol adding SOAP envelope information.

Supplier system functional description

We resume main PIM features description, leaving to Exchange PIM document full details and PIM description.

We resume the Exchange System diagram from Exchange PIM

image1

Figure 2 - Exchange system for WS based Pull

2.2.1 List of requirements implemented

We resume from Exchange PIM

Features Area Feature Snapshot Pull
Subscription Contract Contract N
  Catalogue N
Session Session life cycle N
  Link Monitoring N
Information management Operating modes Periodic or On Occurrence (i.e. Triggered by Client Condition)
  Update methods Snapshot
  Lifecycle management Y, based on snapshot: new and updated content delivered, outdated data not delivered.
Data delivery Data delivery Y
  Data request N
  Large datasets handling N
  Synchronisation Y
Self-Description Handshake N
Communication Security May be implemented using WS-Security
  Compression May be implemented using WS-Compression
  Communication Defined in following clause

2.2.2 Basic Exchange Pattern

We resume from Exchange PIM

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

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

image2

Figure 3 — Snapshot Pull Exchange subsystems and interfaces interactions and method

The Client ay; e.g.

  • Periodic Pull, based on fixed or variable time cycle, depending on application logic at Client System
  • Triggered Pull, on any condition stated by the Client or by the Client System

Relevant Exchange Information in Exchange Data Model

Reference to Exchange PIM

General PSM Exchange Messages format

Reference to Exchange PIM

Specific SOAP implementation details (communication layer)

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.

Client Pull “Simple http Server” profile

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 http/get within the following clauses which implement all PIM specified features.

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 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.”)

  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.

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

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

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

Authentication

Authentication is supported, i.e. only users with explicit permission are allowed to download payload data. The required access credentials have to be provided to the Client as part of the outcome of the DATEX II subscription creation with the content Supplier, which is here an offline process. The specifications make use of the simplest and most widely spread authentication scheme for HTTP, i.e. BASIC authentication.

Note

This scheme is in itself not seen as sufficiently strong for commercial strength business and safety relevant application, as the password is not encrypted during transmission. Applications that fit into this description will either have to use other Extended Exchange profiles or they will need to establish a sufficiently secure transport layer below DATEX II Exchange.

In essence, the Client receives a user name and password together with a URL which identifies a specific publication from the server. During access, the Client then builds a single string from this (“<username>:<password>”) and encodes it according to base64 encoding rules. The result is put into the Authorization header field of the HTTP REQUEST message.

  1. Clients SHOULD fill access credentials they MAY have received during the subscription negotiation process into the ‘Authorization’ header field of the HTTP REQUEST message.

  2. Server providing access credentials (user name & password) during the subscription negotiation phase MAY respond with response code 401 (Unauthorized) to HTTP REQUESTS that do not contain valid access credentials in the ‘Authorization’ header field

    The regulations in this and the previous section are a clarification on how to use standard features of HTTP/1.1 according to RFC2616. The following sections contain additional regulations that go beyond ‘pure’ HTTP. Anyway, the regulations presented so far have to be seen as clarifications on top of RFC2616. They are compliant with the standard and have to be used in conjunction with the standard itself. This principle holds especially for the handling of HTTP return codes. The following clause summarises the main return codes as used in connections and refers to the standard for the handling of further codes.

  3. Servers SHALL produce and Clients SHALL process the following return codes:

    • 200 (OK), in responses carrying payload,
    • 304 (Not Modified), if no payload is send because of the specification in the ‘If-Modified-Since’ header,
    • 503 (Service Unavailable), if an active HTTP server is disconnected from the content feed,
    • 404 (Not Found), if a file based HTTP server does not have a proper payload document stored in the place associated to the URL.

    Servers SHOULD produce and Clients SHOULD process the following return codes:

    • 401 (Unauthorised), if authentication is required but not presented in the request, or if invalid authentication is presented in the request,
    • 403 (Forbidden), if the requested operation is not successful for any other reason.

    Servers & Client SHALL apply an RFC2616 compliant regime for producing / handling all other return code.

Describing payload and interfaces

Server side Client filtering is not supported! It should also be noted that although such a feature could in principle be incorporated, it would require substantial processing power inside the server and also Client specific information products, which would increase the implementation complexity on the server side substantially. Users aiming at applications based on server side Client filtering are thus advised to consider using the Web Services profile instead!

The profile MAY handle different information to be delivered (such as different DATEX II 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.

  1. Payload data for Information products SHALL be denoted by a URL according to the following convention: d2lcp_infop = “http://” host [“:” port] infop_path “/content.xml” [“?” query] where “info path” is a “path” component as specified in section 3.3 of [RFC 2396], but excluding the last path segment.

    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 have to provide the credentials required to perform authentication for any particular information product.

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

Snapshot Push based on WebServices

Introduction

Referring to FEP/EP PIM description in PIM document the Snapshot Push may be implemented by means of SOAP WebServices by implementing a WSDL method Push at Client side. Push Service offered by the Client enable the Supplier to open a Session and deliver Snapshot Payload content to the Client. Push Messages are implemented by SOAP protocol adding SOAP envelope information.

Client system functional description

We resume main PIM features description, leaving to Exchange PIM document full details and PIM description.

We resume the Exchange System diagram from PIM document

image3

Figure 5 - Exchange system for Snapshot Push Web Services based

List of requirements implemented

We resume from Exchange PIM

Features Area Feature Snapshot Pull
Subscription Contract Contract N
  Catalogue N
Session Session life cycle N
  Link Monitoring N
Information management Operating modes Periodic or On Occurrence (i.e. Triggered by Client Condition)
  Update methods Snapshot
  Lifecycle management Y, based on snapshot: new and updated content delivered, outdated data not delivered.
Data delivery Data delivery Y
  Data request N
  Large datasets handling N
  Synchronisation Y
Self Description handshake N
Communication Security To be defined at PSM Level
  Compression To be defined at PSM Level
  Communication To be defined at PSM Level

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

image4

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

Specific SOAP implementation details (communication layer)

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

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.

Simple Push Webservices Implementation

Introduction

Referring to FEP/EP PIM description in PIM document the Stateful Push may be implemented by means of SOAP Web Services by implementing a WSDL method Push. Push Service enable the Supplier to deliver Payload content to the Client, Push Messages are implemented by SOAP protocol adding SOAP envelope information.

Supplier system functional description

We resume the Exchange System diagram from PIM document:

image3-1

Figure 8 — Stateful Push Exchange actors

This “Stateful Push” adds extra features to the basic Snapshot Push exchange pattern to manage Session Lifecycle and Link Monitoring, as well as synchronisation/realignment in case of communication failures or system maintenance. This mechanism is fully explained in the Exchange PIM document.

List of requirements implemented

Features Area Feature Stateful Push
Subscription Contract Contract N
  Catalogue N
Session Session life cycle Supplier and Client side Managed based on communication error detection and Exchange Information.
  Link Monitoring Y
Information management Operating modes Periodic / On Occurrence based on triggering of Supplier condition
  Update methods Snapshot, Single Element Update, All Element Update
  Lifecycle management Y
Data delivery Data delivery Y
  Data request Snapshot realignment
  Large datasets handling N
  Synchronisation Y
Self Description handshake N
Communication Security At PSM Level
  Compression At PSM Level
  Communication At PSM Level

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.

image5

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

Specific SOAP implementation details (communication layer)

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.

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.

Stateful Push Webservices Implementation

Introduction

Referring to FEP/EP PIM description in PIM document the Stateful Push may be implemented by means of SOAP WebServices by implementing a WSDL method Push. Push Service enable the Supplier to deliver Payload content to the Client, Push Messages are implemented by SOAP protocol adding SOAP envelope information.

Supplier system functional description

We resume the Exchange System diagram from Exchange PIM:

image3-2

Figure 11 — Stateful Push Exchange actors

This “Stateful Push” adds extra features to the basic Snapshot Push exchange pattern to manage Session Lifecycle and Link Monitoring, as well as synchronisation/realignment in case of communication failures or system maintenance. This mechanism is fully explained in the Exchange PIM document.

List of requirements implemented

We resume from Exchange PIM

Features Area Feature Stateful Push
Subscription Contract Contract N
  Catalogue N
Session Session life cycle Supplier and Client side Managed based on communication error detection and Exchange Information.
  Link Monitoring Y
Information management Operating modes Periodic / On Occurrence based on triggering of Supplier condition
  Update methods Snapshot, Single Element Update, All Element Update
  Lifecycle management Y
Data delivery Data delivery Y
  Data request Snapshot realignment
  Large datasets handling N
  Synchronisation Y
Self Description handshake N
Communication Security At PSM Level
  Compression At PSM Level
  Communication At PSM Level

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.

image6

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

Specific SOAP implementation details (communication layer)

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

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 inAppendix 4 – Stateful Push WSDL.

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

User support

Models

Recommended profiles

Exchange 2018

Downloads

DATEX II Archive

Other links