Message Containers and Versioning: Unterschied zwischen den Versionen

Aus DRV STRING
Wechseln zu: Navigation, Suche
K
 
(2 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt)
Zeile 1: Zeile 1:
Our mission is to create an interface which is ''backwards compatible'' within a major version. '''Backwards compatible''' we define as never changing existing elements and types but only adding new ones, making them optional. Thus a message of version x.y will be completely valid in x.y+1 while x.y+1 messages will not necessarily validate in x.y but may be used when not validated against the schema.
+
Our mission is to create an interface which is ''backwards compatible'' within a major version. '''Backwards compatible''' we define as never changing existing elements and types but only adding new ones, making them optional. Thus a message of version <code>x.y</code> will be completely valid in <code>x.y+1</code> while <code>x.y+1</code> messages will not necessarily validate in <code>x.y</code> but may be used when not validated against the schema.
  
 
We encourage using several versions at the same time to ease transitions and migrating to new (minor or major) versions. A version is defined as the set of schemas excluding the container ''StringMessage'' (and the ''DrvGlobalTypes'' which are not part of the STRING project).
 
We encourage using several versions at the same time to ease transitions and migrating to new (minor or major) versions. A version is defined as the set of schemas excluding the container ''StringMessage'' (and the ''DrvGlobalTypes'' which are not part of the STRING project).
  
A ''StringMessage'' is a generic request/response pair containing versioning information and a <Content> element defined as xs:anyType which will contain the payload valid for the given version. An empty ''StringMessage'' should be replied to with the list of valid versions for the operator system.
+
A ''StringMessage'' is a generic request/response pair containing versioning information and a <code><Content></code> element defined as xs:anyType which will contain the payload valid for the given version. An empty ''StringMessage'' should be replied to with the list of valid versions for the operator system.
 +
 
 +
We will define a separate namespace per major version. Minor versions will live in the same namespace.
  
 
=== Request / Response with Payload ===
 
=== Request / Response with Payload ===
Zeile 50: Zeile 52:
 
</StringMessageResponse>
 
</StringMessageResponse>
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
 +
This shows a ''Configuration'' request / response (empty for this example) being transferred in the ''StringMessage'' container.
 +
 +
=== Request / Response with Version Information ===
 +
 +
<syntaxhighlight lang="xml">
 +
<StringMessageRequest xmlns="http://string.drv.de/xmlschema/string" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
 +
</syntaxhighlight>
 +
 +
<syntaxhighlight lang="xml">
 +
<StringMessageResponse xmlns="http://string.drv.de/xmlschema/string" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 +
  <SupportedVersions>
 +
    <Version>0.8</Version>
 +
    <Version>0.9</Version>
 +
    <Version>1.0</Version>
 +
  </SupportedVersions>
 +
</StringMessageResponse>
 +
</syntaxhighlight>
 +
 +
An empty ''StringMessage'' triggers a list of supported versions. ''(This example has been superseded and will be replaced!)''

Aktuelle Version vom 16. Oktober 2018, 15:00 Uhr

Our mission is to create an interface which is backwards compatible within a major version. Backwards compatible we define as never changing existing elements and types but only adding new ones, making them optional. Thus a message of version x.y will be completely valid in x.y+1 while x.y+1 messages will not necessarily validate in x.y but may be used when not validated against the schema.

We encourage using several versions at the same time to ease transitions and migrating to new (minor or major) versions. A version is defined as the set of schemas excluding the container StringMessage (and the DrvGlobalTypes which are not part of the STRING project).

A StringMessage is a generic request/response pair containing versioning information and a <Content> element defined as xs:anyType which will contain the payload valid for the given version. An empty StringMessage should be replied to with the list of valid versions for the operator system.

We will define a separate namespace per major version. Minor versions will live in the same namespace.

Request / Response with Payload

<StringMessageRequest xmlns="http://string.drv.de/xmlschema/string" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Version>0.9</Version>
  <Content>
    <StringRequest TimeStamp="2018-04-13T13:44:33Z" Version="0.9" xmlns="http://string.drv.de/xmlschema/string/v0">
      <Requestor>
        <Agency>
          <AgencyID>1</AgencyID>
        </Agency>
      </Requestor>
      <MessageContext>
        <TouroperatorCode>BEWO</TouroperatorCode>
        <TouroperatorSessionID>none</TouroperatorSessionID>
        <ExternalSessionID>none</ExternalSessionID>
        <TransactionCounter>1</TransactionCounter>
      </MessageContext>
      <ConfigurationRequest/>
    </StringRequest>
  </Content>
</StringMessageRequest>
<StringMessageResponse xmlns="http://string.drv.de/xmlschema/string" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Version>0.9</Version>
  <Content>
    <StringResponse Success="true" TimeStamp="2018-04-13T13:44:34Z" xmlns="http://string.drv.de/xmlschema/string/v0">
      <Requestor>
        <Agency>
          <AgencyID>1</AgencyID>
        </Agency>
      </Requestor>
      <MessageContext>
        <TouroperatorCode>BEWO</TouroperatorCode>
        <TouroperatorSessionID>none</TouroperatorSessionID>
        <ExternalSessionID>none</ExternalSessionID>
        <TransactionCounter>1</TransactionCounter>
      </MessageContext>
      <ConfigurationResponse/>
    </StringResponse>
  </Content>
</StringMessageResponse>

This shows a Configuration request / response (empty for this example) being transferred in the StringMessage container.

Request / Response with Version Information

<StringMessageRequest xmlns="http://string.drv.de/xmlschema/string" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
<StringMessageResponse xmlns="http://string.drv.de/xmlschema/string" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <SupportedVersions>
    <Version>0.8</Version>
    <Version>0.9</Version>
    <Version>1.0</Version>
  </SupportedVersions>
</StringMessageResponse>

An empty StringMessage triggers a list of supported versions. (This example has been superseded and will be replaced!)