View Source

{info}This page documents the definition of service interfaces and the generation of service clients and service stubs. It also describes run-time validation of these interfaces.
{info}

See also:
* [CIDev:R2 Service Implementation Guide]
* [syseng:CIAD COI OV Conversation Management]

h2. Overview

The figure below shows the process for definition system interfaces and generation implementation level and system run-time level artifacts from these interfaces:

!https://docs.google.com/drawings/pub?id=1H9Q15O6Oy0hfJ7gY4lflo8qMFlg3qHzRPKDkSxeXjmQ&w=1248&h=684!

The main steps of this process are:

* Authoring of interfaces, e.g. in Enterprise Architect or a Database tool. Interfaces include services, objects (resources), UI elements and others
* Definition of interfaces in machine-readable form, e.g. in YML or CSV files.
* Generation of stubs and clients used during development time
* Loading of the system interfaces into the system registries during bootstrap
* Adding and updating system interfaces during run time

h2. Details

h3. Interface Authoring

Service interfaces are [authored in Enterprise Architect|http://architecture.oceanobservatories.org/ion/r2/] and listed on the [services page|CIAD OV Services].

h3. Service Interface Definition

Since ION R2, YAML (YML) files are used to define service interfaces. Service interfaces are manually defined and maintained in YML files by the architecture team.

Each service definition provides:

* Service description: name, documentation, link to spec
* Service dependencies on other services
* List of operations. Each operation definition provides:
** Operation name, documentation
** Operation input arguments
** Operation output arguments
** Operation exceptions raised

Operation input and output definitions are lists of named and typed arguments. Arguments may be of a basic type or of an ION object type.

h3. Service Client/Stub Generation

During development time, the service interface files are translated into service programming artifacts (e.g. clients, base classes, interface classes) by the *generate_interfaces* script.

The generate_interfaces script takes the service definitions, in YAML, and transforms them into Python code that can be imported/used or inherited from. See [here|R2 Service Implementation Guide#R2ServiceImplementationGuide-Step4GeneratetheServiceInterfaceYAMLintoaPythonzopeinterface%2Cbaseserviceclass%2Candserviceclients] for the fine details.

h3. Run-time Validation

The Capability Container enforces the following conditions:

*On the service provider side:*

This check happens in the validation interceptor. Checks include:

* Arguments are provided exactly as specified in the interface
** No additional arguments are allowed
** Arguments are either not present (if optional), or present and of the exact type
** Note: sub-types are allowed. E.g. if Resource type is specified, any sub-type such as InstrumentDevice is possible
* ID types are are checked (see [Resource Identifiers|syseng:CIAD COI OV Resource Registry#resource-id])

*On the service requester side:*

These checks happen in the generated service clients and their base classes. Checks include:

* Any allowed arguments and types can be sent

*By a third party observer:*

The intent is

* [syseng:CIAD COI OV Conversation Management]