Relay deprecation removal and documentation (#660)

bbakerman · web-flow · commit 513d6e3c7e2e · 2017-08-29T08:50:32.000+10:00
diff --git a/src/main/java/graphql/relay/Connection.java b/src/main/java/graphql/relay/Connection.java
@@ -5,13 +5,22 @@
 import java.util.List;
 
 /**
- * represents a connection in relay.
+ * This represents a connection in Relay, which is a list of {@link graphql.relay.Edge edge}s
+ * as well as a {@link graphql.relay.PageInfo pageInfo} that describes the pagination of that list.
+ *
+ * See <a href="https://facebook.github.io/relay/graphql/connections.htm">https://facebook.github.io/relay/graphql/connections.htm</a>
  */
 @PublicApi
 public interface Connection<T> {
 
+    /**
+     * @return a list of {@link graphql.relay.Edge}s that are really a node of data and its cursor
+     */
     List<Edge<T>> getEdges();
 
+    /**
+     * @return {@link graphql.relay.PageInfo} pagination data about about that list of edges
+     */
     PageInfo getPageInfo();
 
 }
diff --git a/src/main/java/graphql/relay/ConnectionCursor.java b/src/main/java/graphql/relay/ConnectionCursor.java
@@ -3,11 +3,19 @@
 import graphql.PublicApi;
 
 /**
- * represents a {@link Connection connection} cursor in relay.
+ * Represents a {@link Connection connection} cursor in Relay which is an opaque
+ * string that the server understands.  Often this is base64 encoded but the spec only
+ * mandates that it be an opaque cursor so meaning can't be inferred from it (to prevent cheating like
+ * pre calculating the next cursor on the client say)
+ *
+ * See <a href="https://facebook.github.io/relay/graphql/connections.htm#sec-Cursor">https://facebook.github.io/relay/graphql/connections.htm#sec-Cursor</a>
  */
 @PublicApi
 public interface ConnectionCursor {
 
+    /**
+     * @return an opaque string that represents this cursor.
+     */
     String getValue();
 
 }
diff --git a/src/main/java/graphql/relay/DefaultConnection.java b/src/main/java/graphql/relay/DefaultConnection.java
@@ -2,71 +2,44 @@
 
 import graphql.PublicApi;
 
-import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
 
 import static graphql.Assert.assertNotNull;
+import static java.util.Collections.unmodifiableList;
 
+/**
+ * A default implementation of {@link graphql.relay.Connection}
+ */
 @PublicApi
 public class DefaultConnection<T> implements Connection<T> {
 
-    private List<Edge<T>> edges = new ArrayList<>();
-
-    private PageInfo pageInfo;
-
-    /**
-     * @deprecated prefer {@link #DefaultConnection(List, PageInfo)}
-     */
-    @Deprecated
-    public DefaultConnection() {
-    }
+    private final List<Edge<T>> edges;
+    private final PageInfo pageInfo;
 
     /**
-     * @param edges    edges
-     * @param pageInfo page info
+     * A connection consists of a list of edges and page info
+     *
+     * @param edges    a non null list of edges
+     * @param pageInfo a non null page info
      *
      * @throws IllegalArgumentException if edges or page info is null. use {@link Collections#emptyList()} for empty edges.
      */
     public DefaultConnection(List<Edge<T>> edges, PageInfo pageInfo) {
-        // TODO make defensive copy
-        this.edges = assertNotNull(edges, "edges cannot be null");
+        this.edges = unmodifiableList(assertNotNull(edges, "edges cannot be null"));
         this.pageInfo = assertNotNull(pageInfo, "page info cannot be null");
     }
 
     @Override
     public List<Edge<T>> getEdges() {
-        return Collections.unmodifiableList(edges);
-    }
-
-    /**
-     * @param edges edges
-     *
-     * @deprecated prefer {@link #DefaultConnection(List, PageInfo)} and avoid mutation
-     */
-    @Deprecated
-    public void setEdges(List<Edge<T>> edges) {
-        if (edges == null) { // TODO remove setter
-            edges = Collections.emptyList();
-        }
-        this.edges = edges;
+        return edges;
     }
 
     @Override
     public PageInfo getPageInfo() {
         return pageInfo;
     }
 
-    /**
-     * @param pageInfo page info
-     *
-     * @deprecated prefer {@link #DefaultConnection(List, PageInfo)} and avoid mutation
-     */
-    @Deprecated
-    public void setPageInfo(PageInfo pageInfo) {
-        this.pageInfo = pageInfo;
-    }
-
     @Override
     public String toString() {
         return "DefaultConnection{" +
diff --git a/src/main/java/graphql/relay/DefaultEdge.java b/src/main/java/graphql/relay/DefaultEdge.java
@@ -7,51 +7,25 @@
 @PublicApi
 public class DefaultEdge<T> implements Edge<T> {
 
+    private final T node;
+    private final ConnectionCursor cursor;
+
     public DefaultEdge(T node, ConnectionCursor cursor) {
         this.cursor = assertNotNull(cursor, "cursor cannot be null");
         this.node = node;
     }
 
-    /**
-     * @deprecated prefer {@link #DefaultEdge(Object, ConnectionCursor)}
-     */
-    @Deprecated
-    public DefaultEdge() {
-    }
-
-    private T node;
-    private ConnectionCursor cursor;
 
     @Override
     public T getNode() {
         return node;
     }
 
-    /**
-     * @param node node
-     *
-     * @deprecated prefer {@link #DefaultEdge(Object, ConnectionCursor)} and avoid mutation.
-     */
-    @Deprecated
-    public void setNode(T node) {
-        this.node = node;
-    }
-
     @Override
     public ConnectionCursor getCursor() {
         return cursor;
     }
 
-    /**
-     * @param cursor cursor
-     *
-     * @deprecated prefer {@link #DefaultEdge(Object, ConnectionCursor)} and avoid mutation.
-     */
-    @Deprecated
-    public void setCursor(ConnectionCursor cursor) {
-        this.cursor = cursor;
-    }
-
     @Override
     public String toString() {
         return "DefaultEdge{" +
diff --git a/src/main/java/graphql/relay/DefaultPageInfo.java b/src/main/java/graphql/relay/DefaultPageInfo.java
@@ -6,17 +6,10 @@
 @PublicApi
 public class DefaultPageInfo implements PageInfo {
 
-    private ConnectionCursor startCursor;
-    private ConnectionCursor endCursor;
-    private boolean hasPreviousPage;
-    private boolean hasNextPage;
-
-    /**
-     * @deprecated prefer {@link #DefaultPageInfo(ConnectionCursor, ConnectionCursor, boolean, boolean)}
-     */
-    @Deprecated
-    public DefaultPageInfo() {
-    }
+    private final ConnectionCursor startCursor;
+    private final ConnectionCursor endCursor;
+    private final boolean hasPreviousPage;
+    private final boolean hasNextPage;
 
     public DefaultPageInfo(ConnectionCursor startCursor, ConnectionCursor endCursor, boolean hasPreviousPage, boolean hasNextPage) {
         this.startCursor = startCursor;
@@ -30,61 +23,22 @@ public ConnectionCursor getStartCursor() {
         return startCursor;
     }
 
-    /**
-     * @param startCursor startCursor
-     *
-     * @deprecated prefer {@link #DefaultPageInfo(ConnectionCursor, ConnectionCursor, boolean, boolean)} and avoid mutation
-     */
-    @Deprecated
-    public void setStartCursor(ConnectionCursor startCursor) {
-        this.startCursor = startCursor;
-    }
 
     @Override
     public ConnectionCursor getEndCursor() {
         return endCursor;
     }
 
-    /**
-     * @param endCursor endCursor
-     *
-     * @deprecated prefer {@link #DefaultPageInfo(ConnectionCursor, ConnectionCursor, boolean, boolean)} and avoid mutation
-     */
-    @Deprecated
-    public void setEndCursor(ConnectionCursor endCursor) {
-        this.endCursor = endCursor;
-    }
-
     @Override
     public boolean isHasPreviousPage() {
         return hasPreviousPage;
     }
 
-    /**
-     * @param hasPreviousPage previous page
-     *
-     * @deprecated prefer {@link #DefaultPageInfo(ConnectionCursor, ConnectionCursor, boolean, boolean)} and avoid mutation
-     */
-    @Deprecated
-    public void setHasPreviousPage(boolean hasPreviousPage) {
-        this.hasPreviousPage = hasPreviousPage;
-    }
-
     @Override
     public boolean isHasNextPage() {
         return hasNextPage;
     }
 
-    /**
-     * @param hasNextPage has next page
-     *
-     * @deprecated prefer {@link #DefaultPageInfo(ConnectionCursor, ConnectionCursor, boolean, boolean)}
-     */
-    @Deprecated
-    public void setHasNextPage(boolean hasNextPage) {
-        this.hasNextPage = hasNextPage;
-    }
-
     @Override
     public String toString() {
         return "DefaultPageInfo{" +
diff --git a/src/main/java/graphql/relay/Edge.java b/src/main/java/graphql/relay/Edge.java
@@ -3,13 +3,21 @@
 import graphql.PublicApi;
 
 /**
- * represents an edge in relay.
+ * Represents an edge in Relay which is essentially a node of data T and the cursor for that node.
+ *
+ * See <a href="https://facebook.github.io/relay/graphql/connections.htm#sec-Edge-Types">https://facebook.github.io/relay/graphql/connections.htm#sec-Edge-Types</a>
  */
 @PublicApi
 public interface Edge<T> {
 
+    /**
+     * @return the node of data that this edge represents
+     */
     T getNode();
 
+    /**
+     * @return the cursor for this edge node
+     */
     ConnectionCursor getCursor();
 
 }
diff --git a/src/main/java/graphql/relay/PageInfo.java b/src/main/java/graphql/relay/PageInfo.java
@@ -3,7 +3,10 @@
 import graphql.PublicApi;
 
 /**
- * represents a page in relay.
+ * Represents pagination information in Relay about {@link graphql.relay.Edge edges} when used
+ * inside a {@link graphql.relay.Connection connection}
+ *
+ * See <a href="https://facebook.github.io/relay/graphql/connections.htm#sec-undefined.PageInfo">https://facebook.github.io/relay/graphql/connections.htm#sec-undefined.PageInfo</a>
  */
 @PublicApi
 public interface PageInfo {
@@ -19,12 +22,12 @@ public interface PageInfo {
     ConnectionCursor getEndCursor();
 
     /**
-     * @return true if and only if this page is not the first page. only meaningful when you gave {@code last} argument.
+     * @return true if and only if this page is not the first page. only meaningful when you gave the {@code last} argument.
      */
     boolean isHasPreviousPage();
 
     /**
-     * @return true if and only if this page is not the last page. only meaningful when you gave {@code first} argument.
+     * @return true if and only if this page is not the last page. only meaningful when you gave the {@code first} argument.
      */
     boolean isHasNextPage();
 }
diff --git a/src/main/java/graphql/relay/Relay.java b/src/main/java/graphql/relay/Relay.java
@@ -12,6 +12,7 @@
 import graphql.schema.GraphQLObjectType;
 import graphql.schema.GraphQLOutputType;
 import graphql.schema.TypeResolver;
+
 import java.nio.charset.StandardCharsets;
 import java.util.ArrayList;
 import java.util.List;
@@ -27,6 +28,12 @@
 import static graphql.schema.GraphQLInterfaceType.newInterface;
 import static graphql.schema.GraphQLObjectType.newObject;
 
+/**
+ * This can be used to compose graphql runtime types that implement
+ * that Relay specification.
+ *
+ * See <a href="https://facebook.github.io/relay/graphql/connections.htm">https://facebook.github.io/relay/graphql/connections.htm</a>
+ */
 @PublicApi
 public class Relay {
 
@@ -202,16 +209,8 @@ public ResolvedGlobalId(String type, String id) {
             this.id = id;
         }
 
-        /**
-         * @deprecated use {@link #getType()}
-         */
-        @Deprecated
-        public String type;
-        /**
-         * @deprecated use {@link #getId()}
-         */
-        @Deprecated
-        public String id;
+        private String type;
+        private String id;
 
         public String getType() {
             return type;
