Support for ResourceFilter

[amecky]

ResourceFilter are a common way of extracting common functionality. One basic example is using a ResourceFilter to do authorization and authentication. Unfortunately there is no way to include these ResourceFilters in the generated documentation. The only way at the moment is to mention these ResourceFilters in the javadoc. But there is of course no linking and it is only plain text therefore it is not really obvious to the user. All these ResourceFilter implement the JAX RS interface ContainerRequestFilter. The next step would be to support the name binding of ResourceFilters. This is done using an annotation. But I guess this is more difficult to support. But a first workaround could be to use @link in the javadocs.

[stoicflame]

What would a page that describes a resource filter look like?

[amecky]

The ResourceFilters should be listed on the frontpage like Resources for example. In order to build the link between the resource and the filters a new annotation could be used like this:

@GET
@PATH("path")
@Filters(SecurityFilter.class,MDCFilter.class)
public Response getStuff() {
.....
}

The Filters itself are a little bit tricky because you cannot extract on which kind of information they might work. They could extract information from the HTTP header or query parameter. Therefore new annotations would be nice here as well. Here is an example:

/**
 * Some basic info here
*/
public class PagingFilter implements ContainerRequestFilter {
        @FilterHeaderParameter("pageSize","Extracts the pageSize from the header")
        @FilterQueryParameter("pageIndex","Optional query parameter to define the start page")
    @Override
    public void filter(ContainerRequestContext requestContext) throws IOException {
          ........
       }
}

This would be a good starting point. I know that it is difficult to extract the correct information as there is no real direct link between the resource and the filters.

[stoicflame]

So you're thinking "filter" page would contain a list of headers and parameters that are applicable to any requests to which the filter applies.

Why not just add the headers and parameters to the resources themselves e.g. using Enunciate-Specific-Annotations?

[amecky]

Maybe my example was a bit misleading. These header or query parameters and not part of the actual method in the Resource. If you look at my example Resource then you see that the signature is actually empty. I am aware that there are actually ResponseHeader and other already present. But it is too cumbersone to list all parameters like this that are handled by filter on each and every method in the resources.

For example in one of our services we are using 3 ResourceFilters which in total extracts data from 4 query parameters and 3 header parameters. Putting these 7 annotations in front of each method in the resource would blow up the code.

A better way would be to be able to link to ResourceFilters here.

[stoicflame]

I understand the request.

It seems like an unconventional way to process parameters. I suppose I can understand filters that take certain headers as parameters (e.g. authorization filter), but how does e.g. PagingFilter pass pageSize and pageIndex down to the resource? Wouldn't @BeanParam be a better fit for parameter sets that need to be shared across resources?

Note also that there's already a standard way of using annotations apply filters using @NameBinding, so we hopefully wouldn't have to come up with some new annotation like @Filters.

[stoicflame]

I started looking into this.

It's a reasonable request, but it's quite a bit of work, so I'm pulling it off the release plan for now.

If anybody is willing to sponsor the work, reach out to me and I'd be happy to pick it up.