Chapter 20. Entity Data Filtering

Entity Filtering support in Jersey is provided as an extension module and needs to be mentioned explicitly in your pom.xml file (in case of using Maven):

<dependency>
    <groupId>org.glassfish.jersey.ext</groupId>
    <artifactId>jersey-entity-filtering</artifactId>
    <version>2.38-SNAPSHOT</version>
</dependency>

The entity-filtering extension module provides three Features which you can register into server/client runtime in prior to use Entity Filtering in an application:

If you want to use both entity-filtering annotations and security annotations for entity data filtering it is enough to register SecurityEntityFilteringFeature as this feature registers also EntityFilteringFeature.

Entity-filtering currently recognizes one property that can be passed into the Configuration instance (client/server):

You can configure entity-filtering on server (basic + security examples) as follows:

new ResourceConfig()
    // Set entity-filtering scope via configuration.
    .property(EntityFilteringFeature.ENTITY_FILTERING_SCOPE, new Annotation[] {ProjectDetailedView.Factory.get()})
    // Register the EntityFilteringFeature.
    .register(EntityFilteringFeature.class)
    // Further configuration of ResourceConfig.
    .register( ... );

new ResourceConfig()
    // Set entity-filtering scope via configuration.
    .property(EntityFilteringFeature.ENTITY_FILTERING_SCOPE, new Annotation[] {SecurityAnnotations.rolesAllowed("manager")})
    // Register the SecurityEntityFilteringFeature.
    .register(SecurityEntityFilteringFeature.class)
    // Further configuration of ResourceConfig.
    .register( ... );

new ResourceConfig()
    // Set query parameter name for dynamic filtering
    .property(SelectableEntityFilteringFeature.QUERY_PARAM_NAME, "select")
    // Register the SelectableEntityFilteringFeature.
    .register(SelectableEntityFilteringFeature.class)
    // Further configuration of ResourceConfig.
    .register( ... );

Use similar steps to register entity-filtering on client:

final ClientConfig config = new ClientConfig()
    // Set entity-filtering scope via configuration.
    .property(EntityFilteringFeature.ENTITY_FILTERING_SCOPE, new Annotation[] {ProjectDetailedView.Factory.get()})
    // Register the EntityFilteringFeature.
    .register(EntityFilteringFeature.class)
    // Further configuration of ClientConfig.
    .register( ... );

// Create new client.
final Client client = ClientClientBuilder.newClient(config);

// Use the client.

In the next section the entity-filtering features will be illustrated on a project-tracking application that contains three classes in its domain model and few resources (only Project resource will be shown in this chapter). The full source code for the example application can be found in Jersey Entity Filtering example.

Suppose there are three domain model classes (or entities) in our model: Project, User and Task (getters/setter are omitted for brevity).

public class Project {

    private Long id;

    private String name;

    private String description;

    private List<Task> tasks;

    private List<User> users;

    // getters and setters
}

public class User {

    private Long id;

    private String name;

    private String email;

    private List<Project> projects;

    private List<Task> tasks;

    // getters and setters
}

public class Task {

    private Long id;

    private String name;

    private String description;

    private Project project;

    private User user;

    // getters and setters
}

To retrieve the entities from server to client, we have created also a couple of JAX-RS resources from whose the ProjectsResource is shown as example.

@Path("projects")
@Produces("application/json")
public class ProjectsResource {

    @GET
    @Path("{id}")
    public Project getProject(@PathParam("id") final Long id) {
        return getDetailedProject(id);
    }

    @GET
    public List<Project> getProjects() {
        return getDetailedProjects();
    }
}

Entity filtering via annotations is based on an @EntityFiltering meta-annotation. This meta-annotation is used to identify entity-filtering annotations that can be then attached to

An example of entity-filtering annotation applicable to a class, field or method can be seen in Example 20.9, “ProjectDetailedView” below.

@Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@EntityFiltering
public @interface ProjectDetailedView {

    /**
     * Factory class for creating instances of {@code ProjectDetailedView} annotation.
     */
    public static class Factory
                        extends AnnotationLiteral<ProjectDetailedView>
                        implements ProjectDetailedView {

        private Factory() {
        }

        public static ProjectDetailedView get() {
            return new Factory();
        }
    }
}

Since creating annotation instances directly in Java code is not trivial, it is a good practice to provide an inner annotation Factory class in each custom filtering annotation, through which new instances of the annotation can be directly created. The annotation factory class can be created by extending the HK2 AnnotationLiteral class and implementing the annotation interface itself. It should also provide a static factory method that will create and return a new instance of the Factory class when invoked. Such annotation instances can be then passed to the client and server run-times to define or override entity-filtering scopes.

By placing an entity-filtering annotation on an entity (class, fields, getters or setters) we define a so-called entity-filtering scope for the entity. The purpose of entity-filtering scope is to identify parts of the domain model that should be processed when the model is to be sent over the wire in a particular entity-filtering scope. We distinguish between:

Unannotated members of a domain model class are automatically added to all existing global entity-filtering scopes. If there is no explicit global entity-filtering scope defined on a class a default scope is created for this class to group these members.

Creating entity-filtering scopes using custom entity-filtering annotations in domain model classes is illustrated in the following examples.

public class Project {

    private Long id;

    private String name;

    private String description;

    @ProjectDetailedView
    private List<Task> tasks;

    @ProjectDetailedView
    private List<User> users;

    // getters and setters
}

public class User {

    private Long id;

    private String name;

    private String email;

    @UserDetailedView
    private List<Project> projects;

    @UserDetailedView
    private List<Task> tasks;

    // getters and setters
}

public class Task {

    private Long id;

    private String name;

    private String description;

    @TaskDetailedView
    private Project project;

    @TaskDetailedView
    private User user;

    // getters and setters
}

As you can see in the examples above, we have defined 3 separate scopes using @ProjectDetailedView, @UserDetailedView and @TaskDetailedView annotations and we have applied these scopes selectively to certain fields in the domain model classes.

Once the entity-filtering scopes are applied to the parts of a domain model, the entity filtering facility (when enabled) will check the active scopes when the model is being sent over the wire, and filter out all parts from the model for which there is no active scope set in the given context. Therefore, we need a way how to control the scopes active in any given context in order to process the model data in a certain way (e.g. expose the detailed view). We need to tell the server/client runtime which entity-filtering scopes we want to apply. There are 2 ways how to do this for client-side and 3 ways for server-side:

When the multiple approaches are combined, the priorities of calculating the applied scopes are as follows: Entity annotations in request or response > Property passed through Configuration > Annotations applied to a resource method or class.

In a graph of domain model objects, the entity-filtering scopes are applied to the root node as well as transitively to all the child nodes. Fields and child nodes that do not match at least a single active scope are filtered out. When the scope matching is performed, annotations applied to the domain model classes and fields are used to compute the scope for each particular component of the model. If there are no annotations on the class or its fields, the default scope is assumed. During the filtering, first, the annotations on root model class and its fields are considered. For all composite fields that have not been filtered out, the annotations on the referenced child class and its fields are considered next, and so on.

@Path("projects")
@Produces("application/json")
public class ProjectsResource {

    @GET
    public Response getProjects(@QueryParam("detailed") final boolean isDetailed) {
        return Response
                .ok()
                .entity(new GenericEntity<List<Project>>(EntityStore.getProjects()) {},
                        isDetailed ? new Annotation[]{ProjectDetailedView.Factory.get()} : new Annotation[0])
                .build();
    }
}

@Path("projects")
@Produces("application/json")
public class ProjectsResource {

    @GET
    public List<Project> getProjects() {
        return getDetailedProjects();
    }

    @GET
    @Path("detailed")
    @ProjectDetailedView
    public List<Project> getDetailedProjects() {
        return EntityStore.getProjects();
    }
}

{
   "description" : "Jersey is the open source (under dual EPL+GPL license) JAX-RS 2.1 (JSR 370) production quality Reference Implementation for building RESTful Web services.",
   "id" : 1,
   "name" : "Jersey",
   "tasks" : [ {
      "description" : "Entity Data Filtering",
      "id" : 1,
      "name" : "ENT_FLT"
   }, {
      "description" : "OAuth 1 + 2",
      "id" : 2,
      "name" : "OAUTH"
   } ],
   "users" : [ {
      "email" : "very@secret.com",
      "id" : 1,
      "name" : "Jersey Robot"
   } ]
}

{
   "description" : "Jersey is the open source (under dual EPL+GPL license) JAX-RS 2.1 (JSR 370) production quality Reference Implementation for building RESTful Web services.",
   "id" : 1,
   "name" : "Jersey"
}

ClientBuilder.newClient(config)
    .target(uri)
    .request()
    .post(Entity.entity(project, new Annotation[] {ProjectDetailedView.Factory.get()}));

@Path("clients")
@Produces("application/json")
public class ClientsResource {

    @Uri("projects")
    private WebTarget target;

    @GET
    public List<Project> getProjects() {
        return target.request()
            .post(Entity.entity(project, new Annotation[] {ProjectDetailedView.Factory.get()}));
    }
}

Filtering the content sent to the client (or server) based on the authorized security roles is a commonly required use case. By registering SecurityEntityFilteringFeature you can leverage the Jersey Entity Filtering facility in connection with standard javax.annotation.security annotations exactly the same way as you would with custom entity-filtering annotations described in previous chapters. Supported security annotations are:

Although the mechanics of the Entity Data Filtering feature used for the security annotation-based filtering is the same as with the entity-filtering annotations, the processing of security annotations differs in a few important aspects:

Filtering the content sent to the client (or server) dynamically based on query parameters is another commonly required use case. By registering SelectableEntityFilteringFeature you can leverage the Jersey Entity Filtering facility in connection with query parameters exactly the same way as you would with custom entity-filtering annotations described in previous chapters.

@XmlRootElement
public class Address {

    private String streetAddress;

    private String region;

    private PhoneNumber phoneNumber;
}

Query parameters are supported in comma delimited "dot notation" style similar to BeanInfo objects and Spring path expressions. As an example, the following URL: http://jersey.example.com/addresses/51234?select=region,streetAddress may render only the address's region and street address properties as in the following example:

{
   "region" : "CA",
   "streetAddress" : "1234 Fake St."
}

To create a custom entity-filtering annotation with special handling, i.e. an field aggregator annotation used to annotate classes like the one in Example 20.19, “Entity-filtering annotation with custom meaning” it is, in most cases, sufficient to implement and register the following SPI contracts:

@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@EntityFiltering
public @interface FilteringAggregator {

    /**
     * Entity-filtering scope to add given fields to.
     */
    Annotation filteringScope();

    /**
     * Fields to be a part of the entity-filtering scope.
     */
    String[] fields();
}

To support Entity Data Filtering in custom entity providers (e.g. as in Example 20.20, “Entity Data Filtering support in MOXy JSON binding provider”), it is sufficient in most of the cases to implement and register the following SPI contracts:

@Singleton
public class FilteringMoxyJsonProvider extends ConfigurableMoxyJsonProvider {

    @Inject
    private Provider<ObjectProvider<ObjectGraph>> provider;

    @Override
    protected void preWriteTo(final Object object, final Class<?> type, final Type genericType, final Annotation[] annotations,
                              final MediaType mediaType, final MultivaluedMap<String, Object> httpHeaders,
                              final Marshaller marshaller) throws JAXBException {
        super.preWriteTo(object, type, genericType, annotations, mediaType, httpHeaders, marshaller);

        // Entity Filtering.
        if (marshaller.getProperty(MarshallerProperties.OBJECT_GRAPH) == null) {
            final Object objectGraph = provider.get().getFilteringObject(genericType, true, annotations);

            if (objectGraph != null) {
                marshaller.setProperty(MarshallerProperties.OBJECT_GRAPH, objectGraph);
            }
        }
    }

    @Override
    protected void preReadFrom(final Class<Object> type, final Type genericType, final Annotation[] annotations,
                               final MediaType mediaType, final MultivaluedMap<String, String> httpHeaders,
                               final Unmarshaller unmarshaller) throws JAXBException {
        super.preReadFrom(type, genericType, annotations, mediaType, httpHeaders, unmarshaller);

        // Entity Filtering.
        if (unmarshaller.getProperty(MarshallerProperties.OBJECT_GRAPH) == null) {
            final Object objectGraph = provider.get().getFilteringObject(genericType, false, annotations);

            if (objectGraph != null) {
                unmarshaller.setProperty(MarshallerProperties.OBJECT_GRAPH, objectGraph);
            }
        }
    }
}

List of modules from Jersey workspace that support Entity Filtering:

In order to use Entity Filtering in mentioned modules you need to explicitly register either EntityFilteringFeature, SecurityEntityFilteringFeature or SelectableEntityFilteringFeature to activate Entity Filtering for particular module.

To see a complete working examples of entity-filtering feature refer to the: