blob: 42a92483b4dc8d7f9756406363d421b943c4695f [file] [log] [blame]
Andrea Campanella378e21a2017-06-07 12:09:59 +02001/*
Brian O'Connora09fe5b2017-08-03 21:12:30 -07002 * Copyright 2017-present Open Networking Foundation
Andrea Campanella378e21a2017-06-07 12:09:59 +02003 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package org.onosproject.grpc.api;
18
19import com.google.common.annotations.Beta;
20import io.grpc.ManagedChannel;
21import io.grpc.ManagedChannelBuilder;
Andrea Campanella378e21a2017-06-07 12:09:59 +020022
Carmelo Casconec2be50a2019-04-10 00:15:39 -070023import java.net.URI;
Andrea Campanella378e21a2017-06-07 12:09:59 +020024import java.util.Optional;
25
26/**
Carmelo Casconec2be50a2019-04-10 00:15:39 -070027 * Abstraction of a gRPC controller that creates, stores, and manages gRPC
28 * channels.
Andrea Campanella378e21a2017-06-07 12:09:59 +020029 */
30@Beta
Yi Tseng2a340f72018-11-02 16:52:47 -070031public interface GrpcChannelController {
Andrea Campanella378e21a2017-06-07 12:09:59 +020032
Carmelo Casconec2be50a2019-04-10 00:15:39 -070033 /**
34 * Creates a gRPC managed channel to the server identified by the given
35 * channel URI. The channel is created using the information contained in the
36 * URI, as such, the URI is expected to have absolute server-based form,
37 * where the scheme can be either {@code grpc:} or {@code grpcs:}, to
38 * indicated respectively a plaintext or secure channel.
39 * <p>
40 * Example of valid URIs are: <pre> {@code
41 * grpc://10.0.0.1:50001
42 * grpcs://10.0.0.1:50001
43 * grpcs://myserver.local:50001
44 * }</pre>
45 * <p>
46 * This method creates and stores the channel instance associating it to the
47 * passed URI, but it does not make any attempt to connect the channel or
48 * verify server reachability.
49 * <p>
50 * If another channel with the same URI already exists, an {@link
51 * IllegalArgumentException} is thrown. To create multiple channels to the
52 * same server-port combination, URI file or query parameters can be used.
53 * For example: <pre> {@code
54 * grpc://10.0.0.1:50001/foo
55 * grpc://10.0.0.1:50001/bar
56 * grpc://10.0.0.1:50001/bar?param=1
57 * grpc://10.0.0.1:50001/bar?param=2
58 * }</pre>
59 * <p>
60 * When creating secure channels (i.e., {@code grpcs:)}, the current
61 * implementation provides encryption but not authentication, any server
62 * certificate, even if insecure, will be accepted.
63 *
64 * @param channelUri channel URI
65 * @return the managed channel created
66 * @throws IllegalArgumentException if a channel with the same channel URI
67 * already exists
68 */
69 ManagedChannel create(URI channelUri);
Andrea Campanella378e21a2017-06-07 12:09:59 +020070
71 /**
Carmelo Casconec2be50a2019-04-10 00:15:39 -070072 * Similar to {@link #create(URI)} but does not create the chanel instance,
73 * instead, it uses the given channel builder to create it. As such, there
74 * is no requirement on the format of the URI, any URI can be used. The
75 * implementation might modify the passed builder for purposes specific to
76 * this controller, such as to enable gRPC message logging.
Andrea Campanella378e21a2017-06-07 12:09:59 +020077 *
Carmelo Casconec2be50a2019-04-10 00:15:39 -070078 * @param channelUri URI identifying the channel
Carmelo Cascone47a853b2018-01-05 02:40:58 +010079 * @param channelBuilder builder of the managed channel
80 * @return the managed channel created
Carmelo Cascone6d57f322018-12-13 23:15:17 -080081 * @throws IllegalArgumentException if a channel with the same ID already
82 * exists
Andrea Campanella378e21a2017-06-07 12:09:59 +020083 */
Carmelo Casconec2be50a2019-04-10 00:15:39 -070084 ManagedChannel create(URI channelUri,
85 ManagedChannelBuilder<?> channelBuilder);
Andrea Campanella378e21a2017-06-07 12:09:59 +020086
87 /**
Carmelo Casconec2be50a2019-04-10 00:15:39 -070088 * Closes and destroys the gRPC channel associated to the given URI and
89 * removes any internal state associated to it.
Andrea Campanella378e21a2017-06-07 12:09:59 +020090 *
Carmelo Casconec2be50a2019-04-10 00:15:39 -070091 * @param channelUri URI of the channel to remove
Andrea Campanella378e21a2017-06-07 12:09:59 +020092 */
Carmelo Casconec2be50a2019-04-10 00:15:39 -070093 void destroy(URI channelUri);
Andrea Campanella378e21a2017-06-07 12:09:59 +020094
95 /**
Carmelo Casconec2be50a2019-04-10 00:15:39 -070096 * If present, returns the channel associated with the given URI.
Andrea Campanella378e21a2017-06-07 12:09:59 +020097 *
Carmelo Casconec2be50a2019-04-10 00:15:39 -070098 * @param channelUri channel URI
Carmelo Cascone47a853b2018-01-05 02:40:58 +010099 * @return optional channel
Andrea Campanella378e21a2017-06-07 12:09:59 +0200100 */
Carmelo Casconec2be50a2019-04-10 00:15:39 -0700101 Optional<ManagedChannel> get(URI channelUri);
Andrea Campanella378e21a2017-06-07 12:09:59 +0200102}