languages.adoc

uProtocol Language Library

Table of Contents

• 1. Overview
• 2. Requirements
  • 2.1. Content
  • 2.2. Test & CI
  • 2.3. Build
• 3. Class Diagram

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 IETF BCP14 (RFC2119 & RFC8174)

SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation

See the NOTICE file(s) distributed with this work for additional
information regarding copyright ownership.

This program and the accompanying materials are made available under
the terms of the Apache License Version 2.0 which is available at
https://www.apache.org/licenses/LICENSE-2.0

SPDX-FileType: DOCUMENTATION
SPDX-License-Identifier: Apache-2.0

1. Overview

uProtocol Language specific libraries (libraries) are written for a given programming language (ex. Java, C++, etc…​) to implement the protocol and are the primary library that is used by applications and services (uEs) to communicate with other uEs. The libraries declare the API for the uProtocol Transport (uP-L1) and Communication Layers (uP-L2) and provide a generic implementation of the latter.

2. Requirements

2.1. Content

A language library

• MUST declare the language specific uProtocol Transport Layer interface, such that the interface can be implemented by the transport libraries.

• MUST declare the language specific uProtocol Communication Layer (uP-L2) API, such that the interface MAY be implemented by the transport libraries.

• MUST provide a default implementation of uProtocol Communication Layer (uP-L2) API based on the (abstract) Transport Layer API.

• MUST be named according to pattern up-[LANGUAGE], e.g. up-rust or up-python.

• MUST use the programming language specific namespace concept, if availabe, to indicate that the library belongs to the uProtocol project. If the language supports hierarchical namespaces (like Java does), then org.eclipse.uprotocol SHOULD be used. Otherwise, a namespace of uprotocol MUST be used.

• MUST contain a README file that explains how to build and use the library.

2.2. Test & CI

A language library

• SHOULD contain a test suite that covers 100% of all code and specifications defined in Content

• MUST use a CI workflow that prevents pull requests from being merged if they cannot be built.

• MUST use a CI workflow that prevents pull requests from being merged if the library’s test suite does not pass.

• MUST use a CI workflow that prevents pull requests from being merged if the library’s source code does not comply with the project’s code linting rules.

• MUST use a CI workflow that prevents pull requests from being merged if the library’s source code does not contain proper API documentation.

2.3. Build

A language library

• MUST employ an existing build system that is commonly used for the given programming language.

• MUST resolve and include external dependencies as part of the build process only.

3. Class Diagram

Class Diagram