{"id":1372,"date":"2012-05-27T15:51:58","date_gmt":"2012-05-27T20:51:58","guid":{"rendered":"http:\/\/unitstep.net\/?p=1372"},"modified":"2012-05-27T15:51:58","modified_gmt":"2012-05-27T20:51:58","slug":"jax-rsjersey-needs-an-required-annotation-for-parameters","status":"publish","type":"post","link":"https:\/\/unitstep.net\/blog\/2012\/05\/27\/jax-rsjersey-needs-an-required-annotation-for-parameters\/","title":{"rendered":"JAX-RS\/Jersey needs an @Required annotation for parameters"},"content":{"rendered":"<p>I&#8217;ve been using Jersey as a JAX-RS implementation for a little while now, and one thing that it could benefit from is the addition of an <code>@Required<\/code> annotation for resource method parameters.  Right now, when parameters are not provided by the client\/request, they are simply set to <code>null<\/code>, creating the need for duplicated null-checking in resource methods. An <code>@Required<\/code> annotation would solve this issue and reduce code duplication.<\/p>\n<p>This isn&#8217;t so much of an issue for <code>@PathParam<\/code> parameters, (since you won&#8217;t even get to the proper resource method without a matching URI) but it does affect <code>@HeaderParam<\/code> and <code>@QueryParam<\/code> (among others) since they aren&#8217;t needed for Jersey to determine which resource method to invoke. By that definition, they are implicitly optional. There should be a way to make them required.<\/p>\n<p>The behaviour of such a required annotation might be as follows:<\/p>\n<ul>\n<li>If the request does not have the parameter, then by default a <code>Response<\/code> with <code>Status.BAD_REQUEST<\/code> (<acronym class=\"uttInitialism\" title=\"HyperText Transfer Protocol\">HTTP<\/acronym> 400) would be returned to the client.<\/li>\n<li>Some way of customizing the <acronym class=\"uttInitialism\" title=\"HyperText Transfer Protocol\">HTTP<\/acronym> response code and message should also be provided.<\/li>\n<\/ul>\n<p>Right now, there&#8217;s not really an elegant way to make something like a <code>@HeaderParam<\/code> required. Here are some solutions I&#8217;ve tried.<br \/>\n<!--more--><\/p>\n<h3>Attempt #1: Parameter classes<\/h3>\n<p><a href=\"http:\/\/codahale.com\/what-makes-jersey-interesting-parameter-classes\/\">Parameter classes<\/a> can be useful for transforming the single input of a parameter into a single output, and also for verifying that the input parameter value is valid.  This can be useful for ensuring that an input parameter can be converted into a specific object, or that it matches a specific format. <\/p>\n<p>As an example, consider the <code>CsvListParam<\/code> class. This class takes a comma-separated list as a parameter, and returns a <code>List&lt;String&gt;<\/code> comprising each entry in the list. It does an additional check to ensure that the input is not blank, according to <a href=\"http:\/\/commons.apache.org\/lang\/api-3.0\/org\/apache\/commons\/lang3\/StringUtils.html#isBlank(java.lang.CharSequence)\">StringUtils.isBlank()<\/a>.  If it is blank, a 400 Bad Request response is returned to the client via the <code>WebApplicationException<\/code> thrown. <\/p>\n<p>Note: The following examples use the <code>AbstractParam<\/code> class from <a href=\"http:\/\/codahale.com\/what-makes-jersey-interesting-parameter-classes\/\">Coda Hale&#8217;s article<\/a>.<\/p>\n<pre><code>public class CsvListParam extends AbstractParam&lt;List&lt;String&gt;&gt; {\r\n\r\n  public CsvListParam(String param) throws WebApplicationException {\r\n    super(param);\r\n  }\r\n\r\n  @Override\r\n  protected List&lt;String&gt; parse(final String suppliedStringValue) throws Throwable {\r\n    if (StringUtils.isBlank(suppliedStringValue)) {\r\n      throw new WebApplicationException(Response.status(Response.Status.BAD_REQUEST).build());\r\n    }\r\n    return Arrays.asList(StringUtils.split(suppliedStringValue, \",\"));\r\n  }\r\n}\r\n\r\n@GET\r\n@Path(\"test\")\r\npublic Response test(@HeaderParam(\"X-TEST\") final CsvListParam param) {\r\n  final String output;\r\n  if (null != param) {\r\n    output = param.getValue().toString();\r\n  } else {\r\n    output = \"param was null\";\r\n  }\r\n  return Response.ok(output).build();\r\n}<\/code><\/pre>\n<p>However, if the parameter is not present at all &#8211; for example, if this was obtained via the <code>@HeaderParam<\/code> annotation and the header was not present &#8211; then the code in the parameter class <strong>will not even be invoked by Jersey<\/strong>. Instead, the value will simply be <code>null<\/code>.  If we require this parameter, it results in nasty if-else null-checking code in each of our resource methods that requires the parameter.<\/p>\n<p>We need something that gets rid of the necessary null-checking in each resource method.<\/p>\n<h3>Attempt #2: Injection Providers<\/h3>\n<p>Coda Hale provides another brilliant example how to use <a href=\"http:\/\/codahale.com\/what-makes-jersey-interesting-injection-providers\/\">Injection Providers<\/a> in Jersey. Basically, with Injection Providers, you can do everything that you could do with Parameter classes, and more.<\/p>\n<p>While Parameter classes are useful only for single-input to single-output mapping, Injection Providers can map multiple inputs to single or multiple outputs. This could allow you to take multiple values in the <acronym class=\"uttInitialism\" title=\"HyperText Transfer Protocol\">HTTP<\/acronym> request and use them populate a single Bean, or use them to form some more complex single value.  It also allows you to do validation, as throwing a <code>WebApplicationException<\/code> from an Injection Provider will cause the contained <code>Response<\/code> or status to be properly returned to the client.<\/p>\n<p>So, we can achieve a similar effect using an Injection Provider. A first attempt at resolving the issue yields the CsvListProvider class:<\/p>\n<pre><code>@Provider\r\npublic class CsvListProvider extends AbstractInjectableProvider&lt;CsvListParam&gt; {\r\n  public CsvListProvider() {\r\n    super(CsvListParam.class);\r\n  }\r\n\r\n  @Override\r\n  public CsvListParam getValue(final HttpContext httpContext) {\r\n    final String suppliedStringValue = httpContext.getRequest().getHeaderValue(\"X-TEST\");\r\n    return new CsvListParam(suppliedStringValue);\r\n  }\r\n}\r\n\r\n@GET\r\n@Path(\"test\")\r\npublic Response test(@Context final CsvListParam param) {\r\n  final String output = param.getValue().toString();\r\n  return Response.ok(output).build();\r\n}<\/code><\/pre>\n<p>However, while this works as expected, it has the unfortunate side effect that the source of the parameter (an <acronym class=\"uttInitialism\" title=\"HyperText Transfer Protocol\">HTTP<\/acronym> header of &#8220;X-TEST&#8221;) has to be specified in the Provider class rather than on the annotation. This isn&#8217;t ideal since we have to create a new Injection Provider class for each <acronym class=\"uttInitialism\" title=\"HyperText Transfer Protocol\">HTTP<\/acronym> header we want to make required.<\/p>\n<h3>Further attempts<\/h3>\n<p>I have been trying to figure out a solution to this. One possible way might be to change the AbstractInjectableProvider to the following declaration:<\/p>\n<pre><code>public abstract class AbstractInjectableProvider&lt;E, A extends Annotation&gt; extends AbstractHttpContextInjectable&lt;E&gt; implements InjectableProvider&lt;A, Type&gt;<\/code><\/pre>\n<p>We could then define a custom annotation type to take the place of <code>A<\/code> instead of always using <code>@Context<\/code>.  However, this doesn&#8217;t work, as we have no way of then obtaining any of the annotation&#8217;s values in the concrete Provider class.  A solution like this would require changes in the core of Jersey to make it work, thus reducing the solution essentially the same as having an <code>@Required<\/code> annotation as proposed above.<\/p>\n<h3>Conclusion<\/h3>\n<p>It seems like we need a proper solution to this via a change in Jersey. Evidently, others have come to the <a href=\"http:\/\/jersey.576304.n2.nabble.com\/Required-parameters-on-a-Resource-td3446928.html\">same conclusion<\/a>, as there are at least <a href=\"http:\/\/java.net\/jira\/browse\/JERSEY-351\">two<\/a> <a href=\"http:\/\/java.net\/jira\/browse\/JERSEY-399\">issues<\/a> open for Jersey related to this.<\/p>","protected":false},"excerpt":{"rendered":"<p>I&#8217;ve been using Jersey as a JAX-RS implementation for a little while now, and one thing that it could benefit from is the addition of an @Required annotation for resource method parameters. Right now, when parameters are not provided by the client\/request, they are simply set to null, creating the need for duplicated null-checking in [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":[],"categories":[208,197,396,395,137,156],"tags":[394],"_links":{"self":[{"href":"https:\/\/unitstep.net\/wp-json\/wp\/v2\/posts\/1372"}],"collection":[{"href":"https:\/\/unitstep.net\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/unitstep.net\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/unitstep.net\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/unitstep.net\/wp-json\/wp\/v2\/comments?post=1372"}],"version-history":[{"count":21,"href":"https:\/\/unitstep.net\/wp-json\/wp\/v2\/posts\/1372\/revisions"}],"predecessor-version":[{"id":1400,"href":"https:\/\/unitstep.net\/wp-json\/wp\/v2\/posts\/1372\/revisions\/1400"}],"wp:attachment":[{"href":"https:\/\/unitstep.net\/wp-json\/wp\/v2\/media?parent=1372"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/unitstep.net\/wp-json\/wp\/v2\/categories?post=1372"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/unitstep.net\/wp-json\/wp\/v2\/tags?post=1372"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}