From fa91fa00230e56b08c99cb31ab5160fd98ca6433 Mon Sep 17 00:00:00 2001
From: Brad Baker <bbaker@atlassian.com>
Date: Fri, 28 Apr 2017 10:15:02 +1000
Subject: [PATCH] #383 added extra readme documentation for specific references

---
 README.md                                  | 38 +++++++++++++++++++++-
 src/test/groovy/readme/ReadmeExamples.java | 26 ++++++++++++++-
 2 files changed, 62 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index de080458dd..e6c15b92ab 100644
--- a/README.md
+++ b/README.md
@@ -295,7 +295,43 @@ GraphQLObjectType person = newObject()
     .build();
 
 ```
- 
+
+##### Specific Recursive Types
+
+Certain situations require specific type classes as input.  For example the possible union types inside a `GraphQLUnionType` are required
+  to be `GraphQLObjectType` objects.  You can't use a `GraphQLTypeReference` in this case as it is not specifically that type.
+
+You can use a `reference` method on each specific type to create a reference to that type.   
+
+```java
+GraphQLObjectType objectReference = GraphQLObjectType.reference("ObjectReference");
+GraphQLInterfaceType interfaceReference = GraphQLInterfaceType.reference("InterfaceReference");
+GraphQLInputObjectType inputObjectReference = GraphQLInputObjectType.reference("InputObjectReference");
+
+```
+
+you would use this say like this :
+
+```java
+GraphQLUnionType PetType = newUnionType()
+        .name("Pet")
+        .possibleType(GraphQLObjectType.reference("Cat"))
+        .possibleType(DogType)
+        .typeResolver(new TypeResolver() {
+            @Override
+            public GraphQLObjectType getType(Object object) {
+                if (object instanceof GarfieldSchema.Cat) {
+                    return CatType;
+                }
+                if (object instanceof GarfieldSchema.Dog) {
+                    return DogType;
+                }
+                return null;
+            }
+        })
+        .build();
+
+```
  
 #### Data fetching
 
diff --git a/src/test/groovy/readme/ReadmeExamples.java b/src/test/groovy/readme/ReadmeExamples.java
index 8d861ea760..fc88c76715 100644
--- a/src/test/groovy/readme/ReadmeExamples.java
+++ b/src/test/groovy/readme/ReadmeExamples.java
@@ -131,7 +131,6 @@ public GraphQLObjectType getType(Object object) {
                 .build();
     }
 
-
     void recursiveTypes() {
 
         GraphQLObjectType person = newObject()
@@ -142,6 +141,31 @@ void recursiveTypes() {
                 .build();
     }
 
+    void recursiveTypesSpecifically() {
+
+        GraphQLObjectType objectReference = GraphQLObjectType.reference("ObjectReference");
+        GraphQLInterfaceType interfaceReference = GraphQLInterfaceType.reference("InterfaceReference");
+        GraphQLInputObjectType inputObjectReference = GraphQLInputObjectType.reference("InputObjectReference");
+
+        GraphQLUnionType PetType = newUnionType()
+                .name("Pet")
+                .possibleType(GraphQLObjectType.reference("Cat"))
+                .possibleType(DogType)
+                .typeResolver(new TypeResolver() {
+                    @Override
+                    public GraphQLObjectType getType(Object object) {
+                        if (object instanceof GarfieldSchema.Cat) {
+                            return CatType;
+                        }
+                        if (object instanceof GarfieldSchema.Dog) {
+                            return DogType;
+                        }
+                        return null;
+                    }
+                })
+                .build();
+    }
+
     void executionStrategies() {
 
         ThreadPoolExecutor threadPoolExecutor = new ThreadPoolExecutor(