Skip to content

Latest commit

 

History

History
105 lines (68 loc) · 4.19 KB

languages.adoc

File metadata and controls

105 lines (68 loc) · 4.19 KB
Raw

uProtocol Language Library

Table of Contents

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

Language specific uProtocol libraries (the library), builds the protobuf defined data model from Eclipse-uProtocol Core-API project and adds validators, serializers, and builders specific to the protocol for said data model not covered in protobuf generated code. The library is also responsible to declare the language specific uP-L1 & uP-L2 interfaces uTransport and RpcClient.

Note
 All projects/libraries MUST be released under a permissive license (Apache 2.0, MIT, etc..) and located in GitHub Eclipse-uProtocol project and MUST also depend only on other permissive license libraries.

2. Source

The following section will shall elaborate on the contents and structure of these libraries.

  • The root namespace (package name) MUST be org.eclipse.uprotocol

  • Modules defined in table SDK Modules below MUST be implemented in their own folder (namespace)

  • Each module SHOULD separate the implementation of the specification as defined in table Module Folders/Namespace below.

Table 1. Module Folders/Namespace
Folder Description

validators

static methods to validate the data model

serializer

Any code that is responsible to Serialize and deserialize the data model

factory (or builder)

Factory methods to build the data model per business logic (i.e. to build CloudEvents, UUIDs, etc..)

2.1. Modules

Modules are packages (folders) that reside under the src director. SDK Modules table below lists the required modules.

Table 2. SDK Modules
Folder Specification Description

uri

UUri

How things are addressed in uProtocol

uuid

UUID

Unique ID & timestamp specification

cloudevents

CloudEvents

Specification of how uProtocol data models can be expressed using CloudEvents data model

transport

uTransport

uP-L1 Transport Interface & data model.

rpc

uP-L2 RPC Client

APIs used by clients to invoke methods to simplify implementation of the RPC design pattern.

3. Test

  • SHOULD include a test suite under the folder test

  • MUST be able to run the test suite such that merge requests (commits) cannot be merged till tests are passed

  • SHOULD cover 100% of all code and specifications defined in Source

4. Build

  • MUST be easily built in both a Windows and Linux development environment. Any build requirements (i.e. package dependencies) need to be properly documented in the README

  • MUST be able to be imported to any wellknown IDE (Eclipse, IntelliJ, VSCode, etc..) and include self contained build system to build the code and dependencies(ex. maven, gradle, clang, soong, etc…​).

  • MUST fetch external dependency libraries as handle build dependencies, MUST NOT copy external dependencies

  • MUST NOT depend on external copyright or copyleft libraries/modules, only permissive licenses such as Apache 2.0, MIT, shall be accepted etc..

5. Documentation

  • MUST include a main README.adoc file that explains how to build and use the library.

  • Each module MUST also have a README.adoc that explains how to use said module