![[Contents]](FIGURE/CONTENT.GIF)
uCosminexus Application Server, Web Service Development Guide
![[Glossary]](FIGURE/GLOSS.GIF)
![[Index]](FIGURE/INDEX.GIF)
![[Back]](FIGURE/FRONT.GIF)
![[Next]](FIGURE/AFTER.GIF)
This subsection describes the Injectable annotations supported by the JAX-RS engine.
You can use only one injectable annotation for a parameter, a field, or a bean property. If you specify multiple annotations for a parameter, a field, or a bean property, only the annotation on the extreme right side is enabled. If the annotation on the extreme right does not comply with the JAX-RS 1.1 specifications, all other annotations are ignored and injection is not performed.
When using an injection purpose annotation for a bean property, annotate at the method level for the setter method.
In a root resource class or an exception mapping provider, do not reference or change the field annotated by an injectable annotation from the constructor and the setter method of the bean property.
The injection to a constructor, a field, or a bean property is concurrently performed when the JAX-RS engine instantiates the root resource class and the exception mapping provider. Therefore, if you reference the field annotated by an injectable annotation from the constructor and the setter method of bean property, the value acquired is undetermined. Also, if you change the field annotated by an injectiable annotation, either the injection to the field fails, or even if the injection succeeds, the value is undetermined.
Use the javax.ws.rs.HeaderParam annotation to acquire the value of an HTTP header. As the annotation value, specify the HTTP header name included in the HTTP request.
The following table lists the items for which you can specify the javax.ws.rs.HeaderParam annotation:
Table 24-3 Items for which you can specify the javax.ws.rs.HeaderParam annotation
| Web resource or provider | Parameter of constructor | Field | bean property | Parameter of method |
|---|---|---|---|---|
| Root resource class | Y | Y | Y | Y |
| Sub-resource class | N | N | N | Y |
| Exception mapping provider | N | N | N | -- |
For details on the Web resources or providers, see the respective sections in 17. Web Resources and Providers.
Use the javax.ws.rs.CookieParam annotation to acquire the value of HTTP Cookie. As the annotation value, specify the Cookie name included in the HTTP request.
The following table lists the items for which you can specify the javax.ws.rs.CookieParam annotation:
Table 24-4 Items for which you can specify the javax.ws.rs.CookieParam annotation
| Web resource or provider | Parameter of constructor | Field | bean property | Parameter of method |
|---|---|---|---|---|
| Application subclass | N | N | N | -- |
| Root resource class | Y | Y | Y | Y |
| Sub-resource class | N | N | N | Y |
| Entity provider | N | N | N | -- |
| Context provider | N | N | N | -- |
| Exception mapping provider | N | N | N | -- |
For details on the Web resources or providers, see the respective sections in 17. Web Resources and Providers.
Use the javax.ws.rs.MatrixParam annotation to acquire the value of a URI matrix parameter. As the annotation value, specify the matrix parameter name included in the HTTP request.
The following table lists the items for which you can specify the javax.ws.rs.MatrixParam annotation:
Table 24-5 Items for which you can specify the javax.ws.rs.Matrix parameter annotation
| Web resource or provider | Parameter of constructor | Field | bean property | Parameter of method |
|---|---|---|---|---|
| Application sub-class | N | N | N | -- |
| Root resource class | Y | Y | Y | Y |
| Sub-resource class | N | N | N | Y |
| Entity provider | N | N | N | -- |
| Context provider | N | N | N | -- |
| Exception mapping provider | N | N | N | -- |
For details on the Web resources or providers, see the respective sections in 17. Web Resources and Providers.
Use the javax.ws.rs.QueryParam annotation to acquire the value of a URI query parameter. As the annotation value, specify the query parameter name included in the HTTP request.
The following table lists the items for which you can specify the javax.ws.rs.QueryParam annotation:
Table 24-6 Items for which you can specify the javax.ws.rs.QueryParam annotation
| Web resource or provider | Parameter of constructor | Field | bean property | Parameter of method |
|---|---|---|---|---|
| Application sub-class | N | N | N | -- |
| Root resource class | Y | Y | Y | Y |
| Sub-resource class | N | N | N | Y |
| Entity provider | N | N | N | -- |
| Context provider | N | N | N | -- |
| Exception mapping provider | N | N | N | -- |
For details on the Web resources or providers, see the respective sections in 17. Web Resources and Providers.
Use the javax.ws.rs.PathParam annotation to acquire the value of a URI path. Specify a template parameter as the annotation value.
The following table lists the items for which you can specify the javax.ws.rs.PathParam annotation:
Table 24-7 Items for which you can specify the javax.ws.rs.PathParam annotation
| Web resource or provider | Parameter of constructor | Field | bean property | Parameter of method |
|---|---|---|---|---|
| Application sub-class | N | N | N | -- |
| Root resource class | Y | Y | Y | Y |
| Sub-resource class | N | N | N | Y |
| Entity provider | N | N | N | -- |
| Context provider | N | N | N | -- |
| Exception mapping provider | N | N | N | -- |
For details on the Web resources or providers, see the respective sections in 17. Web Resources and Providers.
Use the javax.ws.rs.FormParam annotation to acquire the value of the form parameter included in the entity body of the HTTP request. Specify the form parameter name as the annotation value.
The following table lists the items for which you can specify the javax.ws.rs.FormParam annotation:
Table 24-8 Items for which you can specify the javax.ws.rs.FormParam annotation
| Web resource or provider | Parameter of constructor | Field | bean property | Parameter of method |
|---|---|---|---|---|
| Root resource class | Y | Y | Y | Y |
| Sub-resource class | N | N | N | Y |
| Exception mapping provider | N | N | N | -- |
For details on the Web resources or providers, see the respective sections in 17. Web Resources and Providers.
The default upper limit of the count of the form parameters that are included in the entity body is 10000. If the number of parameters specified in a request exceeds a specific value, an error (KDJJ10042-E) occurs and the javax.ws.rs.WebApplicationException exception that has 413 set as the HTTP status code is thrown. The javax.ws.rs.WebApplicationException exception can be handled by an exception mapping provider. Change the parameter count as and when required by editing the webserver.connector.limit.max_parameter_count property in the User Property file (usrconf.properties) of the J2EE server. For details on the User Property file of the J2EE server, see 2.4 usrconf.properties (User Property file of the J2EE server) in the uCosminexus Application Server Definition Reference Guide.
Use the javax.ws.rs.Context annotation to inject the value of a context. The following table lists the items for which you can specify the javax.ws.rs.Context annotation:
Table 24-9 Items for which you can specify the javax.ws.rs.Context annotation (1)
| Web resource or provider | Context Application type | Context UriInfo type | Context HttpHeaders type | Context Request type | Context SecurityContext type | Context Providers type | |
|---|---|---|---|---|---|---|---|
| Root resource class | Parameter of constructor | N | Y | Y | Y | Y | Y |
| Field | N | Y | Y | Y | Y | Y | |
| bean property | N | Y | Y | Y | Y | Y | |
| Parameter of method | N | Y | Y | Y | Y | Y | |
| Sub-resource class | Parameter of constructor | N | N | N | N | N | N |
| Field | N | N | N | N | N | N | |
| bean property | N | N | N | N | N | N | |
| Parameter of method | N | Y | Y | Y | Y | Y | |
| Exception mapping provider | Parameter of constructor | N | N | N | N | N | Y |
| Field | N | Y | Y | Y | Y | Y | |
| bean property | N | Y | Y | Y | Y | Y | |
Table 24-10 Items for which you can specify the javax.ws.rs.Context annotation (2)
| Web resource or provider | Context HttpServletRequest type | HttpServletResponse type | ServletContext type | ServletConfig type | |
|---|---|---|---|---|---|
| Root resource class | Parameter of constructor | Y# | Y | Y | Y |
| Field | Y# | Y | Y | Y | |
| bean property | Y# | Y | Y | Y | |
| Parameter of method | Y# | Y | Y | Y | |
| Sub-resource class | Parameter of constructor | N | N | N | N |
| Field | N | N | N | N | |
| bean property | N | N | N | N | |
| Parameter of method | Y# | Y | Y | Y | |
| Exception mapping provider | Parameter of constructor | Y# | Y | Y | Y |
| Field | Y# | Y | Y | Y | |
| bean property | Y# | Y | Y | Y | |
You can use the javax.ws.rs.DefaultValue annotation in combination with the following annotations. When you use the javax.ws.rs.DefaultValue annotation, you can specify a default value if a value to be injected in the parameter annotated by the respective annotations does not exist in the HTTP request.
For instance, if a query or a matrix parameter corresponding to an instance does not exist in a URI request, or if a target form parameter does not exist in the entity body of a request, then the default value that you specified in the DefaultValue annotation is used.
Use the javax.ws.rs.Encoded annotation to disable the automatic URL decoding of a URL encoded value. The URL encoded values of the parameters, fields, and bean properties annotated by the following injection annotations are automatically decoded:
You can use the javax.ws.rs.Encoded annotation in:
When using at the parameter level, field level, or property level, use the javax.ws.rs.Encoded annotation in combination with the previously described injectable annotations (javax.ws.rs.MatrixParam, javax.ws.rs.QueryParam, javax.ws.rs.PathParam).
When using the javax.ws.rs.Encoded annotation at the class level, you can disable the automatic URL decoding of all the URL encoded values for all the parameters, fields, and bean properties of the concerned class.
When using the javax.ws.rs.Encoded annotation at the constructor level, you can disable the automatic URL decoding of the URL encoded values for all the parameters of the concerned constructor.
When using the javax.ws.rs.Encoded annotation at the method level, you can disable the automatic URL decoding of the URL encoded values for all the parameters of the respective resource methods, sub-resource methods, or sub-resource locators.
All Rights Reserved. Copyright (C) 2013, Hitachi, Ltd.