content/references/java-chassis/en_US/build-provider/jaxrs/index.html (468 lines of code) (raw):
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link rel="shortcut icon" href="../../img/favicon.ico" />
<title>Develop with JAX-RS - ServiceComb Java Chassis Developers Guide</title>
<link rel="stylesheet" href="../../css/theme.css" />
<link rel="stylesheet" href="../../css/theme_extra.css" />
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/styles/github.min.css" />
<script>
// Current page data
var mkdocs_page_name = "Develop with JAX-RS";
var mkdocs_page_input_path = "build-provider/jaxrs.md";
var mkdocs_page_url = null;
</script>
<script src="../../js/jquery-3.6.0.min.js" defer></script>
<!--[if lt IE 9]>
<script src="../../js/html5shiv.min.js"></script>
<![endif]-->
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/highlight.min.js"></script>
<script>hljs.initHighlightingOnLoad();</script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<a href="../.." class="icon icon-home"> ServiceComb Java Chassis Developers Guide
</a><div role="search">
<form id ="rtd-search-form" class="wy-form" action="../../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" title="Type search term here" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../..">Introduction</a>
</li>
</ul>
<p class="caption"><span class="caption-text">Getting Started</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../start/terminology/">Glossary</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../start/architecture/">Architecture</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../start/development-environment/">Development environment</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../start/first-sample/">Develop the first microservice</a>
</li>
</ul>
<p class="caption"><span class="caption-text">Development Service Provider</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../definition/service-definition/">Service definition</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../define-contract/">Service contract definition</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../code-first/">Implicit API definition</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../swagger-annotation/">Use Swagger annotations</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../springmvc/">Develop with SpringMVC</a>
</li>
<li class="toctree-l1 current"><a class="reference internal current" href="./">Develop with JAX-RS</a>
<ul class="current">
<li class="toctree-l2"><a class="reference internal" href="#concept-description">Concept Description</a>
</li>
<li class="toctree-l2"><a class="reference internal" href="#development-example">Development Example</a>
</li>
<li class="toctree-l2"><a class="reference internal" href="#involved-apis">Involved APIs</a>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../transparent-rpc/">Develop with Transparent RPC</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../interface-constraints/">Interface definition and data type</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../listen-address-and-publish-address/">Service listening address and publishing address</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../thread-pool/">Thread pool</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="#">Service Configuration</a>
<ul>
<li class="toctree-l2"><a class="reference internal" href="../configuration/ratelimite-strategy/">Rate Limiting Policy</a>
</li>
<li class="toctree-l2"><a class="reference internal" href="../configuration/downgrade-strategy/">Fallback Policy</a>
</li>
<li class="toctree-l2"><a class="reference internal" href="../configuration/parameter-validator/">Parameter Validator</a>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../bootup/">Boot-up Process</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../access-log-configuration/">Access Log Configuration</a>
</li>
</ul>
<p class="caption"><span class="caption-text">Writing Service Consumer</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../build-consumer/common-configuration/">Consumer common configuration</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../build-consumer/using-resttemplate/">Using Rest Template</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../build-consumer/using-AsyncRestTemplate/">Using AsyncRestTemplate</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../build-consumer/develop-consumer-using-rpc/">Using with RPC</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../build-consumer/with-contract/">Contract</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="#">Invoke control</a>
<ul>
<li class="toctree-l2"><a class="reference internal" href="../../build-consumer/circuit-breaker/">Circuit Breaker</a>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../build-consumer/flow-control/">Flow Control</a>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../build-consumer/fault-injection/">Fault Injection</a>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../build-consumer/3rd-party-service-invoke/">Invoke 3rd-party REST services</a>
</li>
</ul>
<p class="caption"><span class="caption-text">Transports</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../transports/rest-over-servlet/">REST over Servlet</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../transports/rest-over-vertx/">REST over Vertx</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../transports/highway-rpc/">Highway</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../transports/http2/">HTTP2</a>
</li>
</ul>
<p class="caption"><span class="caption-text">General Development</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../general-development/visit-sc/">Access Service Center</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../general-development/metrics/">Metrics</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../general-development/microservice-invocation-chain/">Microservice invocation chain</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../general-development/customized-tracing/">Customized-Tracing</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../general-development/local-develop-test/">Local development and testing</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../general-development/http-filter/">Http Filter</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../general-development/file-upload/">File Uploading</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../general-development/file-download/">File Downloading</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../general-development/reactive/">Reactive Programing</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../general-development/dnsconfig/">DNS Custom Configuration</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../general-development/dai-li-she-zhi/">Proxy Settings</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../general-development/report-framework-version/">Report framework version</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../general-development/cross-app-invocation/">Cross-application invocation</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../general-development/secret-field/">Customized serialization and deserialization</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../general-development/context/">Using Context to pass control messages</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../general-development/produceprocess/">Return value serialization extension</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../general-development/CORS/">CORS mechanism</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../general-development/AlarmEvent/">Get fuse and instance isolation alarm event information</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../general-development/shutdown/">Shutdown gracefully</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../general-development/error-handling/">Handling exceptions</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../general-development/multienvironment/">Multi-environment isolation between microservice instances</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../general-development/thread-model/">Thread Model</a>
</li>
</ul>
<p class="caption"><span class="caption-text">Configuration</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../config/general-config/">General config</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../config/inject-config/">Configuration injection</a>
</li>
</ul>
<p class="caption"><span class="caption-text">Service Capability Open</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../edge/open-service/">Intruductions</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../edge/by-servicecomb-sdk/">Using Edge Service</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../edge/nginx/">Using confd and Nginx as edge services</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../edge/zuul/">Use zuul as edge services</a>
</li>
</ul>
<p class="caption"><span class="caption-text">Service Packing and Running</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../packaging/standalone/">Standalone mode</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../packaging/web-container/">WEB container mode</a>
</li>
</ul>
<p class="caption"><span class="caption-text">Micro Service Security</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../security/tls/">Using TLS</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../security/rsa/">Using RSA certification</a>
</li>
</ul>
<p class="caption"><span class="caption-text">Using java chassis in Spring Boot</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../using-java-chassis-in-spring-boot/using-java-chassis-in-spring-boot/">Intruductions</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../using-java-chassis-in-spring-boot/components-for-spring-boot/">spring boot starter for java-chassis</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../using-java-chassis-in-spring-boot/java-application/">JAVA application development</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../using-java-chassis-in-spring-boot/web-application/">Web development method development</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../using-java-chassis-in-spring-boot/diff-between-java-web/">The difference between JAVA application method and Web development method</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../using-java-chassis-in-spring-boot/diff-spring-mvc/">The difference in Spring MVC mode</a>
</li>
</ul>
<p class="caption"><span class="caption-text">Handlers reference</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../references-handlers/intruduction/">Intruductions</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../references-handlers/loadbalance/">Load Balancing</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../references-handlers/publickey/">Public key authentication</a>
</li>
</ul>
<p class="caption"><span class="caption-text">FAQ</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../question-and-answer/question_answer/">Q & A</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../question-and-answer/faq/">FAQ</a>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../question-and-answer/interface-compatibility/">Micro Service Interface Compatibility FAQ</a>
</li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="Mobile navigation menu">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../..">ServiceComb Java Chassis Developers Guide</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content"><div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../.." class="icon icon-home" alt="Docs"></a> »</li>
<li>Development Service Provider »</li>
<li>Develop with JAX-RS</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div class="section" itemprop="articleBody">
<h1 id="develop-microservice-with-jax-rs">Develop Microservice with JAX-RS</h1>
<h2 id="concept-description">Concept Description</h2>
<p>ServiceComb supports developers in developing services in JAX-RS mode by using JAX-RS.</p>
<h2 id="development-example">Development Example</h2>
<ul>
<li><strong>Step 1</strong> Import dependencies into your maven project:</li>
</ul>
<p><code>xml
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.apache.servicecomb</groupId>
<artifactId>java-chassis-dependencies</artifactId>
<version>1.0.0-m1</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<!--transport can optional import through endpoint setting in microservice.yaml, we import both rest and highway as example-->
<dependency>
<groupId>org.apache.servicecomb</groupId>
<artifactId>transport-rest-vertx</artifactId>
</dependency>
<dependency>
<groupId>org.apache.servicecomb</groupId>
<artifactId>transport-highway</artifactId>
</dependency>
<dependency>
<groupId>org.apache.servicecomb</groupId>
<artifactId>provider-jaxrs</artifactId>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-log4j12</artifactId>
</dependency>
</dependencies></code></p>
<ul>
<li><strong>Step 2</strong> Implement the service. JAX-RS is used to describe the development of service code. The implementation of the Hello service is as follows:</li>
</ul>
<p>```java
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;
import org.apache.servicecomb.samples.common.schema.models.Person;</p>
<p>@Path("/jaxrshello")
@Produces(MediaType.APPLICATION_JSON)
public class JaxrsHelloImpl {
@Path("/sayhi")
@POST
public String sayHi(String name) {
return "Hello " + name;
}</p>
<pre><code> @Path("/sayhello")
@POST
public String sayHello(Person person) {
return "Hello person " + person.getName();
}
</code></pre>
<p>}
```</p>
<p><strong>Note: PLEASE MAKE SURE TO MARK @Path ON YOUR PRODUCER(JaxrsHelloImpl), OR THE PATH AND METHOD OF PUBLISHED WILL BE INCORRECT!</strong></p>
<p>In this sample the Path of sayHi is <code>/jaxrshello/sayhi</code>, and the Path of sayHello is <code>/jaxrshello/sayhello</code>, if you wish them <code>/sayhi</code> and <code>/sayhello</code>, please change the setting of <code>@Path</code> on the JaxrsHelloImpl to <code>@Path("/")</code>.</p>
<ul>
<li><strong>Step 3</strong> Release the service. Add <code>@RestSchema</code> as the annotation of the service implementation class and specify schemaID, which indicates that the implementation is released as a schema of the current microservice. The code is as follows:</li>
</ul>
<p><code>java
import org.apache.servicecomb.provider.rest.common.RestSchema;
// other code omitted
@RestSchema(schemaId = "jaxrsHello")
public class JaxrsHelloImpl implements Hello {
// other code omitted
}</code></p>
<p>Create the jaxrsHello.bean.xml file in the resources/META-INF/spring directory and configure base-package that performs scanning. The content of the file is as follows:</p>
<p>```xml
<?xml version="1.0" encoding="UTF-8"?></p>
<p><beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:p="http://www.springframework.org/schema/p" xmlns:util="http://www.springframework.org/schema/util"
xmlns:cse="http://www.huawei.com/schema/paas/cse/rpc"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/beans classpath:org/springframework/beans/factory/xml/spring-beans-3.0.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd http://www.huawei.com/schema/paas/cse/rpc classpath:META-INF/spring/spring-paas-cse-rpc.xsd"></p>
<pre><code> <context:component-scan base-package="org.apache.servicecomb.samples.jaxrs.provider"/>
</code></pre>
<p></beans>
```</p>
<ul>
<li><strong>Step 4</strong> Add service definition file:</li>
</ul>
<p>Add <a href="http://servicecomb.incubator.apache.org/cn/users/service-definition/">microservice.yaml</a> file into resources folder of your project.</p>
<ul>
<li><strong>Step 5</strong> Add Main class:</li>
</ul>
<p>```java
import org.apache.servicecomb.foundation.common.utils.BeanUtils;
import org.apache.servicecomb.foundation.common.utils.Log4jUtils;</p>
<p>public class Application {
public static void main(String[] args) throws Exception {
//initializing log, loading bean(including its parameters), and registering service, more detail can be found here : http://servicecomb.incubator.apache.org/users/application-boot-process/
Log4jUtils.init();
BeanUtils.init();
}
}
```</p>
<h2 id="involved-apis">Involved APIs</h2>
<p>Currently, the JAX-RS development mode supports the following annotation. For details about how to use JAX-RS, see <a href="https://jax-rs-spec.java.net/nonav/2.0-rev-a/apidocs/index.html">JAX-RS official documentation</a>。</p>
<table>
<thead>
<tr>
<th align="left">Remarks</th>
<th align="left">Location</th>
<th align="left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">javax.ws.rs.Path</td>
<td align="left">schema/operation</td>
<td align="left">URL path</td>
</tr>
<tr>
<td align="left">javax.ws.rs.Produces</td>
<td align="left">schema/operation</td>
<td align="left">Coding/decoding capability supported by the method</td>
</tr>
<tr>
<td align="left">javax.ws.rs.DELETE</td>
<td align="left">operation</td>
<td align="left">http method</td>
</tr>
<tr>
<td align="left">javax.ws.rs.GET</td>
<td align="left">operation</td>
<td align="left">http method</td>
</tr>
<tr>
<td align="left">javax.ws.rs.POST</td>
<td align="left">operation</td>
<td align="left">http method</td>
</tr>
<tr>
<td align="left">javax.ws.rs.PUT</td>
<td align="left">operation</td>
<td align="left">http method</td>
</tr>
<tr>
<td align="left">javax.ws.rs.QueryParam</td>
<td align="left">parameter</td>
<td align="left">Obtain parameters from query string</td>
</tr>
<tr>
<td align="left">javax.ws.rs.PathParam</td>
<td align="left">parameter</td>
<td align="left">Obtain parameters from path, This parameter must be defined in path.</td>
</tr>
<tr>
<td align="left">javax.ws.rs.HeaderParam</td>
<td align="left">parameter</td>
<td align="left">Obtain parameters from header.</td>
</tr>
<tr>
<td align="left">javax.ws.rs.CookieParam</td>
<td align="left">parameter</td>
<td align="left">Obtain parameters from cookie.</td>
</tr>
</tbody>
</table>
<blockquote>
<p><strong>NOTE</strong>：
- When the method parameter has no annotation and is not an HttpServletRequest parameter, the parameter is of the body type by default. One method supports a maximum of one body-typed parameter.
- You are advised to explicitly define the value of the parameter. Otherwise, the parameter name in the API definition is used, such as <code>@QueryParam\("name"\) String name</code> String name instead of <code>@QueryParam String name</code>.</p>
</blockquote>
</div>
</div><footer>
<div class="rst-footer-buttons" role="navigation" aria-label="Footer Navigation">
<a href="../springmvc/" class="btn btn-neutral float-left" title="Develop with SpringMVC"><span class="icon icon-circle-arrow-left"></span> Previous</a>
<a href="../transparent-rpc/" class="btn btn-neutral float-right" title="Develop with Transparent RPC">Next <span class="icon icon-circle-arrow-right"></span></a>
</div>
<hr/>
<div role="contentinfo">
<!-- Copyright etc -->
</div>
Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<div class="rst-versions" role="note" aria-label="Versions">
<span class="rst-current-version" data-toggle="rst-current-version">
<span><a href="../springmvc/" style="color: #fcfcfc">« Previous</a></span>
<span><a href="../transparent-rpc/" style="color: #fcfcfc">Next »</a></span>
</span>
</div>
<script>var base_url = '../..';</script>
<script src="../../js/theme_extra.js" defer></script>
<script src="../../js/theme.js" defer></script>
<script src="../../search/main.js" defer></script>
<script defer>
window.onload = function () {
SphinxRtdTheme.Navigation.enable(true);
};
</script>
</body>
</html>