Skip to content

Latest commit

 

History

History
97 lines (59 loc) · 3.56 KB

rpcclient.adoc

File metadata and controls

97 lines (59 loc) · 3.56 KB

RpcClient Interface

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

Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.

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

1. Overview

RpcClient defines a common, language specific interface for method invocation to allow the auto-generation of client-side & server-side code per-language (SDK) in lieu of per platform.

Table 1. API Definition Terminology
Term Description

IN

Input parameter

OUT

Output parameter

IN/OUT

Input/output parameter

&

Parameter passed by reference

?

Parameter is optional

Future

Language specific mechanism to access the result of asynchronous operations, ex. std::future for C++, CompletableFuture for Java, etc…​

2. Interface

All language-specific uProtocol libraries MUST declare the RpcClient interface with method:

OUT Future UMessage invokeMethod(IN UUri, IN UPayload?, IN CallOptions)

Table 2. Parameters

Parameter

Description

UUri

Method URI that is being invoked

CallOptions

Set of attributes that can be sent as part of a method invocation

3. Implementation

Implementations communicate to their underlining transport through the uTransport Interface.

  • Every uPClient library MUST implement the RpcClient interface.

  • The UUri and CallOptions passed to invokeMethod() MUST be cached non-persistent memory per call, this is to be able to complete the Future when the response is received from the server.

  • The UPayload passed to invokeMethod() MAY be null or empty.

  • Method invocation that fails, MUST return exceptionally as defined by the uProtocol Error Model.

  • Cached requests must be completed exceptionally with DEADLINE_EXCEEDED when UAttributes.isExpired() is true. This notifies the calling context that the request has expired.

  • MUST return INVALID_PARAMETER if UUri is null or empty or CallOptions.priority() < CS4

  • MUST return ALREADY_EXISTS if the same request already exists (i.e. same UUri and CallOptions). This is to prevent duplicate requests.

  • MUST complete future successfully when the response is received from the server.