JerseyWord文件下载.docx
《JerseyWord文件下载.docx》由会员分享，可在线阅读，更多相关《JerseyWord文件下载.docx（15页珍藏版）》请在冰豆网上搜索。
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的概览。
RootResourceClasses
根资源类是用@Path注解的POJOs，至少含有一个@Path注解的，或者资源方法指示符（@GET,@PUT,@POST,@DELETE）注解的方法。
由资源方法指示符注解的方法称为资源方法。
本章将说明怎样使用Jersey去注解一个Java对象，以创建RESTfulwebservice。
Example3.1是使用JAX-RS注解的一个非常简单的根资源例子。
该段代码是随Jersey一起发布的。
Example
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
SpecifyingURIpathparameter
如果username必须是只能包含小写和大写数字和字符，则可以声明一个正则表达式，这会覆盖默认的正则表达式，“[^/]+”，例如：
@Path（"
users/{username:
[a-zA-Z][a-zA-Z_0-9]*}"
）
如果用户输入的username不匹配，则报404错误（NotFound）。
@Path的值以‘/’开头，或者不以‘/’开头，结果是一样的。
同样，默认情况下，@Path的值以‘/’结尾或没有‘/’，结果也是一样的。
因此以‘/’结尾或者没有‘/’的URLs都会被匹配。
@GET,@PUT,@POST,@DELETE,...（HTTPMethods）
@GET,@PUT,@POST,@DELETE和@HEAD，都是JAX-RS定义的资源方法指示符注解，以响应类似名字的HTTP方法。
在上例中，被注解的Java方法会处理HTTPGET请求。
资源的行为是由资源的响应的HTTP方法决定的。
下例是一个PUT方法的示例，用来创建或更新storagecontainer：
PUTmethod
默认的，JAX-RS运行时会自动支持HEAD和OPTIONS方法，如果没有显式实现。
对于HEAD，运行时会调用GET方法（如果存在）并忽略响应实体（如果设置了）。
OPTIONS方法返回的响应由在header中定义的‘Accept’的请求media类型决定。
因此，OPTIONS方法返回在’Allow’中支持的资源方法列表，或者返回一个WADL文档。
具体请参考wadl章节。
@Produces
@Produces注解用来指定资源产生的representations的MIMEmedia类型，然后发送到客户端。
在本例中，Java方法生成MIMEmedia类型为”text/plain”的representations。
@Produces既可以在Class上，也可以在method上。
如下例：
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，如下例：
UsingmultipleoutputMIMEtypes
如果声明可接受的mediatype为
"
application/xml"
and"
application/json"
，则调用doGetAsXmlOrJso方法。
如果两个都可以接受，会选择前者，因为它是第一个触发的。
可选地，服务器可以为单个mediatype指定质量因子。
当客户端对多个mediatype都接受的时候，会判断该因子。
例如：
Server-sidecontentnegotiation
上例zhon个，
ifclientacceptsboth"
（equally）,则服务器zon改善发送"
，因为"
的因子小些。
上例中，为了更清晰，显式参考某个MIMEmediatype。
也可以参考常量值，这样会降低印刷错误，seetheconstantfieldvaluesof
MediaType.
@Consumes
@Consumes注解用来指定可以被资源消费的representations的MIMEmediatype。
上例可以修改下，来设置点击的消息，如下例：
SpecifyinginputMIMEtype
本例中，Java方法将消费MIMEmediatype为“text/plain”的representations。
注意：
资源方法返回void。
意即无representation被返回，而是返回一个204的状态码（NoContent）响应给客户端。
@Consumes可以在class和method级别使用，也可以在同一个@Consumes声明中声明多个mediatype。
ParameterAnnotations（@*Param）
资源方法的参数可以用基于参数的注解来标注，以提取request中的信息。
当请求的URL与@Path中声明的路径向匹配时，@PathParam用于从URL的路径组件中提取路径参数。
@QueryParam用于从请求URL的Query组件中提取query参数。
如：
3.8.
Queryparameters
如果query参数存在，则提取并解析为声明的数据类型，然后分配给对应的method的参数；
如果不存在，则使用默认值。
如果参数类型与method中的参数类型不匹配，会返回一个HTTP404（NotFound）的响应。
也可以使用自定义的Java类型，如下例：
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<
T>
Set<
或者SortedSet<
，T满足以上2或者3。
结果结合只读。
有时，对于同一个参数，可能有多个值，这时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表单提交中提取信息。
3.10.
ProcessingPOSTedHTMLform
如果想要得到一个参数名和值的map，对于query和path参数，可以通过以下方式：
3.11.
ObtaininggeneralmapofURIpathand/orqueryparameters
对于header和cookie参数则如下：
3.12.
Obtaininggeneralmapofheaderparameters
总之，@Context可以用来获得与request或response相关的上下文Javatypes。
因为表单参数（不同于其它）是消息体的一部分，可以如下：
3.13.
Obtaininggeneralmapofformparameters
而不必使用@Context注解。
另一种注入类型是@BeanParam，它可以将上述参数注入到一个singlebean中。
用@BeanParam标注的bean包含任意字段；
如果这些字段在资源类中，则请求的值会根据注解进行匹配，进行初始化。
（appropriate
*param
annotation（like
@PathParam）willbeinitializedwithcorrespondingrequestvaluesinexpectedwayasifthesefieldswereintheresourceclass.
Theninsteadofinjectingrequestvalueslikepathparamintoaconstructorparametersorclassfieldsthe
@BeanParam
canbeusedtoinjectsuchabeanintoaresourceorresourcemethod.The
isusedthiswaytoaggregatemorerequestparametersintoasinglebean.
3.14.
Exampleofthebeanwhichwillbeusedas
@BeanParam
3.15.
InjectionofMyBeanParamasamethodparameter:
上例展示了把@PathParam,@QueryParam,@MatrixParam和@HeaderParam聚合到一个bean中。
注入到一个bean的规则和上边讲的一致。
@DefaultValue用来为matrix参数matrixParam定义默认值。
同样@Encoded注解也是一样，与在资源方法中直接注入是一样的。
注意：
不能把beanparameter注入到@Singleton的资源类字段中，只能使用方法参数注入。
@BeanParam可以包含所有的参数注入（@PathParam,
@QueryParam,
@MatrixParam,
@HeaderParam,
@CookieParam,
@FormParam）。
可以把多个bean注入到一个资源或方法参数总，即便它们注入的是相同的请求值。
3.16.
Injectionofmorebeansintooneresourcemethods:
Sub-resources
@Path用在类上，则这种类被称为rootresourceclasses。
@Path也可以用在rootresourceclasses的方法上。
这使得把一组resources的公共功能归纳到一起成为可能，并重用。
第一种方式：
@Path用在资源方法上，这种方法被称为sub-resourcemethods。
3.17.
Sub-resourcemethods
如果请求URL的路径是printers，则没有被@Path标注的资源方法被选中。
如果请求URL是printers/list，那么首先匹配到rootresourceclass，接着匹配到@Path值为list的sub-resourcemethod，也就是方法getListOfPrinters。
因此上例中执行的是URL的层级匹配。
第二种方式：
@Path用在没有被@GET或者@POST标注的方法上，这种方法被称为sub-resourcelocators。
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）。
3.19.
Sub-resourcelocatorswithemptypath
上例中，sub-resourcelocator方法getItemContentResource会匹配/item/locator，或者甚至是只有/item。
此外，theprocessingofresourceclassesreturnedbysub-resourcelocatorsisperformedatruntimethusitispossibletosupportpolymorphism.
Sub-resourcelocator可能根据请求返回不同的子类型（例如根据验证通过的身份的角色，返回不同的子类）。
所以下例是有效的：
3.20.
Sub-resourcelocatorsreturningsub-type
对于sub-resourcelocator方法返回的实例，运行时不会管理其生命周期，也不会执行任何的字段注入到实例上。
这是因为运行时根本不知道实例的生命周期是什么。
如果需要运行时以标准资源来管理sub-resource，就应该返回Class，如下例：
3.21.
Sub-resourcelocatorscreatedfromclasses
JAX-RS资源默认是在每个request中管理的，也就是说会为每个请求创建新的资源。
此例中，javax.inject.Singleton注解代表资源被作为singleton来管理，而不是在request中。
Sub-resourcelocator方法返回一个类代表运行时会管理资源实例及其生命周期。
如果方法返回的是实例，singleton注解将不起作用，而是直接使用返回的实例。
Subresourcelocator也可以返回程序生成的资源模型。
See
resourcebuildersection
forinformationofhowtheprogrammaticresourcemodelisconstructed.Thefollowingexampleshowsverysimpleresourcereturnedfromthesub-resourcelocatormethod.
3.22.
Sub-resourcelocatorsreturningresourcemodel
上例和之前例子效果相同。
Resource
isaresourcesimpleresourceconstructedfrom
ItemContentSingletonResource.Morecomplexprogrammaticresourcecanbereturnedaslongtheyarevalidresources.
Life-cycleofRootResourceClasses
默认情况下，rootresourceclasses的生命周期是每个request一个。
也就是说每当URI路径匹配到rootresource时，就会创建一个rootresourceclass的实例。
Thismakesforaverynaturalprogrammingmodelwhereconstructorsandfieldscanbeutilized（asintheprevioussectionshowingtheconstructoroftheSparklinesResource
class）withoutconcernformultipleconcurrentrequeststothesameresource（不必考虑对同一资源的多个并发请求）.
总之这不太可能导致性能问题。
经过这么多年，JVMs的类构造和垃圾回收已经有了很大改进，许多对象创建和销毁，以服务和处理HTTP请求，以及返回HTTP响应。
Singletonrootresourceclasses的实例可以通过Application的实例来声明。
Jersey还支持另外两种声明周期，通过使用Jersey特定的注解。
RulesofInjection
Previoussectionshavepresentedexamplesofannotatedtypes,mostlyannotatedmethodparametersbutalsoannotatedfieldsofaclass,fortheinjectionofvaluesontothosetypes.
Thissectionpresentstherulesofinjectionofvaluesonannotatedtypes.Injectioncanbeperformedonfields,constructorparameters,resource/sub-resource/sub-resourcelocatormethodparametersandbeansettermethods.Thefollowingpresentsanexampleofallsuchinjectioncases:
3.23.
Injection
注入到singletonscope的生命周期的resourceclasses时有一些限制。
这时，类字段或者构造器参数不能被注入与
升级会员 