JAXRSREST式Web服务API中新增的和值得关注的功能

JAXRS.：REST式Web服务API中新增的和值得关注的功能JAX-RS2.0：REST式Web服务API中新增的和值得关注的功能JohnClinganJavaEE和GlassFish产品经理JAX-RS2.0中的新增功能JAX-RS回顾客户端API通用配置异步处理过滤器/拦截器超媒体支持服务器端内容协商JAX-RS—用于REST式服务的JavaAPI基于POJO的资源类以HTTP为中心的编程模型实体格式独立性容器独立性包括在JavaEE中注解驱动的标准API，用于帮助开发人员使用Java构建REST式

Web服务和客户端JAX-RS示例...@POST@Path("/withdrawal")@Consumes("text/plain")@Produces("application/json")publicMoneywithdraw(@PathParam("card")Stringcard,@QueryParam("pin")Stringpin,Stringamount){returngetMoney(card,pin,amount);}}JAX-RS注解方法注解目的GET@GET读取，可能缓存POST@POST在没有已知ID的情况下更新或创建PUT@PUT在有已知ID的情况下更新或创建DELETE@DELETE删除HEAD@HEAD没有响应的GETOPTIONS@Options支持的方法JAX-RS注解（续）注解目的@PathParam绑定来自URI的值，例如

@PathParam(“id”)@QueryParam绑定查询名称的值/查询值，例如

@QueryParam(“name”)@CookieParam绑定cookie的值，例如

@CookieParam(“JSESSIONID”)@HeaderParam绑定HTTP标头的值，例如

@HeaderParam(“Accept”)@FormParam绑定HTML表单的值，例如

@FormParam(“name”)@MatrixParam绑定矩阵参数的值，例如

@MatrixParam(“name”)JAXRS2.0客户端API客户端APIHTTP客户端库太低级利用JAX-RS1.xAPI中的提供商/概念主要实现引入的专用API动机客户端API//GetinstanceofClientClientclient=ClientBuilder.newClient();//GetaccountbalanceStringbal=client.target("://.../atm/{cardId}/balance").resolveTemplate().queryParam("pin","9876").request("text/plain").get(String.class);客户端API//WithdrawsomemoneyMoneymoney=

client.target("://.../atm/{cardId}/withdrawal").resolveTemplate().queryParam("pin","9876").request("application/json").post(text("50.0"),Money.class);客户端APIInvocationinvocation1=client.target("://.../atm/{cardId}/balance")….request(“text/plain”).buildGet();Invocationinvocation2=client.target("://.../atm/{cardId}/withdraw")….request("application/json").buildPost(text("50.0"));客户端APICollection<Invocation>invocations=

Arrays.asList(inv1,inv2);Collection<Response>responses=Collections.transform(invocations,newF<Invocation,Response>(){publicResponseapply(Invocationinvocation){returninvocation.invoke();}});客户端API//CreateclientandregisterMyProvider1Clientclient=ClientBuilder.newClient();client.register(MyProvider1.class);//Createatmtarget;inheritsMyProvider1WebTargetatm=client.target("://.../atm");//RegisterMyProvider2atm.register(MyProvider2.class);//Createbalancetarget;inheritsMyProvider1,MyProvider2WebTargetbalance=atm.path(”{cardId}/balance");//RegisterMyProvider3balance.register(MyProvider3.class);JAXRS2.0

通用配置通用配置—动机客户端客户端.register(JsonMessageBodyReader.class).register(JsonMessageBodyWriter.class).register(JsonpInterceptor.class).property().property()...通用配置—动机服务器端publicSet<Class<?>>getClasses(){Set<Class<?>>classes=newHashSet<…>();...classes.add(JsonMessageBodyReader.class);classes.add(JsonMessageBodyWriter.class);classes.add(JsonpInterceptor.class);...returnclasses;}}通用配置—解决方案客户端客户端.register(JsonMessageBodyReader.class).register(JsonMessageBodyWriter.class).register(JsonpInterceptor.class).property().property()...JsonFeaturejf=newJsonFeature().enableCallbackQueryParam();client.register(jf);通用配置—解决方案服务器端publicSet<Class<?>>getClasses(){...classes.add(JsonMessageBodyReader.class);classes.add(JsonMessageBodyWriter.class);classes.add(JsonpInterceptor.class);...}publicSet<Class<?>>getClasses(){...classes.add(JsonFeature.class);...}通用配置publicinterfaceConfigurable{ConfigurationgetConfiguration();Configurableproperty(Stringname,Objectvalue);Configurableregister(...);}publicinterfaceConfiguration{Set<Class>getClasses();Map<Class,Integer>getContracts(ClasscomponentClass);Set<Object>getInstances();Map<String,Object>getProperties();ObjectgetProperty(Stringname);Collection<String>getPropertyNames();booleanisEnabled(Featurefeature);booleanisRegistered(Objectcomponent);...}通用配置publicinterfaceFeature{booleanconfigure(FeatureContextcontext);}Feature示例publicvoidJsonFeatureimplementsFeature{publicbooleanconfigure(FeatureContextcontext){context.register(JsonMessageBodyReader.class).register(JsonMessageBodyWriter.class).register(JsonpInterceptor.class).property(CALLBACK_NAME,calbackName).property(USE_QUERY_PARAM,useQueryParam);returntrue;}}动态Feature仅服务器端publicinterfaceDynamicFeature{voidconfigure(ResourceInfori,FeatureContextcontext);}publicinterfaceResourceInfo{MethodgetResourceMethod();Class<?>getResourceClass();}JAXRS2.0

异步处理异步处理服务器API分流I/O容器线程高效的异步事件处理利用Servlet3.x异步支持（如果可用）客户端API异步的请求调用API异步处理@Stateless@Path("/async/longRunning")publicclassMyResource{@GET@AsynchronouspublicvoidlongRunningOp(@SuspendedAsyncResponsear){ar.setTimeoutHandler(newMyTimoutHandler());ar.setTimeout(15,SECONDS);finalStringresult=executeLongRunningOperation();ar.resume(result);}}异步处理：服务器端publicinterfaceAsyncResponse{publicvoidresume(Object/Throwableresponse);publicvoidcancel();publicvoidcancel(int/DateretryAfter);publicbooleanisSuspended();publicbooleanisCancelled();publicbooleanisDone();publicvoidsetTimeout(longtime,TimeUnitunit);publicvoidsetTimeoutHandler(TimeoutHandlerhandler);publicCollection<Class<?>>register(Class<?>callback);publicMap<Class<?>,Collection<Class<?>>>register(Class<?>callback,Class<?>...callbacks);publicCollection<Class<?>>register(Objectcallback);publicMap<Class<?>,Collection<Class<?>>>register(Objectcallback,Object...callbacks);}异步处理：服务器端@Target({ElementType.PARAMETER})@Retention(RetentionPolicy.RUNTIME)@Documentedpublic@interfaceSuspended{}publicinterfaceTimeoutHandler{voidhandleTimeout(AsyncResponseasyncResponse);}异步处理：服务器端publicinterfaceCompletionCallback{publicvoidonComplete(Throwablethrowable);}publicinterfaceConnectionCallback{publicvoidonDisconnect(AsyncResponsedisconnected);}异步处理：客户端WebTargettarget=client.target("://.../balance”)…//StartasynccallandregistercallbackFuture<?>handle=target.request().async().get(newInvocationCallback<String>(){voidcomplete(Stringbalance){…}voidfailed(InvocationExceptione){…}});//Afterwaitingfortoolong…if(!handle.isDone())handle.cancel(true);JAXRS2.0

过滤器/拦截器过滤器和拦截器定制JAX-RS请求/响应处理用例：日志记录、压缩、安全性，等等针对客户端和服务器API而引入替换现有的专用支持动机过滤器和拦截器非包装过滤器链过滤器不直接调用链中的下一个过滤器由JAX-RS运行时管理

每个过滤器决定是继续还是中断链过滤每个传入/传出消息请求

请求ContainerRequestFilter,ClientRequestFilter响应

响应ContainerResponseFilter,ClientResponseFilter服务器端特性@PreMatching、DynamicFeature过滤器和拦截器日志记录过滤器示例publicclassRequestLoggingFilterimplementsContainerRequestFilter{@Overridepublicvoidfilter(ContainerRequestContextrequestContext){log(requestContext);//non-wrapping=>returnswithoutinvokingthenextfilter}...}过滤器和拦截器只有当发生实体处理时才会调用性能提升

包装拦截器链每个拦截器都通过ceed()调用链中的下一个拦截器拦截实体提供者MessageBodyReader

拦截器ReaderInterceptor接口MessageBodyWriter拦截器WriterInterceptor接口过滤器和拦截器Gzip读取器拦截器示例publicclassGzipInterceptorimplementsReaderInterceptor{@OverrideObjectaroundReadFrom(ReaderInterceptorContextctx){InputStreamold=ctx.getInputStream();ctx.setInputStream(newGZIPInputStream(old));//wrapping=>invokesthenextinterceptorObjectentity=ceed();ctx.setInputStream(old);returnentity;}}过滤器和拦截器应用程序请求过滤器过滤器网络传输……响应过滤器过滤器写入器拦截器…MBW…MBR写入器拦截器读取器拦截器读取器拦截器过滤器和拦截器响应应用程序过滤器过滤器网络…响应过滤器过滤器…MBW写入器拦截器写入器拦截器过滤器过滤器…请求请求读取器拦截器…MBR读取器拦截器过滤器过滤器资源匹配@PreMatching绑定和优先级绑定将过滤器和拦截器与资源方法相关联服务器端概念优先级声明在执行链中的相对位置@Priority(intpriority)过滤器和拦截器共有的概念有作用域的绑定全局绑定静态@NameBinding默认@PreMatching动态DynamicFeature无绑定@NameBinding@Target({ElementType.TYPE,ElementType.METHOD})@Retention(value=RetentionPolicy.RUNTIME)public@interfaceLogged{}@Provider@Logged@Priority(USER)publicclassLoggingFilterimplementsContainerRequestFilter,

ContainerResponseFilter{…}绑定@Path("/greet/{name}")@Produces("text/plain")publicclassMyResourceClass{@Logged@GETpublicStringhello(@PathParam("name")Stringname){return"Hello"+name;}}DynamicFeature示例仅服务器端publicvoidSecurityFeatureimplementsDynamicFeature{publicbooleanconfigure(ResourceInfori,FeatureContextcontext){String[]roles=getRolesAllowed(ri);if(roles!=null){context.register(newRolesAllowedFilter(roles));}}...}JAXRS2.0

超媒体支持超媒体支持REST原则标识符和链接HATEOAS（超媒体作为应用程序状态的引擎）链接类型：结构性链接过渡性链接超媒体支持Link:<://.../orders/1/ship>;rel=ship,<://.../orders/1/cancel>;rel=cancel...<orderid="1"><customer>://.../customers/11</customer><address>://.../customers/11/address/1</address><items><item><product>://.../products/111</product><quantity>2</quantity></item><items>...</order>超媒体Link

和LinkBuilder

类RFC5988：Web链接支持ResponseBuilder

和过滤器中的链接过渡性链接（标头）支持手动结构性链接通过Link.JaxbAdapter

和Link.JaxbLink从客户端API中的链接创建资源目标超媒体//ProducerAPI(server-side)Linkself=Link.fromMethod(MyResource.class,”handleGet”).build();Linkupdate=Link.fromMethod(MyResource.class,“handlePost”).rel(”update”).build();...Responseres=Response.ok(order).link("://.../orders/1/ship","ship").links(self,update).build();超媒体Responseorder=client.target(…).request("application/xml").get();//ConsumerAPI(client-side)LinkshipmentLink=order.getLink(“ship”);if(shipmentLink!=null){Responseshipment=client.target(shipmentLink).post(null);…}JAXRS2.0

服务器端内容协商服务器端内容协商GET://.../widgets2Accept:text/*;q=1…Path("widgets2")publicclassWidgetsResource2{@GET@Produces("text/plain","text/html")publicWidgetsgetWidget(){...}}服务器端内容协商GET://.../widgets2Accept:text/*;q=1…Path("widgets2")publicclassWidgetsResource2{@GET@Produces("text/plain;qs=0.5","text/html;qs=0.75")publicWidgetsgetWidget(){...}}JAX-RS2.0总结主要新功能客户端API、过滤器和拦截器、异步资源、超媒体许多微小的API改进和扩展Bean验证、请求/响应、URI生成器、字符串转换器、

@BeanParam、MultivaluedHashMap、GenericType……DI集成、JavaEE安全性、MVC、延迟的高级客户端API其他资源阅读JSR343规范：GlassFish4.0OpenMessageQueue5.0JAX-RS2.0：REST式Web服务API中新增的和值得关注的功能JohnClinganJavaEE和GlassFish产品经理JAX-RS2.0中的新增功能JAX-RS回顾客户端API通用配置异步处理过滤器/拦截器超媒体支持服务器端内容协商JAX-RS—用于REST式服务的JavaAPI基于POJO的资源类以HTTP为中心的编程模型实体格式独立性容器独立性包括在JavaEE中注解驱动的标准API，用于帮助开发人员使用Java构建REST式

Web服务和客户端JAX-RS示例...@POST@Path("/withdrawal")@Consumes("text/plain")@Produces("application/json")publicMoneywithdraw(@PathParam("card")Stringcard,@QueryParam("pin")Stringpin,Stringamount){returngetMoney(card,pin,amount);}}JAX-RS注解方法注解目的GET@GET读取，可能缓存POST@POST在没有已知ID的情况下更新或创建PUT@PUT在有已知ID的情况下更新或创建DELETE@DELETE删除HEAD@HEAD没有响应的GETOPTIONS@Options支持的方法JAX-RS注解（续）注解目的@PathParam绑定来自URI的值，例如

@PathParam(“id”)@QueryParam绑定查询名称的值/查询值，例如

@QueryParam(“name”)@CookieParam绑定cookie的值，例如

@CookieParam(“JSESSIONID”)@HeaderParam绑定HTTP标头的值，例如

@HeaderParam(“Accept”)@FormParam绑定HTML表单的值，例如

@FormParam(“name”)@MatrixParam绑定矩阵参数的值，例如

@MatrixParam(“name”)JAXRS2.0客户端API客户端APIHTTP客户端库太低级利用JAX-RS1.xAPI中的提供商/概念主要实现引入的专用API动机客户端API//GetinstanceofClientClientclient=ClientBuilder.newClient();//GetaccountbalanceStringbal=client.target("://.../atm/{cardId}/balance").resolveTemplate().queryParam("pin","9876").request("text/plain").get(String.class);客户端API//WithdrawsomemoneyMoneymoney=

client.target("://.../atm/{cardId}/withdrawal").resolveTemplate().queryParam("pin","9876").request("application/json").post(text("50.0"),Money.class);客户端APIInvocationinvocation1=client.target("://.../atm/{cardId}/balance")….request(“text/plain”).buildGet();Invocationinvocation2=client.target("://.../atm/{cardId}/withdraw")….request("application/json").buildPost(text("50.0"));客户端APICollection<Invocation>invocations=

Arrays.asList(inv1,inv2);Collection<Response>responses=Collections.transform(invocations,newF<Invocation,Response>(){publicResponseapply(Invocationinvocation){returninvocation.invoke();}});客户端API//CreateclientandregisterMyProvider1Clientclient=ClientBuilder.newClient();client.register(MyProvider1.class);//Createatmtarget;inheritsMyProvider1WebTargetatm=client.target("://.../atm");//RegisterMyProvider2atm.register(MyProvider2.class);//Createbalancetarget;inheritsMyProvider1,MyProvider2WebTargetbalance=atm.path(”{cardId}/balance");//RegisterMyProvider3balance.register(MyProvider3.class);JAXRS2.0

通用配置通用配置—动机客户端客户端.register(JsonMessageBodyReader.class).register(JsonMessageBodyWriter.class).register(JsonpInterceptor.class).property(“”,“callback”).property(“jsonp.callback.queryParam”,“true”)...通用配置—动机服务器端publicclassMyAppextendsjavax.ws.rs.core.Application{publicSet<Class<?>>getClasses(){Set<Class<?>>classes=newHashSet<…>();...classes.add(JsonMessageBodyReader.class);classes.add(JsonMessageBodyWriter.class);classes.add(JsonpInterceptor.class);...returnclasses;}}通用配置—解决方案客户端客户端.register(JsonMessageBodyReader.class).register(JsonMessageBodyWriter.class).register(JsonpInterceptor.class).property(“”,“callback”).property(“jsonp.callback.queryParam”,“true”)...JsonFeaturejf=newJsonFeature().enableCallbackQueryParam();client.register(jf);通用配置—解决方案服务器端publicSet<Class<?>>getClasses(){...classes.add(JsonMessageBodyReader.class);classes.add(JsonMessageBodyWriter.class);classes.add(JsonpInterceptor.class);...}publicSet<Class<?>>getClasses(){...classes.add(JsonFeature.class);...}通用配置publicinterfaceConfigurable{ConfigurationgetConfiguration();Configurableproperty(Stringname,Objectvalue);Configurableregister(...);}publicinterfaceConfiguration{Set<Class>getClasses();Map<Class,Integer>getContracts(ClasscomponentClass);Set<Object>getInstances();Map<String,Object>getProperties();ObjectgetProperty(Stringname);Collection<String>getPropertyNames();booleanisEnabled(Featurefeature);booleanisRegistered(Objectcomponent);...}通用配置publicinterfaceFeature{booleanconfigure(FeatureContextcontext);}Feature示例publicvoidJsonFeatureimplementsFeature{publicbooleanconfigure(FeatureContextcontext){context.register(JsonMessageBodyReader.class).register(JsonMessageBodyWriter.class).register(JsonpInterceptor.class).property(CALLBACK_NAME,calbackName).property(USE_QUERY_PARAM,useQueryParam);returntrue;}}动态Feature仅服务器端publicinterfaceDynamicFeature{voidconfigure(ResourceInfori,FeatureContextcontext);}publicinterfaceResourceInfo{MethodgetResourceMethod();Class<?>getResourceClass();}JAXRS2.0

异步处理异步处理服务器API分流I/O容器线程高效的异步事件处理利用Servlet3.x异步支持（如果可用）客户端API异步的请求调用API异步处理@Stateless@Path("/async/longRunning")publicclassMyResource{@GET@AsynchronouspublicvoidlongRunningOp(@SuspendedAsyncResponsear){ar.setTimeoutHandler(newMyTimoutHandler());ar.setTimeout(15,SECONDS);finalStringresult=executeLongRunningOperation();ar.resume(result);}}异步处理：服务器端publicinterfaceAsyncResponse{publicvoidresume(Object/Throwableresponse);publicvoidcancel();publicvoidcancel(int/DateretryAfter);publicbooleanisSuspended();publicbooleanisCancelled();publicbooleanisDone();publicvoidsetTimeout(longtime,TimeUnitunit);publicvoidsetTimeoutHandler(TimeoutHandlerhandler);publicCollection<Class<?>>register(Class<?>callback);publicMap<Class<?>,Collection<Class<?>>>register(Class<?>callback,Class<?>...callbacks);publicCollection<Class<?>>register(Objectcallback);publicMap<Class<?>,Collection<Class<?>>>register(Objectcallback,Object...callbacks);}异步处理：服务器端@Target({ElementType.PARAMETER})@Retention(RetentionPolicy.RUNTIME)@Documentedpublic@interfaceSuspended{}publicinterfaceTimeoutHandler{voidhandleTimeout(AsyncResponseasyncResponse);}异步处理：服务器端publicinterfaceCompletionCallback{publicvoidonComplete(Throwablethrowable);}publicinterfaceConnectionCallback{publicvoidonDisconnect(AsyncResponsedisconnected);}异步处理：客户端WebTargettarget=client.target("://.../balance”)…//StartasynccallandregistercallbackFuture<?>handle=target.request().async().get(newInvocationCallback<String>(){voidcomplete(Stringbalance){…}voidfailed(InvocationExceptione){…}});//Afterwaitingfortoolong…if(!handle.isDone())handle.cancel(true);JAXRS2.0

过滤器/拦截器过滤器和拦截器定制JAX-RS请求/响应处理用例：日志记录、压缩、安全性，等等针对客户端和服务器API而引入替换现有的专用支持动机过滤器和拦截器非包装过滤器链过滤器不直接调用链中的下一个过滤器由JAX-RS运行时管理

每个过滤器决定是继续还是中断链过滤每个传入/传出消息请求

请求ContainerRequestFilter,ClientRequestFilter响应

响应ContainerResponseFilter,ClientResponseFilter服务器端特性@PreMatching、DynamicFeature过滤器和拦截器日志记录过滤器示例publicclassRequestLoggingFilterimplementsContainerRequestFilter{@Overridepublicvoidfilter(ContainerRequestContextrequestContext){log(requestContext);//non-wrapping=>returnswithoutinvokingthenextfilter}...}过滤器和拦截器只有当发生实体处理时才会调用性能提升

包装拦截器链每个拦截器都通过ceed()调用链中的下一个拦截器拦截实体提供者MessageBodyReader

拦截器ReaderInterceptor接口MessageBodyWriter拦截器WriterInterceptor接口过滤器和拦截器Gzip读取器拦截器示例publicclassGzipInterceptorimplementsReaderInterceptor{@OverrideObjectaroundReadFrom(ReaderInterceptorContextctx){InputStreamold=ctx.getInputStream();ctx.setInputStream(newGZIPInputStream(old));//wrapping=>invokesthenextinterceptorObjectentity=ceed();ctx.setInputStream(old);returnentity;}}过滤器和拦截器应用程序请求过滤器过滤器网络传输……响应过滤器过滤器写入器拦截器…MBW…MBR写入器拦截器读取器拦截器读取器拦截器过滤器和拦截器响应应用程序过滤器过滤器网络…响应过滤器过滤器…MBW写入器拦截器写入器拦截器过滤器过滤器…请求请求读取器拦截器…MBR读取器拦截器过滤器过滤器资源匹配@PreMatching绑定和优先级绑定将过滤器和拦截器与资源方法相关联服务器端概念优先级声明在执行链中的相对位置@Priority(intpriority)过滤器和拦截器共有的概念有作用域的绑定全局绑定静态@NameBinding默认@PreMatching动态DynamicFeature无绑定@NameBinding@Target({ElementType.TYPE,ElementType.METHOD})@Retention(value=RetentionPolicy.RUNTIME)public@interfaceLogged{}@Provider@Logged@Priority(USER)publicclassLoggingFilterimplementsContainerRequestFilter,

ContainerResponseFilter{…}绑定@Path("/greet/{name}")@Produces("text/plain")publicclassMyResourceClass{@Logged