Versions Compared

Version Old Version 14 New Version Current
Changes made by

WILSON Scott

WILSON Scott

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Insert excerpt
Task Status
Task Status
nopaneltrue

Table of Contents

Introduction

Service

implementations can use the Advanced Message Queuing Protocol (AMQP) v1.0 international standard. This is available at https://www.amqp.org/.It is discussed in connection with the EUROCONTROL SWIM TI Yellow Profile Specification

design is a step in the service orientation process detailed on the SWIM reference website

. See:

(https://reference.swim.aero/

technical-infrastructure

knowledge/

guidance

service-

for-pub-sub-push-implementation.html
  • https://reference.swim.aero/technical-infrastructure/binding-selection-guidelines.html

    • The issue of topics has been discussed in the FAQ. See:

    Documenting its use

    Info
    titleThe overall approach
    There is no need to rewrite the standards. For example, there is no need to document the operations defined by the standard. It is preferable to refer to where they are documented.

    SWIM-SERV-140 Service functions

    The functionality name could be somehow harmonised for AMQP services or a general term, because it delivers always data.

    Code Blocklanguagejstitle

    orientation-process.html#design). One outcome is a service model (service interface(s), service operation(s), service behaviour).

    This page provides guidance on some aspects of service design.

    Table of Contents

    Naming conventions

    The following section shows how the names appear in a service definition.

    In general:

    • nouns/roles should be as clear as possible.

    • verbs should be from an agreed list (of examples).

    Info

    The following documents will help.

    SWIM-DEFN-140 Service functions

    The functionality expresses the business view of the service. The requirements asks for information about:

    • the functions expected to be offered by the service in support of its capabilities; and

    • their expected real world effects.

    The service metadata schema introduces the need to name the function.

    Natural language is preferred when naming the function. The example below uses two formulations:

    • Provide ...

    • ... Provision

    It is not possible to have a best practice on which is preferred. Both formulations are allowed. The important this to remember is that it is a name and should be as clear and descriptive as possible.

    Example of SWIM-SERV-140 using Service Metadata Schema
    Code Block
    languagejs
    "generalDescription": {
 "functionality": [{
  "name": "
    ...
    Provide Turbulence Forecast Information",
  "description": "
    ..
    A detailed and product-specific description on the delivered product.",
  "realWorldEffect": "
    ..
    Information is provided continually; the service consumer gets the subscribed data."
 }, {
  "name": "
    ..
    Meteorological Forecast Provision",
  "description": "...",
  "realWorldEffect": "..."
 }]
}

    SWIM-

    SERVSWIM-SERV-240 already contains a <noun><role> pattern. e.g

    DEFN-240 Service interfaces

    Name and description could be harmonised e.g. AMQP Notification, AMQP Subscription.

    Advice on naming service interfaces is given in the note to SWIM-SERV-240.

    A service may contain multiple interfaces. Some of these may be private or at least interfaces for specific purposes, e.g. Monitoring or Reporting interfaces. Only exposed service interface need to be documented.

    Info

    SWIM-SERV-240

    Note: To improve readability across service descriptions, it is best practice to apply the following conventions for a service interface name

    • be represented using UpperCamelCase; and

    • use the <noun> <role> pattern where <noun> is a topic related to the service and <role> describes the roles in a composition/interaction sequence, based on the Message Exchange Pattern that is used.

    Example service interface names: FlightPlanCoordinator, FlightPlanSubmitter, ForecastProvider, ForecastConsumer, ClearanceRequester, ClearanceManager, PreDepartureSequencer, FlightInformationPublisher, AlertListener.

    Info

    It is best to avoid mention of a broker. Indeed, a broker is not necessary when using AMQP.

    Examples based on this from the SWIM Registry:

    (not AMQP but shows the same pattern for names).

    As far as AMQP is converned, what are the roles?

    • Publisher, Queue, Message...

    SWIM-SERV-250 SWIM TI Profile and interface bindings

    The best practice could be a link to ... specifications to header/content-type information (e.g. AMQP header information to encoding, message-annotation etc.)

    Code Block
    languagejs
    titleExample of SWIM-SERV-250 using Service Metadata Schema
    "serviceInterface": [{
 "serviceInterfaceBinding": {
  "name": "SWIM_TI_YP_1_1_AMQP_MESSAGING",
  "description": "..."
 }
}

    SWIM-SERV-270 Service operations

    A harmonised entry for AMQP delivery. Consider a controlled vocabulary of verbs for names.

    SWIM-SERV-270 proposes <verb><noun> e.g.getAlerts; requestTrajectoryAnalysis; publishAirportMETInducedCapacity; setCoordinationAndTransferData; proposeARESDeActivation.

    Which verbs are best in the context of AMQP?

    SWIM-SERV-280 Service messages

    SWIM-DEFN-270 Service operations

    Advice for naming service operations is given in the note to SWIM-SERV-270.

    Info

    SWIM-SERV-270

    Note: To improve readability across service descriptions, it is best practice to apply following conventions for a service operation name:

    • include a verb and a noun; and

    • be represented using lowerCamelCase.

    Example service operation names: getAlerts; requestTrajectoryAnalysis; publishAirportMETInducedCapacity; setCoordinationAndTransferData; proposeARESDeActivation; setTargetOffBlockTime.

    An example of this convention can be seen in the Web Feature Service standard's getFeature, getCapabilities and getFeatureType operations.

    The AMQP 1.0 standard uses message queues. A service consumer can subscribe to a specific endpoint (which is user specific) to get a message.

    Operations from the service provider point of view, e.g., when a broker is used (see BROKERED_PUBLISH_SUBSCRIBE_WITH_PUSH_MECHANISM) could be publishTurbulenceForecast. The use of the broker should be transparent to the service consumer.

    Info

    Note that there is no need to document operations if a standardised implementation is used. See Documenting the use of standardised implementations for more information.

    Categorisation

    SWIM-DEFN-100 Service categories

    The following example shows how to

    document the service messagelanguagejstitle

    add a service categorisation for a Web Feature Service.

    Code Block
    Note

    The URL used in the example does not exist yet. It is waiting for the service category page to be updated.

    Example of SWIM-SERV-
    280
    100 using Service Metadata Schema
    "serviceInterface
    Code Block
    languagejs
    "serviceCategorisation":
    [
    {
     
     "
    messages
    other": [{
     
      "name": "
    AMQP message body
    SERVICE_TYPE",
     
      "
    description
    value": "
    The AMQP message body contains the OPMET data in IWXXM3.0
    FEATURE_ACCESS_SERVICE",
     
      "
    schema
    categorisationScheme": {
      
     "url": "
    https
    http://
    schemas
    reference.
    wmo
    swim.
    int
    aero/
    iwxxm/3.0.0/"  
    information-services/service-categories/CodeServiceType"
  }
     
     }]
    , ...
    
}
    ]

    Adding the reference

    Info

    There is no need to mention the use of AMQP as part of SWIM-SERV-120 Service standard reference. It is more concerned with service definitions produced by the various ATM communities.

    However, a service standard listed as part of SWIM-SERV-120 may include statements on the use of AMQP. In that case, any deviations from the service standard should be noted.

    The following example shows how to document the use of AMQP in the list of references.

    Code Block
    languagejs
    titleExample of references using Service Metadata Schema
    "references": { "serviceDocument": [{ "documentType": "PROTOCOL_SPECIFICATION", "title": "Advanced Message Queuing Protocol (AMQP)", "version": "1.0", "description": "The Advanced Message Queuing Protocol (AMQP) is an open internet protocol for business messaging.", "reference": { "url": "https://www.amqp.org/" } } ] }
    Application Message Exchange Patterns
    SWIM-DEFN-210 Application message exchange pattern
    Guidance on the selection of the application message exchange pattern can be found on the SWIM reference resource pages.
    In general: