Skip to content

Commit 6be703d

Browse files
author
Steven Hartley
authored
uProtocol 1.5 (#16)
uProtocol 1.5 introduces the following: * Updates to UUri to add micro format (represent URIs using names and numbers) * uTransport interface & data model * uLink & language specific library requirements * Various doc fixes/updates #13
1 parent 0afc605 commit 6be703d

11 files changed

Lines changed: 2218 additions & 1054 deletions

File tree

up-l2/permissions.adoc renamed to basics/permissions.adoc

File renamed without changes.

‎basics/uri.adoc‎

Lines changed: 282 additions & 37 deletions
Large diffs are not rendered by default.

‎basics/uri.drawio.svg‎

Lines changed: 208 additions & 4 deletions
Loading

‎basics/uuri.drawio.svg‎

Lines changed: 779 additions & 0 deletions
Loading

‎languages.adoc‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
= Language Specific Library
2+
:toc:
3+
:sectnums:
4+
5+
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 https://www.rfc-editor.org/info/bcp14[IETF BCP14 (RFC2119 & RFC8174)]
6+
7+
----
8+
Licensed to the Apache Software Foundation (ASF) under one
9+
or more contributor license agreements. See the NOTICE file
10+
distributed with this work for additional information
11+
regarding copyright ownership. The ASF licenses this file
12+
to you under the Apache License, Version 2.0 (the
13+
"License"); you may not use this file except in compliance
14+
with the License. You may obtain a copy of the License at
15+
16+
http://www.apache.org/licenses/LICENSE-2.0
17+
18+
Unless required by applicable law or agreed to in writing,
19+
software distributed under the License is distributed on an
20+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21+
KIND, either express or implied. See the License for the
22+
specific language governing permissions and limitations
23+
under the License.
24+
----
25+
26+
== Overview
27+
The language specific uProtocol libraries (_the library_) shall package the various interface and data models that are used by software developers and other uProtocol libraries.
28+
29+
NOTE: *MUST* be released under a permissive license (Apache 2.0, MIT, etc..) and located in https://github.com/eclipse-uprotocol[GitHub Eclipse-uProtocol] project.
30+
31+
32+
== Source
33+
The following section will shall elaborate on the contents and structure of these libraries.
34+
35+
* The root namespace (package name) *MUST* be `org.eclipse.uprotocol`
36+
* Modules defined in table <<content>> below *MUST* be implemented in their own folder (namespace)
37+
* Each module *MUST* divide the implementation of the specification as defined in table <<folders>> below
38+
39+
40+
.Module Folders/Namespace
41+
[#folders,width="80%",cols="20%,80%",options="header"]
42+
|===
43+
| Folder | Description
44+
45+
| `validators`
46+
| static methods to validate the data model
47+
48+
| `serializer`
49+
| Any code that is responsible to Serialize and deserialize the data model
50+
51+
| `factory` (or `builder`)
52+
| Factory methods to build the data model per business logic (i.e. to build CloudEvents, UUIDs, etc..)
53+
54+
|===
55+
56+
57+
=== Modules
58+
59+
Modules are packages (folders) that reside under the `src` director. <<content>> table below lists the required modules.
60+
61+
.SDK Modules
62+
[#content,width="100%",cols="20%,20%,60%",options="header"]
63+
|===
64+
| Folder | Specification |Description
65+
66+
| `uri`
67+
| link:basics/uri.adoc[UUri]
68+
| How things are addressed in uProtocol
69+
70+
| `uuid`
71+
| link:basics/uuid.adoc[UUID]
72+
| Unique ID & timestamp specification
73+
74+
| `cloudevents`
75+
| link:up-l1/cloudevents.adoc[CloudEvents]
76+
| Specification of how uProtocol data models can be expressed using CloudEvents data model
77+
78+
| `transport`
79+
| link:up-l1/README.adoc[uTransport]
80+
a| uP-L1 Transport Interface & data model.
81+
82+
* *MUST* declare the interface & data model where as link:../ulink.adoc[uLink Libraries] implement the said interface.
83+
84+
| `rpcclient`
85+
| link:up-l2/rpcclient.adoc[uP-L2 RPC Client]
86+
a|API used by uP-L3 code generators to generate the client-side boundary objects for uServices. The interface wrap method invocation (uP-L2) such that generated client-side code does not have to be platform (or transport) specific, only language specific.
87+
88+
* *MUST* declare the interface & data model where as link:../ulink.adoc[uLink Libraries] implement the said interface.
89+
90+
|===
91+
92+
93+
== Test
94+
95+
* *SHOULD* include a test suite under the folder `test`
96+
* *MUST* be able to run the tes test suite the command line (i.e. `mvn test`) such that it can be added to a workflow for each commit
97+
* *MUST* cover 100% of all code and specifications defined in <<Source>>
98+
99+
100+
== Build
101+
102+
* *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
103+
* *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...).
104+
* *MUST* fetch external dependency libraries as handle build dependencies, *MUST NOT* copy external dependencies
105+
* *MUST NOT* depend on external copyright or copyleft libraries/modules, only permissive licenses such as Apache 2.0, MIT, shall be accepted etc..
106+
107+
108+
== Documentation
109+
110+
* *MUST* include a main README.adoc file that explains how to build and use the library.
111+
* Each module *MUST* also have a README.adoc that explains how to use said module

‎ulink.adoc‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
= uLink Library & APIs
2+
:toc:
3+
:sectnums:
4+
5+
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 https://www.rfc-editor.org/info/bcp14[IETF BCP14 (RFC2119 & RFC8174)]
6+
7+
----
8+
Licensed to the Apache Software Foundation (ASF) under one
9+
or more contributor license agreements. See the NOTICE file
10+
distributed with this work for additional information
11+
regarding copyright ownership. The ASF licenses this file
12+
to you under the Apache License, Version 2.0 (the
13+
"License"); you may not use this file except in compliance
14+
with the License. You may obtain a copy of the License at
15+
16+
http://www.apache.org/licenses/LICENSE-2.0
17+
18+
Unless required by applicable law or agreed to in writing,
19+
software distributed under the License is distributed on an
20+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21+
KIND, either express or implied. See the License for the
22+
specific language governing permissions and limitations
23+
under the License.
24+
----
25+
26+
== Overview
27+
28+
uLink refers to a library and boundary object used by all uEs (apps, services, core uEs, etc...) to communicate with each other on a given uPlatform. The library contains a transport specific implementation of the link:up-l1/README.adoc[uTransport] and link:up-l2/rpcclient.adoc[RpcClient] interfaces. The library is language specific so there is a new library per supported link:sdk.adoc[uProtocol SDK Libraries].
29+
30+
== Requirements
31+
32+
=== uLink Library
33+
34+
* *MUST* contain a boundary object called `ULink`
35+
* *MUST* be language specific (one library per language)
36+
37+
38+
=== Boundary Object
39+
40+
Below are the requirements for the ULink boundary object.
41+
42+
* *MUST* implement the link:up-l1/README.adoc[uTransport] interface
43+
* *MUST* implement the link:up-l2/rpcclient.adoc[RpcClient] interface
44+
* *MUST* be named `ULink`
45+
* *MUST NOT* be more than one instance of ULink per URI addressable uE, this is because the protocol only can address at the uE name level. This is due to the fact uProtocol address is a singleton as the UUri can only address at the uE level .
46+
47+

0 commit comments

Comments
 (0)