Add @ProvideLink(s) to declarative-linking

@ProvideLinks allows a different way of creating links, with this feature you can annotate
the resource methods to contribute links to entities. This has the advantage, that you
don't have to build the resource path by hand. It is fully compatible with the existing
@InjectLinks and can be mixed. Furthermore, the link collection will now be merged
with an existing collection, this allows users to manually add links as well.

Change-Id: I66f474433f0bb55c66ca827bd85114622548adcb

Author: leonard84

incubator/declarative-linking/pom.xml

@@ -87,6 +87,25 @@
             <artifactId>junit</artifactId>
             <scope>test</scope>
         </dependency>
+
+        <dependency>
+            <groupId>org.glassfish.jersey.test-framework.providers</groupId>
+            <artifactId>jersey-test-framework-provider-grizzly2</artifactId>
+            <version>${project.version}</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.glassfish.jersey.media</groupId>
+            <artifactId>jersey-media-json-jackson</artifactId>
+            <version>${jersey.version}</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.skyscreamer</groupId>
+            <artifactId>jsonassert</artifactId>
+            <version>1.4.0</version>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <profiles>

incubator/declarative-linking/src/main/java/org/glassfish/jersey/linking/DeclarativeLinkingFeature.java

@@ -48,6 +48,8 @@
 
 import org.glassfish.jersey.Beta;
 import org.glassfish.jersey.internal.inject.AbstractBinder;
+import org.glassfish.jersey.linking.contributing.NaiveResourceLinkContributionContext;
+import org.glassfish.jersey.linking.contributing.ResourceLinkContributionContext;
 import org.glassfish.jersey.linking.mapping.NaiveResourceMappingContext;
 import org.glassfish.jersey.linking.mapping.ResourceMappingContext;
 
@@ -57,7 +59,6 @@
  * @author Mark Hadley
  * @author Gerard Davison (gerard.davison at oracle.com)
  */
-
 @Beta
 public class DeclarativeLinkingFeature implements Feature {
 
@@ -74,6 +75,14 @@ protected void configure() {
                             .to(ResourceMappingContext.class).in(Singleton.class);
                 }
             });
+            context.register(new AbstractBinder() {
+
+                @Override
+                protected void configure() {
+                    bindAsContract(NaiveResourceLinkContributionContext.class)
+                            .to(ResourceLinkContributionContext.class).in(Singleton.class);
+                }
+            });
 
             context.register(ResponseLinkFilter.class);
 

incubator/declarative-linking/src/main/java/org/glassfish/jersey/linking/ELLinkBuilder.java

@@ -1,7 +1,7 @@
 /*
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
  *
- * Copyright (c) 2010-2015 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010-2017 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
@@ -69,7 +69,13 @@ private ELLinkBuilder() {
             ExpressionFactory.newInstance();
 
     /**
-     * TODO javadoc.
+     * Evaluates the condition
+     *
+     * @param condition the condition expression
+     * @param entity    the entity returned from the resource method
+     * @param resource  the resource class instance that returned the entity
+     * @param instance  the instance that contains the entity, e.g. the value of a field within an entity class.
+     * @return the result of the condition
      */
     static boolean evaluateCondition(String condition,
                                      Object entity,
@@ -87,7 +93,15 @@ static boolean evaluateCondition(String condition,
     }
 
     /**
-     * TODO javadoc.
+     * Creates the URI using the link descriptor.
+     *
+     * @param link the link descriptor
+     * @param entity the entity returned from the resource method
+     * @param resource the resource class instance that returned the entity
+     * @param instance the instance that contains the entity, e.g. the value of a field within an entity class.
+     * @param uriInfo JAX-RS {@link UriInfo}
+     * @param rmc the {@link ResourceMappingContext}
+     * @return the URI
      */
     static URI buildURI(InjectLinkDescriptor link,
                         Object entity,

incubator/declarative-linking/src/main/java/org/glassfish/jersey/linking/EntityDescriptor.java

@@ -1,7 +1,7 @@
 /*
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
  *
- * Copyright (c) 2010-2015 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010-2017 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
@@ -59,14 +59,12 @@
  * @author Mark Hadley
  * @author Gerard Davison (gerard.davison at oracle.com)
  */
-
 class EntityDescriptor {
 
     // Maintains an internal static cache to optimize processing
-
     private static final Map<Class<?>, EntityDescriptor> descriptors = new HashMap<>();
 
-    public static synchronized EntityDescriptor getInstance(Class<?> entityClass) {
+    static synchronized EntityDescriptor getInstance(Class<?> entityClass) {
         if (descriptors.containsKey(entityClass)) {
             return descriptors.get(entityClass);
         } else {
@@ -84,6 +82,7 @@ public static synchronized EntityDescriptor getInstance(Class<?> entityClass) {
 
     /**
      * Construct an new descriptor by inspecting the supplied class.
+     *
      * @param entityClass
      */
     private EntityDescriptor(Class<?> entityClass) {
@@ -100,21 +99,22 @@ private EntityDescriptor(Class<?> entityClass) {
         this.linkFields = Collections.unmodifiableMap(this.linkFields);
     }
 
-    public Collection<FieldDescriptor> getLinkFields() {
+    Collection<FieldDescriptor> getLinkFields() {
         return linkFields.values();
     }
 
-    public Collection<FieldDescriptor> getNonLinkFields() {
+    Collection<FieldDescriptor> getNonLinkFields() {
         return nonLinkFields.values();
     }
 
-    public List<LinkHeaderDescriptor> getLinkHeaders() {
+    List<LinkHeaderDescriptor> getLinkHeaders() {
         return linkHeaders;
     }
 
     /**
      * Find and cache the fields of the supplied class and its superclasses and
      * interfaces.
+     *
      * @param entityClass the class
      */
     private void findFields(Class<?> entityClass) {

incubator/declarative-linking/src/main/java/org/glassfish/jersey/linking/FieldDescriptor.java

@@ -1,7 +1,7 @@
 /*
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
  *
- * Copyright (c) 2010-2015 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010-2017 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
@@ -61,7 +61,7 @@ class FieldDescriptor {
         this.field = f;
     }
 
-    public Object getFieldValue(Object instance) {
+    Object getFieldValue(Object instance) {
         setAccessibleField(field);
         Object value = null;
         try {
@@ -76,7 +76,7 @@ public String getFieldName() {
         return field.getName();
     }
 
-    protected static void setAccessibleField(final Field f) {
+    static void setAccessibleField(final Field f) {
         if (Modifier.isPublic(f.getModifiers())) {
             return;
         }

incubator/declarative-linking/src/main/java/org/glassfish/jersey/linking/FieldProcessor.java

@@ -1,7 +1,7 @@
 /*
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
  *
- * Copyright (c) 2010-2016 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010-2017 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
@@ -43,16 +43,19 @@
 import java.lang.reflect.Modifier;
 import java.net.URI;
 import java.util.ArrayList;
-import java.util.logging.Level;
-import java.util.logging.Logger;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
 import javax.ws.rs.core.Link;
 import javax.ws.rs.core.UriInfo;
+
 import javax.xml.bind.annotation.XmlTransient;
 
+import org.glassfish.jersey.linking.contributing.ResourceLinkContributionContext;
 import org.glassfish.jersey.linking.mapping.ResourceMappingContext;
 
 /**
@@ -67,33 +70,39 @@ class FieldProcessor<T> {
     private EntityDescriptor instanceDescriptor;
     private static final Logger log = Logger.getLogger(FieldProcessor.class.getName());
 
-    public FieldProcessor(Class<T> c) {
+    FieldProcessor(Class<T> c) {
         instanceDescriptor = EntityDescriptor.getInstance(c);
     }
 
     /**
      * Inject any {@link org.glassfish.jersey.linking.InjectLink} annotated fields in the supplied entity and
      * recursively process its fields.
-     * @param entity the entity object returned by the resource method
+     *
+     * @param entity  the entity object returned by the resource method
      * @param uriInfo the uriInfo for the request
+     * @param rmc     the ResourceMappingContext used for building URIs
+     * @param rlcc    the ResourceLinkContributionContext used to find link contributors
      */
-    public void processLinks(T entity, UriInfo uriInfo, ResourceMappingContext rmc) {
+    void processLinks(T entity, UriInfo uriInfo, ResourceMappingContext rmc, ResourceLinkContributionContext rlcc) {
         Set<Object> processed = new HashSet<Object>();
         Object resource = uriInfo.getMatchedResources().get(0);
-        processLinks(entity, resource, entity, processed, uriInfo, rmc);
+        processLinks(entity, resource, entity, processed, uriInfo, rmc, rlcc);
     }
 
     /**
      * Inject any {@link org.glassfish.jersey.linking.InjectLink} annotated fields in the supplied instance. Called
      * once for the entity and then recursively for each member and field.
-     * @param entity
+     *
+     * @param entity    the entity object returned by the resource method
      * @param processed a list of already processed objects, used to break
-     * recursion when processing circular references.
-     * @param uriInfo
+     *                  recursion when processing circular references.
+     * @param uriInfo   the uriInfo for the request
+     * @param rmc       the ResourceMappingContext used for building URIs
+     * @param rlcc      the ResourceLinkContributionContext used to find link contributors
      */
     private void processLinks(Object entity, Object resource, Object instance,
-                              Set<Object> processed, UriInfo uriInfo,
-                              ResourceMappingContext rmc) {
+            Set<Object> processed, UriInfo uriInfo,
+            ResourceMappingContext rmc, ResourceLinkContributionContext rlcc) {
 
         try {
             if (instance == null || processed.contains(instance)) {
@@ -121,14 +130,23 @@ private void processLinks(Object entity, Object resource, Object instance,
             } else if (field instanceof InjectLinksFieldDescriptor) {
 
                 InjectLinksFieldDescriptor linksField = (InjectLinksFieldDescriptor) field;
-                List<Link> list = new ArrayList<Link>();
+                List<Link> list = new ArrayList<>();
                 for (InjectLinkFieldDescriptor linkField : linksField.getLinksToInject()) {
                     if (ELLinkBuilder.evaluateCondition(linkField.getCondition(), entity, resource, instance)) {
                        URI uri = ELLinkBuilder.buildURI(linkField, entity, resource, instance, uriInfo, rmc);
                        Link link = linkField.getLink(uri);
                        list.add(link);
                     }
                 }
+                List<ProvideLinkDescriptor> linkContributors = rlcc.getContributorsFor(instance.getClass());
+                for (ProvideLinkDescriptor linkContributor : linkContributors) {
+                    if (ELLinkBuilder.evaluateCondition(linkContributor.getCondition(),
+                            entity, linkContributor.getResource(), instance)) {
+                        URI uri = ELLinkBuilder.buildURI(linkContributor, entity, resource, instance, uriInfo, rmc);
+                        Link link = linkContributor.getLink(uri);
+                        list.add(link);
+                    }
+                }
 
                 linksField.setPropertyValue(instance, list);
             }
@@ -139,25 +157,25 @@ private void processLinks(Object entity, Object resource, Object instance,
         if (instanceClass.isArray() && Object[].class.isAssignableFrom(instanceClass)) {
             Object array[] = (Object[]) instance;
             for (Object member : array) {
-                processMember(entity, resource, member, processed, uriInfo, rmc);
+                processMember(entity, resource, member, processed, uriInfo, rmc, rlcc);
             }
         } else if (instance instanceof Iterable) {
             Iterable iterable = (Iterable) instance;
             for (Object member : iterable) {
-                processMember(entity, resource, member, processed, uriInfo, rmc);
+                processMember(entity, resource, member, processed, uriInfo, rmc, rlcc);
             }
         } else if (instance instanceof Map) {
             Map map = (Map) instance;
             for (Object member : map.entrySet()) {
-                processMember(entity, resource, member, processed, uriInfo, rmc);
+                processMember(entity, resource, member, processed, uriInfo, rmc, rlcc);
             }
         }
 
         // Recursively process all member fields
         for (FieldDescriptor member : instanceDescriptor.getNonLinkFields()) {
 
             if (fieldSuitableForIntrospection(member)) {
-                processMember(entity, resource, member.getFieldValue(instance), processed, uriInfo, rmc);
+                processMember(entity, resource, member.getFieldValue(instance), processed, uriInfo, rmc, rlcc);
             }
         }
 
@@ -174,10 +192,10 @@ private boolean fieldSuitableForIntrospection(FieldDescriptor member) {
     }
 
     private void processMember(Object entity, Object resource, Object member, Set<Object> processed, UriInfo uriInfo,
-      ResourceMappingContext rmc) {
+            ResourceMappingContext rmc, ResourceLinkContributionContext rlcc) {
         if (member != null) {
-            FieldProcessor proc = new FieldProcessor(member.getClass());
-            proc.processLinks(entity, resource, member, processed, uriInfo, rmc);
+            FieldProcessor<?> proc = new FieldProcessor(member.getClass());
+            proc.processLinks(entity, resource, member, processed, uriInfo, rmc, rlcc);
         }
     }
 

incubator/declarative-linking/src/main/java/org/glassfish/jersey/linking/HeaderProcessor.java

@@ -1,7 +1,7 @@
 /*
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
  *
- * Copyright (c) 2010-2015 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010-2017 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
@@ -61,7 +61,7 @@ class HeaderProcessor<T> {
 
     private EntityDescriptor instanceDescriptor;
 
-    public HeaderProcessor(Class<T> c) {
+    HeaderProcessor(Class<T> c) {
         instanceDescriptor = EntityDescriptor.getInstance(c);
     }
 
@@ -71,10 +71,10 @@ public HeaderProcessor(Class<T> c) {
      * @param uriInfo the uriInfo for the request
      * @param headers the map into which the headers will be added
      */
-    public void processLinkHeaders(T entity,
-                                   UriInfo uriInfo,
-                                   ResourceMappingContext rmc,
-                                   MultivaluedMap<String, Object> headers) {
+    void processLinkHeaders(T entity,
+                            UriInfo uriInfo,
+                            ResourceMappingContext rmc,
+                            MultivaluedMap<String, Object> headers) {
         List<String> headerValues = getLinkHeaderValues(entity, uriInfo, rmc);
         for (String headerValue : headerValues) {
             headers.add("Link", headerValue);
@@ -100,8 +100,8 @@ List<String> getLinkHeaderValues(Object entity, UriInfo uriInfo, ResourceMapping
         return Collections.emptyList();
     }
 
-    static String getLinkHeaderValue(LinkHeaderDescriptor desc, Object entity, Object resource, UriInfo uriInfo,
-                                     ResourceMappingContext rmc) {
+    private static String getLinkHeaderValue(LinkHeaderDescriptor desc, Object entity, Object resource, UriInfo uriInfo,
+                                             ResourceMappingContext rmc) {
         URI uri = ELLinkBuilder.buildURI(desc, entity, resource, entity, uriInfo, rmc);
         InjectLink link = desc.getLinkHeader();
         return InjectLink.Util.buildLinkFromUri(uri, link).toString();