Jersey.docx
- 文档编号:5616891
- 上传时间:2022-12-29
- 格式:DOCX
- 页数:15
- 大小:2.48MB
Jersey.docx
《Jersey.docx》由会员分享,可在线阅读,更多相关《Jersey.docx(15页珍藏版)》请在冰豆网上搜索。
Jersey
目录
Chapter 3. JAX-RSApplication,ResourcesandSub-Resources3
3.1. RootResourceClasses3
3.1.2. @GET,@PUT,@POST,@DELETE,...(HTTPMethods)4
3.1.3. @Produces5
3.1.4. @Consumes6
3.2. ParameterAnnotations(@*Param)6
3.3. Sub-resources9
3.4. Life-cycleofRootResourceClasses12
3.5. RulesofInjection12
3.6. Useof@Context14
3.7. Programmaticresourcemodel15
Chapter 3. JAX-RSApplication,ResourcesandSub-Resources
TableofContents
3.1.RootResourceClasses
3.1.1.@Path
3.1.2.@GET,@PUT,@POST,@DELETE,...(HTTPMethods)
3.1.3.@Produces
3.1.4.@Consumes
3.2.ParameterAnnotations(@*Param)
3.3.Sub-resources
3.4.Life-cycleofRootResourceClasses
3.5.RulesofInjection
3.6.Useof@Context
3.7.Programmaticresourcemodel
本章是JAX-RS核心概念—resources和sub-resources的概览。
3.1. RootResourceClasses
根资源类是用@Path注解的POJOs,至少含有一个@Path注解的,或者资源方法指示符(@GET,@PUT,@POST,@DELETE)注解的方法。
由资源方法指示符注解的方法称为资源方法。
本章将说明怎样使用Jersey去注解一个Java对象,以创建RESTfulwebservice。
Example3.1是使用JAX-RS注解的一个非常简单的根资源例子。
该段代码是随Jersey一起发布的。
Example 3.1. Simplehelloworldrootresourceclass
接下来就看一下在这个例子中使用倒的部分annotations。
3.1.1@Path
@Path注解的值是一个相对的URI路径。
在上例中,Java类对应的URI路径就是/helloworld。
这是@Path注解最简单的使用。
JAX-RS更有用的地方在于,你可以在URIs中嵌入变量。
URI路径模板是指在URI语法中嵌入变量的URIs。
在运行时,变量会被实际值取代,这样就有一个资源来响应这个具体的请求。
变量是在花括号中的。
例如,
@Path(“/users/{username}”)
要得到username变量的值,可以在request方法的方法参数中添加@PathParam,例如:
Example 3.2. SpecifyingURIpathparameter
如果username必须是只能包含小写和大写数字和字符,则可以声明一个正则表达式,这会覆盖默认的正则表达式,“[^/]+”,例如:
@Path("users/{username:
[a-zA-Z][a-zA-Z_0-9]*}")
如果用户输入的username不匹配,则报404错误(NotFound)。
@Path的值以‘/’开头,或者不以‘/’开头,结果是一样的。
同样,默认情况下,@Path的值以‘/’结尾或没有‘/’,结果也是一样的。
因此以‘/’结尾或者没有‘/’的URLs都会被匹配。
3.1.2. @GET,@PUT,@POST,@DELETE,...(HTTPMethods)
@GET,@PUT,@POST,@DELETE和@HEAD,都是JAX-RS定义的资源方法指示符注解,以响应类似名字的HTTP方法。
在上例中,被注解的Java方法会处理HTTPGET请求。
资源的行为是由资源的响应的HTTP方法决定的。
下例是一个PUT方法的示例,用来创建或更新storagecontainer:
Example 3.3. PUTmethod
默认的,JAX-RS运行时会自动支持HEAD和OPTIONS方法,如果没有显式实现。
对于HEAD,运行时会调用GET方法(如果存在)并忽略响应实体(如果设置了)。
OPTIONS方法返回的响应由在header中定义的‘Accept’的请求media类型决定。
因此,OPTIONS方法返回在’Allow’中支持的资源方法列表,或者返回一个WADL文档。
具体请参考wadl章节。
3.1.3. @Produces
@Produces注解用来指定资源产生的representations的MIMEmedia类型,然后发送到客户端。
在本例中,Java方法生成MIMEmedia类型为”text/plain”的representations。
@Produces既可以在Class上,也可以在method上。
如下例:
Example 3.4. SpecifyingoutputMIMEtype
doGetAsPlainText方法默认使用定义在class上的@Produce注解的MIME类型。
doGetAsHtml方法的@Produces注解覆盖类级别的@Produces设置,指定该方法生成HTML,而不是普通文本。
如果资源类可以生成多个MIMEmediatype,则资源方法选择最接近客户端声明的mediatype。
在HTTP请求的Accept头中指定更多的细节将声明哪种类型是最可接受的。
例如,如果Accept头中是”Accept:
text/plain”,那么doGetAsPlainTex方法会被调用。
如果Accept头中是”Accept:
text/plain;q=0.9,text/html”,则声明客户端可以接受”text/plain”和”text/html”这两种mediatypes,但是后者更优先,因此doGetAsHtml方法会被调用。
在@Produces声明中声明多个mediatype,如下例:
Example 3.5. UsingmultipleoutputMIMEtypes
如果声明可接受的mediatype为 "application/xml"and"application/json",则调用doGetAsXmlOrJso方法。
如果两个都可以接受,会选择前者,因为它是第一个触发的。
可选地,服务器可以为单个mediatype指定质量因子。
当客户端对多个mediatype都接受的时候,会判断该因子。
例如:
Example 3.6. Server-sidecontentnegotiation
上例zhon个, ifclientacceptsboth"application/xml"and"application/json"(equally),则服务器zon改善发送"application/json",因为"application/xml"的因子小些。
上例中,为了更清晰,显式参考某个MIMEmediatype。
也可以参考常量值,这样会降低印刷错误,seetheconstantfieldvaluesof MediaType.
3.1.4. @Consumes
@Consumes注解用来指定可以被资源消费的representations的MIMEmediatype。
上例可以修改下,来设置点击的消息,如下例:
Example 3.7. SpecifyinginputMIMEtype
本例中,Java方法将消费MIMEmediatype为“text/plain”的representations。
注意:
资源方法返回void。
意即无representation被返回,而是返回一个204的状态码(NoContent)响应给客户端。
@Consumes可以在class和method级别使用,也可以在同一个@Consumes声明中声明多个mediatype。
3.2. ParameterAnnotations(@*Param)
资源方法的参数可以用基于参数的注解来标注,以提取request中的信息。
当请求的URL与@Path中声明的路径向匹配时,@PathParam用于从URL的路径组件中提取路径参数。
@QueryParam用于从请求URL的Query组件中提取query参数。
如:
Example 3.8. Queryparameters
如果query参数存在,则提取并解析为声明的数据类型,然后分配给对应的method的参数;如果不存在,则使用默认值。
如果参数类型与method中的参数类型不匹配,会返回一个HTTP404(NotFound)的响应。
也可以使用自定义的Java类型,如下例:
Example 3.9. CustomJavatypeforconsumingrequestparameters
Important:
总之,方法参数的Java类型可以是以下几种:
1.基本类型
2.有一个接受单一字符串参数的构造函数
3.有一个叫valueOf或者fromString的静态方法,接受一个单一的字符串参数(例如,Integer.valueOf(String)和java.util.UUID.fromString(String));
4.有一个JAX-RS扩展SPIjavax.ws.rs.ext.ParamConverterProvider的注册实现,该类返回一个javax.ws.rs.ext.ParamConverter实例,类似于”fromstring”,可以转换为某type。
Or
5.List
结果结合只读。
有时,对于同一个参数,可能有多个值,这时5)可以用来得到所有的值。
如果@DefaultValue不是和@QueryParam一起使用的,并且query参数不存在,那么对于List,Set或SortedSet来说,其值就是一个空的集合;对于其他对象是null;对于基本类型是java定义的默认值。
@PathParam和其他的基于参数的注解,@MatrixParam,@HeaderParam,@CookieParam,@FormParam遵循和@QueryParam一样的规则。
@MatrixParam从URLpathsegments中提取信息。
@HeaderParam从HTTPheaders中提取信息。
@CookieParam从与HTTPheaders相关的cookie中提取信息。
@FormParam稍微有点不同,因为它从MIMEmediatype是“application/x-www-form-urlencoded”的请求representation中提取信息,遵从HTML表单指定的编码。
该参数用来从HTML表单提交中提取信息。
如下例:
Example 3.10. ProcessingPOSTedHTMLform
如果想要得到一个参数名和值的map,对于query和path参数,可以通过以下方式:
Example 3.11. ObtaininggeneralmapofURIpathand/orqueryparameters
对于header和cookie参数则如下:
Example 3.12. Obtaininggeneralmapofheaderparameters
总之,@Context可以用来获得与request或response相关的上下文Javatypes。
因为表单参数(不同于其它)是消息体的一部分,可以如下:
Example 3.13. Obtaininggeneralmapofformparameters
而不必使用@Context注解。
另一种注入类型是@BeanParam,它可以将上述参数注入到一个singlebean中。
用@BeanParam标注的bean包含任意字段;
如果这些字段在资源类中,则请求的值会根据注解进行匹配,进行初始化。
(appropriate *param annotation(like @PathParam)willbeinitializedwithcorrespondingrequestvaluesinexpectedwayasifthesefieldswereintheresourceclass. )
Theninsteadofinjectingrequestvalueslikepathparamintoaconstructorparametersorclassfieldsthe @BeanParam canbeusedtoinjectsuchabeanintoaresourceorresourcemethod.The @BeanParam isusedthiswaytoaggregatemorerequestparametersintoasinglebean.
Example 3.14. Exampleofthebeanwhichwillbeusedas @BeanParam
Example 3.15. InjectionofMyBeanParamasamethodparameter:
上例展示了把@PathParam,@QueryParam,@MatrixParam和@HeaderParam聚合到一个bean中。
注入到一个bean的规则和上边讲的一致。
@DefaultValue用来为matrix参数matrixParam定义默认值。
同样@Encoded注解也是一样,与在资源方法中直接注入是一样的。
注意:
不能把beanparameter注入到@Singleton的资源类字段中,只能使用方法参数注入。
@BeanParam可以包含所有的参数注入(@PathParam, @QueryParam, @MatrixParam, @HeaderParam, @CookieParam, @FormParam)。
可以把多个bean注入到一个资源或方法参数总,即便它们注入的是相同的请求值。
例如:
Example 3.16. Injectionofmorebeansintooneresourcemethods:
3.3. Sub-resources
@Path用在类上,则这种类被称为rootresourceclasses。
@Path也可以用在rootresourceclasses的方法上。
这使得把一组resources的公共功能归纳到一起成为可能,并重用。
第一种方式:
@Path用在资源方法上,这种方法被称为sub-resourcemethods。
Example 3.17. Sub-resourcemethods
如果请求URL的路径是printers,则没有被@Path标注的资源方法被选中。
如果请求URL是printers/list,那么首先匹配到rootresourceclass,接着匹配到@Path值为list的sub-resourcemethod,也就是方法getListOfPrinters。
因此上例中执行的是URL的层级匹配。
第二种方式:
@Path用在没有被@GET或者@POST标注的方法上,这种方法被称为sub-resourcelocators。
Example 3.18. Sub-resourcelocators
RootresourceclassItemResource有一个sub-resourcelocator方法getItemContentResource,该方法返回一个新的资源类。
如果请求URL的路径是item/content,首先会匹配到rootresource,接着匹配到sub-resourcelocator并执行,然后返回一个ItemContentResource资源类的实例。
Sub-resourcelocators可以使resource类重用。
Amethodcanbeannotatedwiththe @Path annotationwithemptypath whichmeansthatthesubresourcelocatorismatchedforthepathoftheenclosingresource(withoutsub-resourcepath).这句话理解为:
用带有空path(@Path(“/”)or@Path(“”))的@Path注解标注的方法,subresourcelocator会匹配所有以类@path中值开头的URL(没有sub-resourcepath)。
Example 3.19. Sub-resourcelocatorswithemptypath
上例中,sub-resourcelocator方法getItemContentResource会匹配/item/locator,或者甚至是只有/item。
此外,theprocessingofresourceclassesreturnedbysub-resourcelocatorsisperformedatruntimethusitispossibletosupportpolymorphism. Sub-resourcelocator可能根据请求返回不同的子类型(例如根据验证通过的身份的角色,返回不同的子类)。
所以下例是有效的:
Example 3.20. Sub-resourcelocatorsreturningsub-type
注意:
对于sub-resourcelocator方法返回的实例,运行时不会管理其生命周期,也不会执行任何的字段注入到实例上。
这是因为运行时根本不知道实例的生命周期是什么。
如果需要运行时以标准资源来管理sub-resource,就应该返回Class,如下例:
Example 3.21. Sub-resourcelocatorscreatedfromclasses
JAX-RS资源默认是在每个request中管理的,也就是说会为每个请求创建新的资源。
此例中,javax.inject.Singleton注解代表资源被作为singleton来管理,而不是在request中。
Sub-resourcelocator方法返回一个类代表运行时会管理资源实例及其生命周期。
如果方法返回的是实例,singleton注解将不起作用,而是直接使用返回的实例。
Subresourcelocator也可以返回程序生成的资源模型。
See resourcebuildersection forinformationofhowtheprogrammaticresourcemodelisconstructed.Thefollowingexampleshowsverysimpleresourcereturnedfromthesub-resourcelocatormethod.
Example 3.22. Sub-resourcelocatorsreturningresourcemodel
上例和之前例子效果相同。
Resource isaresourcesimpleresourceconstructedfrom ItemContentSingletonResource.Morecomplexprogrammaticresourcecanbereturnedaslongtheyarevalidresources.
3.4. Life-cycleofRootResourceClasses
默认情况下,rootresourceclasses的生命周期是每个request一个。
也就是说每当URI路径匹配到rootresource时,就会创建一个rootresourceclass的实例。
Thismakesforaverynaturalprogrammingmodelwhereconstructorsandfieldscanbeutilized(asintheprevioussectionshowingtheconstructoroftheSparklinesResource class)withoutconcernformultipleconcurrentrequeststothesameresource(不必考虑对同一资源的多个并发请求).
总之这不太可能导致性能问题。
经过这么多年,JVMs的类构造和垃圾回收已经有了很大改进,许多对象创建和销毁,以服务和处理HTTP请求,以及返回HTTP响应。
Singletonrootresourceclasses的实例可以通过Application的实例来声明。
Jersey还支持另外两种声明周期,通过使用Jersey特定的注解。
3.5. RulesofInjection
Previoussectionshavepresentedexamplesofannotatedtypes,mostlyannotatedmethodparametersbutalsoannotatedfieldsofaclass,fortheinjectionofvaluesontothosetypes.
Thissectionpresentstherulesofinjectionofvaluesonannotatedtypes.Injectioncanbeperformedonfields,constructorparameters,resource/sub-resource/sub-resourcelocatormethodparametersandbeansettermethods.Thefollowingpresentsanexampleofallsuchinjectioncases:
Example 3.23. Injection
注入到singletonscope的生命周期的resourceclasses时有一些限制。
这时,类字段或者构造器参数不能被注入与
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- Jersey