Merge pull request javaee#60 from apemberton/master

Initial commit of 'Selectable' filtering implementation

docs/src/main/docbook/entity-filtering.xml

@@ -79,6 +79,9 @@
             <listitem>
                 <para><xref linkend="ef.security.annotations"/></para>
             </listitem>
+            <listitem>
+                <para><xref linkend="ef.selectable.annotations"/></para>
+            </listitem>
         </itemizedlist>
 
         as well as some more complex ones.
@@ -116,7 +119,7 @@
             </note>
         </para>
         <para>
-            The entity-filtering extension module provides two &lit.jaxrs.core.Feature;s which you can register into server/client
+            The entity-filtering extension module provides three &lit.jaxrs.core.Feature;s which you can register into server/client
             runtime in prior to use Entity Filtering in an application:
 
             <itemizedlist>
@@ -132,6 +135,10 @@
                     <para>Filtering based on security (<literal>javax.annotation.security</literal>) and entity-filtering
                         annotations.</para>
                 </listitem>
+                <listitem>
+                    <para>&jersey.message.filtering.SelectableEntityFilteringFeature;</para>
+                    <para>Filtering based on dynamic and configurable query parameters</para>
+                </listitem>
             </itemizedlist>
 
             If you want to use both entity-filtering annotations and security annotations for entity data filtering it is enough
@@ -185,6 +192,18 @@
     // Register the SecurityEntityFilteringFeature.
     .register(SecurityEntityFilteringFeature.class)
     // Further configuration of ResourceConfig.
+    .register( ... );</programlisting>
+            </example>
+
+            <example xml:id="ef.example.server.security.registration">
+                <title>Registering and configuring entity-filtering feature with security annotations on server.</title>
+
+                <programlisting language="java" linenumbering="numbered">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( ... );</programlisting>
             </example>
         </para>
@@ -710,6 +729,42 @@ public class ClientsResource {
             </note>
         </para>
     </section>
+
+    <section xml:id="ef.selectable.annotations">
+        <para>
+            Filtering the content sent to the client (or server) dynamically based on query parameters is another commonly
+            required use case. By registering &jersey.message.filtering.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. 
+        </para>
+
+        <para>
+        	<example>
+                    <title>Sever - Query Parameter driven entity-filtering</title>
+
+                    <programlisting language="java" linenumbering="numbered">@XmlRootElement
+public class Address {
+
+    private String streetAddress;
+
+    private String region;
+
+    private PhoneNumber phoneNumber;
+}</programlisting>
+                </example>
+        </para>
+        <para>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:  
+        </para>
+
+        <example>
+        <programlisting language="xml" linenumbering="numbered">{
+	   "region" : "CA",
+	   "streetAddress" : "1234 Fake St."
+	}</programlisting>
+	</example>
+
+    </section>
 
     <section xml:id="ef.custom.annotations">
         <title>Defining custom handling for entity-filtering annotations</title>

examples/entity-filtering-selectable/pom.xml

@@ -0,0 +1,112 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
+
+    Copyright (c) 2013-2014 Oracle and/or its affiliates. All rights reserved.
+
+    The contents of this file are subject to the terms of either the GNU
+    General Public License Version 2 only ("GPL") or the Common Development
+    and Distribution License("CDDL") (collectively, the "License").  You
+    may not use this file except in compliance with the License.  You can
+    obtain a copy of the License at
+    http://glassfish.java.net/public/CDDL+GPL_1_1.html
+    or packager/legal/LICENSE.txt.  See the License for the specific
+    language governing permissions and limitations under the License.
+
+    When distributing the software, include this License Header Notice in each
+    file and include the License file at packager/legal/LICENSE.txt.
+
+    GPL Classpath Exception:
+    Oracle designates this particular file as subject to the "Classpath"
+    exception as provided by Oracle in the GPL Version 2 section of the License
+    file that accompanied this code.
+
+    Modifications:
+    If applicable, add the following below the License Header, with the fields
+    enclosed by brackets [] replaced by your own identifying information:
+    "Portions Copyright [year] [name of copyright owner]"
+
+    Contributor(s):
+    If you wish your version of this file to be governed by only the CDDL or
+    only the GPL Version 2, indicate your decision by adding "[Contributor]
+    elects to include this software in this distribution under the [CDDL or GPL
+    Version 2] license."  If you don't indicate a single choice of license, a
+    recipient has the option to distribute your version of this file under
+    either the CDDL, the GPL Version 2 or to extend the choice of license to
+    its licensees as provided above.  However, if you add GPL Version 2 code
+    and therefore, elected the GPL Version 2 license, then the option applies
+    only if the new code is made subject to such option by the copyright
+    holder.
+
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+    <modelVersion>4.0.0</modelVersion>
+
+    <parent>
+        <groupId>org.glassfish.jersey.examples</groupId>
+        <artifactId>project</artifactId>
+        <version>2.6-SNAPSHOT</version>
+    </parent>
+
+    <artifactId>entity-filtering-selectable</artifactId>
+    <name>jersey-examples-entity-filtering-selectable</name>
+
+    <description>Jersey Entity Data Filtering Selectable Example.</description>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.glassfish.jersey.core</groupId>
+            <artifactId>jersey-server</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.glassfish.jersey.media</groupId>
+            <artifactId>jersey-media-moxy</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.glassfish.jersey.ext</groupId>
+            <artifactId>jersey-entity-filtering</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>org.glassfish.jersey.containers</groupId>
+            <artifactId>jersey-container-grizzly2-http</artifactId>
+        </dependency>
+
+        <dependency>
+            <groupId>org.glassfish.jersey.test-framework.providers</groupId>
+            <artifactId>jersey-test-framework-provider-bundle</artifactId>
+            <type>pom</type>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <!-- Run the application using "mvn exec:java" -->
+            <plugin>
+                <groupId>org.codehaus.mojo</groupId>
+                <artifactId>exec-maven-plugin</artifactId>
+                <configuration>
+                    <mainClass>org.glassfish.jersey.examples.entityfiltering.selectable.App</mainClass>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+
+    <profiles>
+        <profile>
+            <id>release</id>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>org.apache.maven.plugins</groupId>
+                        <artifactId>maven-assembly-plugin</artifactId>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
+    </profiles>
+
+</project>

examples/entity-filtering-selectable/src/main/java/org/glassfish/jersey/examples/entityfiltering/selectable/App.java

@@ -0,0 +1,82 @@
+/*
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
+ *
+ * Copyright (c) 2014 Oracle and/or its affiliates. All rights reserved.
+ *
+ * The contents of this file are subject to the terms of either the GNU
+ * General Public License Version 2 only ("GPL") or the Common Development
+ * and Distribution License("CDDL") (collectively, the "License").  You
+ * may not use this file except in compliance with the License.  You can
+ * obtain a copy of the License at
+ * http://glassfish.java.net/public/CDDL+GPL_1_1.html
+ * or packager/legal/LICENSE.txt.  See the License for the specific
+ * language governing permissions and limitations under the License.
+ *
+ * When distributing the software, include this License Header Notice in each
+ * file and include the License file at packager/legal/LICENSE.txt.
+ *
+ * GPL Classpath Exception:
+ * Oracle designates this particular file as subject to the "Classpath"
+ * exception as provided by Oracle in the GPL Version 2 section of the License
+ * file that accompanied this code.
+ *
+ * Modifications:
+ * If applicable, add the following below the License Header, with the fields
+ * enclosed by brackets [] replaced by your own identifying information:
+ * "Portions Copyright [year] [name of copyright owner]"
+ *
+ * Contributor(s):
+ * If you wish your version of this file to be governed by only the CDDL or
+ * only the GPL Version 2, indicate your decision by adding "[Contributor]
+ * elects to include this software in this distribution under the [CDDL or GPL
+ * Version 2] license."  If you don't indicate a single choice of license, a
+ * recipient has the option to distribute your version of this file under
+ * either the CDDL, the GPL Version 2 or to extend the choice of license to
+ * its licensees as provided above.  However, if you add GPL Version 2 code
+ * and therefore, elected the GPL Version 2 license, then the option applies
+ * only if the new code is made subject to such option by the copyright
+ * holder.
+ */
+
+package org.glassfish.jersey.examples.entityfiltering.selectable;
+
+import java.io.IOException;
+import java.net.URI;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
+import org.glassfish.grizzly.http.server.HttpServer;
+import org.glassfish.jersey.grizzly2.httpserver.GrizzlyHttpServerFactory;
+
+/**
+ * Java application class starting Grizzly2 server with Entity Data Filtering with query parameters.
+ *
+ * @author Andy Pemberton (pembertona at oracle.com)
+ */
+public final class App {
+
+    private static final URI BASE_URI = URI.create("http://localhost:8080/");
+
+    public static void main(String[] args) {
+        try {
+            System.out.println("Jersey Entity Data Filtering Example.");
+
+            final HttpServer server = GrizzlyHttpServerFactory.createHttpServer(BASE_URI, new SelectableEntityFilteringApplication());
+
+            System.out.println("Application started.\nTry out one of these URIs:");
+            for (final String path : new String[]{"people/1234", "people/1234?select=familyName,givenName",
+                    "people/1234?select=region,addresses.region",
+                    "people/1234?select=familyName,givenName,addresses.phoneNumber.number"}) {
+                System.out.println(BASE_URI + path);
+            }
+            System.out.println("Hit enter to stop it...");
+
+            System.in.read();
+
+            server.shutdownNow();
+        } catch (IOException ex) {
+            Logger.getLogger(App.class.getName())
+                    .log(Level.SEVERE, "I/O error occurred during reading from an system input stream.", ex);
+        }
+    }
+}

examples/entity-filtering-selectable/src/main/java/org/glassfish/jersey/examples/entityfiltering/selectable/SelectableEntityFilteringApplication.java

@@ -0,0 +1,69 @@
+/*
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
+ *
+ * Copyright (c) 2014 Oracle and/or its affiliates. All rights reserved.
+ *
+ * The contents of this file are subject to the terms of either the GNU
+ * General Public License Version 2 only ("GPL") or the Common Development
+ * and Distribution License("CDDL") (collectively, the "License").  You
+ * may not use this file except in compliance with the License.  You can
+ * obtain a copy of the License at
+ * http://glassfish.java.net/public/CDDL+GPL_1_1.html
+ * or packager/legal/LICENSE.txt.  See the License for the specific
+ * language governing permissions and limitations under the License.
+ *
+ * When distributing the software, include this License Header Notice in each
+ * file and include the License file at packager/legal/LICENSE.txt.
+ *
+ * GPL Classpath Exception:
+ * Oracle designates this particular file as subject to the "Classpath"
+ * exception as provided by Oracle in the GPL Version 2 section of the License
+ * file that accompanied this code.
+ *
+ * Modifications:
+ * If applicable, add the following below the License Header, with the fields
+ * enclosed by brackets [] replaced by your own identifying information:
+ * "Portions Copyright [year] [name of copyright owner]"
+ *
+ * Contributor(s):
+ * If you wish your version of this file to be governed by only the CDDL or
+ * only the GPL Version 2, indicate your decision by adding "[Contributor]
+ * elects to include this software in this distribution under the [CDDL or GPL
+ * Version 2] license."  If you don't indicate a single choice of license, a
+ * recipient has the option to distribute your version of this file under
+ * either the CDDL, the GPL Version 2 or to extend the choice of license to
+ * its licensees as provided above.  However, if you add GPL Version 2 code
+ * and therefore, elected the GPL Version 2 license, then the option applies
+ * only if the new code is made subject to such option by the copyright
+ * holder.
+ */
+package org.glassfish.jersey.examples.entityfiltering.selectable;
+
+import javax.ws.rs.ApplicationPath;
+
+import org.glassfish.jersey.message.filtering.SelectableEntityFilteringFeature;
+import org.glassfish.jersey.moxy.json.MoxyJsonConfig;
+import org.glassfish.jersey.server.ResourceConfig;
+
+/**
+ * Entity Data Filtering application using request parameters.
+ *
+ * @author Andy Pemberton (pembertona at gmail.com)
+ */
+@ApplicationPath("/")
+public class SelectableEntityFilteringApplication extends ResourceConfig {
+
+    public SelectableEntityFilteringApplication() {
+        // Register all resources present under the package.
+        packages("org.glassfish.jersey.examples.entityfiltering.selectable");
+
+        // Register entity-filtering selectable feature.
+        register(SelectableEntityFilteringFeature.class);
+
+        // Configure MOXy Json provider.
+        register(new MoxyJsonConfig().setFormattedOutput(true).resolver());
+
+        property(SelectableEntityFilteringFeature.QUERY_PARAM_NAME, "select");
+
+    }
+}