grpc
/
grpc-java
mirror of https://github.com/grpc/grpc-java.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

core: add package level javadoc. 

Fixes #714
This commit is contained in:
Carl Mastrangelo 2016-06-22 18:07:29 -07:00
parent a10712b515
commit e11917e1b8
1 changed files with 37 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
core/src/main/java/io/grpc/package-info.java
View File

@ -29,7 +29,43 @@
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
package io.grpc;
/**
* The gRPC core public API.
*
* <p>gRPC is based on a client-server model of remote procedural calls. A client creates a
* channel which is connected to a server. RPCs are initiated from the client and sent to the
* server which then responds back to the client. When the client and server are done sending
* messages, they half close their respective connections. The RPC is complete as soon as the
* server closes.
*
* <p>To send an RPC, first create a {@link Channel} using {@link ManagedChannelBuilder#forTarget}.
* When using auto generate Protobuf stubs, the stub class will have constructors for wrapping the
* channel. These include {@code newBlockingStub}, {@code newStub}, and {@code newFutureStub}
* which you can use based on your design. The stub is the primary way a client interacts with a
* server.
*
* <p>To receive RPCs, create a {@link Server} using {@link ServerBuilder#forPort}. The Protobuf
* stub will contain an abstract class called AbstractFoo, where Foo is the name of your service.
* Extend this class, and pass an instance of it to {@link ServerBuilder#addService}. Once your
* server is built, call {@link Server#start} to begin accepting RPCs.
*
* <p>Both Clients and Servers should use a custom {@link java.util.concurrent.Executor}. The gRPC
* runtime includes a default executor that eases testing and examples, but is not ideal for use in
* a production environment. See the associated documentation in the respective builders.
*
* <p>Clients and Servers can also be gracefully shutdown gracefully using the {@code shutdown}
* method. The API to conduct an orderly shutdown is modeled from the
* {@link java.util.concurrent.ExecutorService}.
*
* <p>gRPC also includes support for more advanced features, such as name resolution, load
* balancing, bidirectional streaming, health checking, and more. See the relative methods in the
* client and server builders.
*
* <p>Development of gRPC is done primary on Github at
* <a href="https://github.com/grpc/grpc-java">https://github.com/grpc/grpc-java</a>, where the gRPC
* team welcomes contributions and bug reports. There is also a mailing list at
* <a href="https://groups.google.com/forum/#!forum/grpc-io">grpc-io</a> if you have questions
* about gRPC.
*/
package io.grpc;