1 /* 2 * Copyright 2017 The gRPC Authors 3 * 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 17 /** 18 * API for the Stub layer. 19 * 20 * <p>The gRPC Java API is split into two main parts: The stub layer and the call layer. The stub 21 * layer is a wrapper around the call layer. 22 * 23 * <p>In the most common case of gRPC over Protocol Buffers, stub classes are automatically 24 * generated from service definition .proto files by the Protobuf compiler. See <a 25 * href="https://grpc.io/docs/reference/java/generated-code.html">gRPC Java Generated Code Guide</a> 26 * . 27 * 28 * <p>The server side stub classes are abstract classes with RPC methods for the server application 29 * to implement/override. These classes internally use {@link io.grpc.stub.ServerCalls} to interact 30 * with the call layer. The RPC methods consume a {@link io.grpc.stub.StreamObserver} object {@code 31 * responseObserver} as one of its arguments. When users are implementing/override these 32 * methods in the server application, they may call the {@link io.grpc.stub.StreamObserver#onNext 33 * onNext()}, {@link io.grpc.stub.StreamObserver#onError onError()} and {@link 34 * io.grpc.stub.StreamObserver#onCompleted onCompleted()} methods on the {@code responseObserver} 35 * argument to send out a response message, error and completion notification respectively. If the 36 * RPC is client-streaming or bidirectional-streaming, the abstract RPC method should return a 37 * {@code requestObserver} which is also a {@link io.grpc.stub.StreamObserver} object. User should 38 * typically implement the {@link io.grpc.stub.StreamObserver#onNext onNext()}, {@link 39 * io.grpc.stub.StreamObserver#onError onError()} and {@link io.grpc.stub.StreamObserver#onCompleted 40 * onCompleted()} callbacks of {@code requestObserver} to define how the server application would 41 * react when receiving a message, error and completion notification respectively from the client 42 * side. 43 * 44 * <p>The client side stub classes are implementations of {@link io.grpc.stub.AbstractStub} that 45 * provide the RPC methods for the client application to call. The RPC methods in the client stubs 46 * internally use {@link io.grpc.stub.ClientCalls} to interact with the call layer. For asynchronous 47 * stubs, the RPC methods also consume a {@link io.grpc.stub.StreamObserver} object {@code 48 * responseObserver} as one of its arguments, and moreover for client-streaming or 49 * bidirectional-streaming, also return a {@code requestObserver} which is also a {@link 50 * io.grpc.stub.StreamObserver} object. In contrast to the server side, users should implement the 51 * {@link io.grpc.stub.StreamObserver#onNext onNext()}, {@link io.grpc.stub.StreamObserver#onError 52 * onError()} and {@link io.grpc.stub.StreamObserver#onCompleted onCompleted()} callbacks of {@code 53 * responseObserver} to define what the client application would do when receiving a response 54 * message, error and completion notification respectively from the server side, and then pass the 55 * {@code responseObserver} to the RPC method in the client stub. If the RPC method returns a {@code 56 * requestObserver}, users should call the {@link io.grpc.stub.StreamObserver#onNext onNext()}, 57 * {@link io.grpc.stub.StreamObserver#onError onError()} and {@link 58 * io.grpc.stub.StreamObserver#onCompleted onCompleted()} methods on the {@code requestObserver} to 59 * send out a request message, error and completion notification respectively. 60 */ 61 package io.grpc.stub; 62
