1 /* 2 * Copyright 2015 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 * The gRPC core public API. 19 * 20 * <p>gRPC is based on a client-server model of remote procedure calls. A client creates a channel 21 * which is connected to a server. RPCs are initiated from the client and sent to the server which 22 * then responds back to the client. When the client and server are done sending messages, they half 23 * close their respective connections. The RPC is complete as soon as the server closes. 24 * 25 * <p>To send an RPC, first create a {@link io.grpc.Channel} using {@link 26 * io.grpc.ManagedChannelBuilder#forTarget}. When using auto generate Protobuf stubs, the stub class 27 * will have constructors for wrapping the channel. These include {@code newBlockingStub}, {@code 28 * newStub}, and {@code newFutureStub} which you can use based on your design. The stub is the 29 * primary way a client interacts with a server. 30 * 31 * <p>To receive RPCs, create a {@link io.grpc.Server} using {@link io.grpc.ServerBuilder#forPort}. 32 * The Protobuf stub will contain an abstract class called AbstractFoo, where Foo is the name of 33 * your service. Extend this class, and pass an instance of it to {@link 34 * io.grpc.ServerBuilder#addService}. Once your server is built, call {@link io.grpc.Server#start} 35 * to begin accepting RPCs. 36 * 37 * <p>Both Clients and Servers should use a custom {@link java.util.concurrent.Executor}. The gRPC 38 * runtime includes a default executor that eases testing and examples, but is not ideal for use in 39 * a production environment. See the associated documentation in the respective builders. 40 * 41 * <p>Clients and Servers can also be shutdown gracefully using the {@code shutdown} method. The API 42 * to conduct an orderly shutdown is modeled from the {@link java.util.concurrent.ExecutorService}. 43 * 44 * <p>gRPC also includes support for more advanced features, such as name resolution, load 45 * balancing, bidirectional streaming, health checking, and more. See the relative methods in the 46 * client and server builders. 47 * 48 * <p>Development of gRPC is done primary on Github at <a 49 * href="https://github.com/grpc/grpc-java">https://github.com/grpc/grpc-java</a>, where the gRPC 50 * team welcomes contributions and bug reports. There is also a mailing list at <a 51 * href="https://groups.google.com/forum/#!forum/grpc-io">grpc-io</a> if you have questions about 52 * gRPC. 53 */ 54 package io.grpc; 55