grpc.io/public/docs/quickstart/java/index.html

342 lines
22 KiB
HTML

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css" integrity="sha384-MCw98/SFnGE8fJT3GXwEOngsV7Zt27NXFoaoApmYm81iuXoPkFOJwJ8ERdknLPMO" crossorigin="anonymous">
<link href="https://fonts.googleapis.com/css?family=Open+Sans:300,400" rel="stylesheet">
<link rel="stylesheet" type="text/css" href="/css/style.css">
<title>
Java Quickstart &ndash; gRPC
</title>
<link rel="apple-touch-icon" href="/favicons/apple-touch-icon.png" sizes="180x180">
<link rel="icon" type="image/png" href="/favicons/android-chrome-192x192.png" sizes="192x192" >
<link rel="icon" type="image/png" href="/favicons/favicon-32x32.png" sizes="32x32">
<link rel="icon" type="image/png" href="/favicons/favicon-16x16.png" sizes="16x16">
<link rel="manifest" href="/favicons/manifest.json">
<link rel="mask-icon" href="/favicons/safari-pinned-tab.svg" color="#2DA6B0">
<meta name="msapplication-TileColor" content="#ffffff">
<meta name="msapplication-TileImage" content="/favicons/mstile-150x150.png">
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-60127042-1"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'UA-60127042-1');
</script>
</head>
<body>
<div id="landing-content">
<div class="row">
<div class="topbannersub">
<nav class="navbar navbar-expand-md navbar-dark topnav">
<a class="navbar-brand" href="https://cjyabraham.github.io/">
<img src="https://cjyabraham.github.io/img/grpc-logo.png" width="114" height="50">
</a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div class="topnav, collapse navbar-collapse" id="navbarSupportedContent" style="float:right !important">
<ul class="navbar-nav ml-auto">
<li class="nav-item ">
<a class="nav-link" href="https://cjyabraham.github.io/about/">About</a>
</li>
<li class="nav-item dropdown active">
<a class="nav-link dropdown-toggle" href="https://cjyabraham.github.io/docs/" id="navbarDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
Docs
</a>
<div class="dropdown-menu" aria-labelledby="navbarDropdown">
<a class="dropdown-item" href="/docs">
Overview
</a>
<a class="dropdown-item" href="/docs/quickstart/">
Quick Start
</a>
<a class="dropdown-item" href="/docs/guides/">
Guides
</a>
<a class="dropdown-item" href="/docs/tutorials/">
Tutorials
</a>
<a class="dropdown-item" href="/docs/reference/">
Reference
</a>
<a class="dropdown-item" href="/docs/samples/">
Samples
</a>
<a class="dropdown-item" href="/docs/talks">
Presentations
</a>
</div>
</li>
<li class="nav-item ">
<a class="nav-link" href="/blog">
Blog
</a>
</li>
<li class="nav-item ">
<a class="nav-link" href="/community">Community</a>
</li>
<li class="nav-item">
<a class="nav-link" href="https://packages.grpc.io/">
Packages
</a>
</li>
<li class="nav-item ">
<a class="nav-link" href="https://cjyabraham.github.io/faq/">FAQ</a>
</li>
</ul>
</div>
</nav>
<div class="headertext">Documentation</div>
</div>
</div>
</div>
<div class="subnav d-none d-md-block">
<a href="https://cjyabraham.github.io/docs/" >Overview</a>
| <a href="https://cjyabraham.github.io/docs/quickstart/" class="active">Quick Start</a>
| <a href="https://cjyabraham.github.io/docs/guides/" >Guides</a>
| <a href="https://cjyabraham.github.io/docs/tutorials/" >Tutorials</a>
| <a href="https://cjyabraham.github.io/docs/reference/" >Reference</a>
| <a href="https://cjyabraham.github.io/docs/samples/" >Samples</a>
| <a href="https://cjyabraham.github.io/docs/talks/" >Presentations</a>
</div>
<div class="quickstartcols">
<div class="quickstartcol1">
<h8>Quick Start</h8>
<a href="https://cjyabraham.github.io/docs/quickstart/cpp/" >C++</a>
<a href="https://cjyabraham.github.io/docs/quickstart/csharp/" >C#</a>
<a href="https://cjyabraham.github.io/docs/quickstart/dart/" >Dart</a>
<a href="https://cjyabraham.github.io/docs/quickstart/go/" >Go</a>
<a href="https://cjyabraham.github.io/docs/quickstart/java/" class="active">Java</a>
<a href="https://cjyabraham.github.io/docs/quickstart/android/" >Android Java</a>
<a href="https://cjyabraham.github.io/docs/quickstart/node/" >Node.js</a>
<a href="https://cjyabraham.github.io/docs/quickstart/objective-c/" >Objective-C</a>
<a href="https://cjyabraham.github.io/docs/quickstart/php/" >PHP</a>
<a href="https://cjyabraham.github.io/docs/quickstart/python/" >Python</a>
<a href="https://cjyabraham.github.io/docs/quickstart/ruby/" >Ruby</a>
<a href="https://cjyabraham.github.io/docs/quickstart/web/" >Web</a>
</div>
<div class="quickstartcol2" style="margin-top:4%">
<h3 style="margin-top:0px;">Java Quickstart</h3>
<p class="lead">This guide gets you started with gRPC in Java with a simple
working example.</p>
<div id="toc"></div>
<h3 id="before-you-begin">Before you begin</h3>
<h4 id="prerequisites">Prerequisites</h4>
<ul>
<li><code>JDK</code>: version 7 or higher</li>
</ul>
<h3 id="download-the-example">Download the example</h3>
<p>You&rsquo;ll need a local copy of the example code to work through this quickstart.
Download the example code from our GitHub repository (the following command
clones the entire repository, but you just need the examples for this quickstart
and other tutorials):</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh">$ <span style="color:#75715e"># Clone the repository at the latest release to get the example code:</span>
$ git clone -b v1.20.0 https://github.com/grpc/grpc-java
$ <span style="color:#75715e"># Navigate to the Java examples:</span>
$ cd grpc-java/examples</code></pre></div>
<h3 id="run-a-grpc-application">Run a gRPC application</h3>
<p>From the <code>examples</code> directory:</p>
<ol>
<li>Compile the client and server</li>
</ol>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh"> $ ./gradlew installDist</code></pre></div>
<ol>
<li>Run the server</li>
</ol>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh"> $ ./build/install/examples/bin/hello-world-server</code></pre></div>
<ol>
<li>In another terminal, run the client</li>
</ol>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh"> $ ./build/install/examples/bin/hello-world-client</code></pre></div>
<p>Congratulations! You&rsquo;ve just run a client-server application with gRPC.</p>
<h3 id="update-a-grpc-service">Update a gRPC service</h3>
<p>Now let&rsquo;s look at how to update the application with an extra method on the
server for the client to call. Our gRPC service is defined using protocol
buffers; you can find out lots more about how to define a service in a <code>.proto</code>
file in <a href="/docs/tutorials/basic/java/">gRPC Basics: Java</a>. For now all you need to know is that both the
server and the client &ldquo;stub&rdquo; have a <code>SayHello</code> RPC method that takes a
<code>HelloRequest</code> parameter from the client and returns a <code>HelloReply</code> from the
server, and that this method is defined like this:</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-java" data-lang="java"><span style="color:#75715e">// The greeting service definition.
</span><span style="color:#75715e"></span>service Greeter <span style="color:#f92672">{</span>
<span style="color:#75715e">// Sends a greeting
</span><span style="color:#75715e"></span> rpc <span style="color:#a6e22e">SayHello</span> <span style="color:#f92672">(</span>HelloRequest<span style="color:#f92672">)</span> returns <span style="color:#f92672">(</span>HelloReply<span style="color:#f92672">)</span> <span style="color:#f92672">{}</span>
<span style="color:#f92672">}</span>
<span style="color:#75715e">// The request message containing the user&#39;s name.
</span><span style="color:#75715e"></span>message HelloRequest <span style="color:#f92672">{</span>
string name <span style="color:#f92672">=</span> 1<span style="color:#f92672">;</span>
<span style="color:#f92672">}</span>
<span style="color:#75715e">// The response message containing the greetings
</span><span style="color:#75715e"></span>message HelloReply <span style="color:#f92672">{</span>
string message <span style="color:#f92672">=</span> 1<span style="color:#f92672">;</span>
<span style="color:#f92672">}</span></code></pre></div>
<p>Let&rsquo;s update this so that the <code>Greeter</code> service has two methods. Edit
<code>src/main/proto/helloworld.proto</code> and update it with a new <code>SayHelloAgain</code>
method, with the same request and response types:</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-java" data-lang="java"><span style="color:#75715e">// The greeting service definition.
</span><span style="color:#75715e"></span>service Greeter <span style="color:#f92672">{</span>
<span style="color:#75715e">// Sends a greeting
</span><span style="color:#75715e"></span> rpc <span style="color:#a6e22e">SayHello</span> <span style="color:#f92672">(</span>HelloRequest<span style="color:#f92672">)</span> returns <span style="color:#f92672">(</span>HelloReply<span style="color:#f92672">)</span> <span style="color:#f92672">{}</span>
<span style="color:#75715e">// Sends another greeting
</span><span style="color:#75715e"></span> rpc <span style="color:#a6e22e">SayHelloAgain</span> <span style="color:#f92672">(</span>HelloRequest<span style="color:#f92672">)</span> returns <span style="color:#f92672">(</span>HelloReply<span style="color:#f92672">)</span> <span style="color:#f92672">{}</span>
<span style="color:#f92672">}</span>
<span style="color:#75715e">// The request message containing the user&#39;s name.
</span><span style="color:#75715e"></span>message HelloRequest <span style="color:#f92672">{</span>
string name <span style="color:#f92672">=</span> 1<span style="color:#f92672">;</span>
<span style="color:#f92672">}</span>
<span style="color:#75715e">// The response message containing the greetings
</span><span style="color:#75715e"></span>message HelloReply <span style="color:#f92672">{</span>
string message <span style="color:#f92672">=</span> 1<span style="color:#f92672">;</span>
<span style="color:#f92672">}</span></code></pre></div>
<p>(Don&rsquo;t forget to save the file!)</p>
<h3 id="update-and-run-the-application">Update and run the application</h3>
<p>When we recompile the example, normal compilation will regenerate
<code>GreeterGrpc.java</code>, which contains our generated gRPC client and server classes.
This also regenerates classes for populating, serializing, and retrieving our
request and response types.</p>
<p>However, we still need to implement and call the new method in the human-written
parts of our example application.</p>
<h4 id="update-the-server">Update the server</h4>
<p>In the same directory, open
<code>src/main/java/io/grpc/examples/helloworld/HelloWorldServer.java</code>. Implement the
new method like this:</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-java" data-lang="java"><span style="color:#66d9ef">private</span> <span style="color:#66d9ef">class</span> <span style="color:#a6e22e">GreeterImpl</span> <span style="color:#66d9ef">extends</span> GreeterGrpc<span style="color:#f92672">.</span><span style="color:#a6e22e">GreeterImplBase</span> <span style="color:#f92672">{</span>
<span style="color:#a6e22e">@Override</span>
<span style="color:#66d9ef">public</span> <span style="color:#66d9ef">void</span> <span style="color:#a6e22e">sayHello</span><span style="color:#f92672">(</span>HelloRequest req<span style="color:#f92672">,</span> StreamObserver<span style="color:#f92672">&lt;</span>HelloReply<span style="color:#f92672">&gt;</span> responseObserver<span style="color:#f92672">)</span> <span style="color:#f92672">{</span>
HelloReply reply <span style="color:#f92672">=</span> HelloReply<span style="color:#f92672">.</span><span style="color:#a6e22e">newBuilder</span><span style="color:#f92672">().</span><span style="color:#a6e22e">setMessage</span><span style="color:#f92672">(</span><span style="color:#e6db74">&#34;Hello &#34;</span> <span style="color:#f92672">+</span> req<span style="color:#f92672">.</span><span style="color:#a6e22e">getName</span><span style="color:#f92672">()).</span><span style="color:#a6e22e">build</span><span style="color:#f92672">();</span>
responseObserver<span style="color:#f92672">.</span><span style="color:#a6e22e">onNext</span><span style="color:#f92672">(</span>reply<span style="color:#f92672">);</span>
responseObserver<span style="color:#f92672">.</span><span style="color:#a6e22e">onCompleted</span><span style="color:#f92672">();</span>
<span style="color:#f92672">}</span>
<span style="color:#a6e22e">@Override</span>
<span style="color:#66d9ef">public</span> <span style="color:#66d9ef">void</span> <span style="color:#a6e22e">sayHelloAgain</span><span style="color:#f92672">(</span>HelloRequest req<span style="color:#f92672">,</span> StreamObserver<span style="color:#f92672">&lt;</span>HelloReply<span style="color:#f92672">&gt;</span> responseObserver<span style="color:#f92672">)</span> <span style="color:#f92672">{</span>
HelloReply reply <span style="color:#f92672">=</span> HelloReply<span style="color:#f92672">.</span><span style="color:#a6e22e">newBuilder</span><span style="color:#f92672">().</span><span style="color:#a6e22e">setMessage</span><span style="color:#f92672">(</span><span style="color:#e6db74">&#34;Hello again &#34;</span> <span style="color:#f92672">+</span> req<span style="color:#f92672">.</span><span style="color:#a6e22e">getName</span><span style="color:#f92672">()).</span><span style="color:#a6e22e">build</span><span style="color:#f92672">();</span>
responseObserver<span style="color:#f92672">.</span><span style="color:#a6e22e">onNext</span><span style="color:#f92672">(</span>reply<span style="color:#f92672">);</span>
responseObserver<span style="color:#f92672">.</span><span style="color:#a6e22e">onCompleted</span><span style="color:#f92672">();</span>
<span style="color:#f92672">}</span>
<span style="color:#f92672">}</span>
<span style="color:#f92672">...</span></code></pre></div>
<h4 id="update-the-client">Update the client</h4>
<p>In the same directory, open
<code>src/main/java/io/grpc/examples/helloworld/HelloWorldClient.java</code>. Call the new
method like this:</p>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-java" data-lang="java"><span style="color:#66d9ef">public</span> <span style="color:#66d9ef">void</span> <span style="color:#a6e22e">greet</span><span style="color:#f92672">(</span>String name<span style="color:#f92672">)</span> <span style="color:#f92672">{</span>
logger<span style="color:#f92672">.</span><span style="color:#a6e22e">info</span><span style="color:#f92672">(</span><span style="color:#e6db74">&#34;Will try to greet &#34;</span> <span style="color:#f92672">+</span> name <span style="color:#f92672">+</span> <span style="color:#e6db74">&#34; ...&#34;</span><span style="color:#f92672">);</span>
HelloRequest request <span style="color:#f92672">=</span> HelloRequest<span style="color:#f92672">.</span><span style="color:#a6e22e">newBuilder</span><span style="color:#f92672">().</span><span style="color:#a6e22e">setName</span><span style="color:#f92672">(</span>name<span style="color:#f92672">).</span><span style="color:#a6e22e">build</span><span style="color:#f92672">();</span>
HelloReply response<span style="color:#f92672">;</span>
<span style="color:#66d9ef">try</span> <span style="color:#f92672">{</span>
response <span style="color:#f92672">=</span> blockingStub<span style="color:#f92672">.</span><span style="color:#a6e22e">sayHello</span><span style="color:#f92672">(</span>request<span style="color:#f92672">);</span>
<span style="color:#f92672">}</span> <span style="color:#66d9ef">catch</span> <span style="color:#f92672">(</span>StatusRuntimeException e<span style="color:#f92672">)</span> <span style="color:#f92672">{</span>
logger<span style="color:#f92672">.</span><span style="color:#a6e22e">log</span><span style="color:#f92672">(</span>Level<span style="color:#f92672">.</span><span style="color:#a6e22e">WARNING</span><span style="color:#f92672">,</span> <span style="color:#e6db74">&#34;RPC failed: {0}&#34;</span><span style="color:#f92672">,</span> e<span style="color:#f92672">.</span><span style="color:#a6e22e">getStatus</span><span style="color:#f92672">());</span>
<span style="color:#66d9ef">return</span><span style="color:#f92672">;</span>
<span style="color:#f92672">}</span>
logger<span style="color:#f92672">.</span><span style="color:#a6e22e">info</span><span style="color:#f92672">(</span><span style="color:#e6db74">&#34;Greeting: &#34;</span> <span style="color:#f92672">+</span> response<span style="color:#f92672">.</span><span style="color:#a6e22e">getMessage</span><span style="color:#f92672">());</span>
<span style="color:#66d9ef">try</span> <span style="color:#f92672">{</span>
response <span style="color:#f92672">=</span> blockingStub<span style="color:#f92672">.</span><span style="color:#a6e22e">sayHelloAgain</span><span style="color:#f92672">(</span>request<span style="color:#f92672">);</span>
<span style="color:#f92672">}</span> <span style="color:#66d9ef">catch</span> <span style="color:#f92672">(</span>StatusRuntimeException e<span style="color:#f92672">)</span> <span style="color:#f92672">{</span>
logger<span style="color:#f92672">.</span><span style="color:#a6e22e">log</span><span style="color:#f92672">(</span>Level<span style="color:#f92672">.</span><span style="color:#a6e22e">WARNING</span><span style="color:#f92672">,</span> <span style="color:#e6db74">&#34;RPC failed: {0}&#34;</span><span style="color:#f92672">,</span> e<span style="color:#f92672">.</span><span style="color:#a6e22e">getStatus</span><span style="color:#f92672">());</span>
<span style="color:#66d9ef">return</span><span style="color:#f92672">;</span>
<span style="color:#f92672">}</span>
logger<span style="color:#f92672">.</span><span style="color:#a6e22e">info</span><span style="color:#f92672">(</span><span style="color:#e6db74">&#34;Greeting: &#34;</span> <span style="color:#f92672">+</span> response<span style="color:#f92672">.</span><span style="color:#a6e22e">getMessage</span><span style="color:#f92672">());</span>
<span style="color:#f92672">}</span></code></pre></div>
<h4 id="run">Run!</h4>
<p>Just like we did before, from the <code>examples</code> directory:</p>
<ol>
<li>Compile the client and server</li>
</ol>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh"> $ ./gradlew installDist</code></pre></div>
<ol>
<li>Run the server</li>
</ol>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh"> $ ./build/install/examples/bin/hello-world-server</code></pre></div>
<ol>
<li>In another terminal, run the client</li>
</ol>
<div class="highlight"><pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><code class="language-sh" data-lang="sh"> $ ./build/install/examples/bin/hello-world-client</code></pre></div>
<h3 id="what-s-next">What&rsquo;s next</h3>
<ul>
<li>Read a full explanation of how gRPC works in <a href="/docs/guides/">What is gRPC?</a>
and <a href="/docs/guides/concepts/">gRPC Concepts</a></li>
<li>Work through a more detailed tutorial in <a href="/docs/tutorials/basic/java/">gRPC Basics: Java</a></li>
<li>Explore the gRPC Java core API in its <a href="/grpc-java/javadoc/">reference
documentation</a></li>
</ul>
</div>
</div>
</div>
<script src="https://code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js" integrity="sha384-ZMP7rVo3mIykV+2+9J3UJ46jBk0WLaUAdn689aCwoqbBJiSnjAK/l8WvCWPIPm49" crossorigin="anonymous"></script>
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js" integrity="sha384-ChfqqxuZUCnJSK3+MXmPNIyE6ZbWh2IMqE241rYiqJxyMiZ6OW/JmZQ5stwEULTy" crossorigin="anonymous"></script>
</body>
</html>