Tutorial: student records

modules/ROOT/nav.adoc

@@ -2,7 +2,7 @@
 
 * xref:hello-world:start-using-sdk.adoc[Hello World]
 ** xref:hello-world:sample-application.adoc[]
-// ** xref:hello-world:student-record-developer-tutorial.adoc[]
+** xref:hello-world:student-record-developer-tutorial.adoc[Student Record Tutorial]
 ** xref:howtos:managing-connections.adoc[Connecting to Your Database]
 *** xref:howtos:sdk-authentication.adoc[Authentication & Authorization]
 *** xref:howtos:troubleshooting-cloud-connections.adoc[Troubleshooting Cloud Connections]

modules/devguide/examples/java/AddEnrollments.java

@@ -0,0 +1,102 @@
+import com.couchbase.client.core.error.CouchbaseException;
+import com.couchbase.client.java.Bucket;
+import com.couchbase.client.java.Cluster;
+import com.couchbase.client.java.Collection;
+import com.couchbase.client.java.Scope;
+import com.couchbase.client.java.json.JsonArray;
+import com.couchbase.client.java.json.JsonObject;
+import com.couchbase.client.java.query.QueryOptions;
+import com.couchbase.client.java.query.QueryResult;
+import com.couchbase.client.java.query.QueryScanConsistency;
+import com.couchbase.client.java.ClusterOptions;
+
+import java.time.Duration;
+import java.time.LocalDate;
+import java.time.format.DateTimeFormatter;
+
+public class AddEnrollments {
+
+    public static void main(String[] args) {
+
+        String connectionString = "<<connection-string>>"; // Replace this with Connection String
+        String username = "<<username>>"; // Replace this with username from cluster access credentials
+        String password = "<<password>>"; // Replace this with password from cluster access credentials
+
+        Cluster cluster = Cluster.connect(connectionString, ClusterOptions.clusterOptions(username, password)
+                    .environment(env -> env.applyProfile("wan-development"))
+        );
+
+        // Retrieves the student bucket you set up.
+        Bucket bucket = cluster.bucket("student-bucket");
+
+        // Forces the application to wait until the bucket is ready.
+        bucket.waitUntilReady(Duration.ofSeconds(10));  
+
+        // Retrieves the `art-school-scope` collection from the scope.
+        Scope scope = bucket.scope("art-school-scope");
+        Collection student_records = scope.collection("student-record-collection");  
+
+        // Retrieves Hilary's student record, the `graphic design` course record, and the `art history` course record. 
+        // Each method uses a SQL++ call to retrieve a single record from each collection.
+        JsonObject hilary = retrieveStudent(cluster,"Hilary Smith"); 
+        JsonObject graphic_design = retrieveCourse(cluster, "graphic design"); 
+        JsonObject art_history = retrieveCourse(cluster, "art history");  
+
+        // Couchbase does not have a native date type, so the common practice is to store dates as strings.
+        String currentDate = LocalDate.now().format(DateTimeFormatter.ISO_DATE);    
+
+        // Stores the `enrollments` inside the student record as an array. 
+        // `JsonArray.create()` creates an empty list structure.
+        JsonArray enrollments = JsonArray.create();    
+
+        // Adds two JSON elements to the `enrollments` array: the course that the enrollment relates to, and the date that the student enrolled in the course. 
+        // To avoid repeating data all over the cluster, you store a reference to the course instead of the entire course record itself in this field. 
+        // This means that you do not have to search through every single record if the course details change.
+        enrollments.add(JsonObject.create()
+                .put("course-id", graphic_design.getString("id"))
+                .put("date-enrolled", currentDate));    
+        enrollments.add(JsonObject.create()
+                .put("course-id", art_history.getString("id"))
+                .put("date-enrolled", currentDate));   
+
+        // Adds the `enrollments` array to Hilary's student record.
+        hilary.put("enrollments", enrollments);   
+
+        // Commits the changes to the collection. 
+        // The `upsert` function call takes the key of the record you want to insert or update and the record itself as parameters. 
+        // If the `upsert` call finds a document with a matching ID in the collection, it updates the document. 
+        // If there is no matching ID, it creates a new document.
+        student_records.upsert(hilary.getString("id"), hilary); 
+
+        cluster.disconnect();
+
+    }
+
+    private static JsonObject retrieveStudent(Cluster cluster, String name) throws CouchbaseException {
+
+        QueryOptions studentQueryOptions = QueryOptions.queryOptions();
+        studentQueryOptions.parameters(JsonObject.create().put("name", name));
+        studentQueryOptions.scanConsistency(QueryScanConsistency.REQUEST_PLUS);
+
+        final QueryResult result = cluster.query("select META().id, src.* " +
+                        "from `student-bucket`.`art-school-scope`.`student-record-collection` src " +
+                        "where src.`name` = $name", studentQueryOptions);
+
+        return result.rowsAsObject().get(0);
+
+    }
+
+    private static JsonObject retrieveCourse(Cluster cluster, String course) throws CouchbaseException {
+
+        QueryOptions courseQueryOptions = QueryOptions.queryOptions();
+        courseQueryOptions.parameters(JsonObject.create().put("courseName", course));
+        courseQueryOptions.scanConsistency(QueryScanConsistency.REQUEST_PLUS);
+
+        final QueryResult result = cluster.query("select META().id, crc.* " +
+                        "from `student-bucket`.`art-school-scope`.`course-record-collection` crc " +
+                        "where crc.`course-name` = $courseName", courseQueryOptions);
+
+        return result.rowsAsObject().get(0);
+
+    }
+}

modules/devguide/examples/java/ArtSchoolRetriever.java

@@ -0,0 +1,48 @@
+import com.couchbase.client.core.error.CouchbaseException;
+import com.couchbase.client.java.Cluster;
+import com.couchbase.client.java.json.JsonObject;
+import com.couchbase.client.java.query.QueryOptions;
+import com.couchbase.client.java.query.QueryResult;
+import com.couchbase.client.java.ClusterOptions;
+
+public class ArtSchoolRetrieverParameters {
+
+    public static void main(String[] args) {
+
+        String connectionString = "<<connection-string>>"; // Replace this with Connection String
+        String username = "<<username>>"; // Replace this with username from cluster access credentials
+        String password = "<<password>>"; // Replace this with password from cluster access credentials
+
+        Cluster cluster = Cluster.connect(connectionString, ClusterOptions.clusterOptions(username, password)
+                    .environment(env -> env.applyProfile("wan-development"))
+        );
+
+
+        retrieveCourses(cluster);
+
+        cluster.disconnect();
+    }
+
+    private static void retrieveCourses(Cluster cluster) {
+
+        try {
+
+            // This SQL++ statement takes the parameter `$creditPopints`, 
+            // which is then substituted by the value in the second parameter when the statement is called.
+            final QueryResult result = cluster.query("select crc.* " +
+                            "from `student-bucket`.`art-school-scope`.`course-record-collection` crc " +
+                            "where crc.`credit-points` < $creditPoints",   
+
+                    // The second parameter in the function call, with a value that replaces `$creditPoints`.
+                    QueryOptions.queryOptions()
+                            .parameters(JsonObject.create().put("creditPoints", 200))); 
+
+            for (JsonObject row : result.rowsAsObject()) {
+                System.out.println("Found row: " + row);
+            }
+
+        } catch (CouchbaseException ex) {
+            ex.printStackTrace();
+        }
+    }
+}

modules/devguide/examples/java/ArtSchoolRetrieverAll.java

@@ -0,0 +1,37 @@
+import com.couchbase.client.core.error.CouchbaseException;
+import com.couchbase.client.java.Cluster;
+import com.couchbase.client.java.json.JsonObject;
+import com.couchbase.client.java.query.QueryResult;
+import com.couchbase.client.java.ClusterOptions;
+
+public class ArtSchoolRetriever {
+
+    public static void main(String[] args) {
+
+        String connectionString = "<<connection-string>>"; // Replace this with Connection String
+        String username = "<<username>>"; // Replace this with username from cluster access credentials
+        String password = "<<password>>"; // Replace this with password from cluster access credentials
+
+        Cluster cluster = Cluster.connect(connectionString, ClusterOptions.clusterOptions(username, password)
+                    .environment(env -> env.applyProfile("wan-development"))
+        );
+
+        retrieveCourses(cluster);
+
+        cluster.disconnect();
+    }
+
+    private static void retrieveCourses(Cluster cluster) {
+
+        try {
+            final QueryResult result = cluster.query("select crc.* from `student-bucket`.`art-school-scope`.`course-record-collection` crc");
+
+            for (JsonObject row : result.rowsAsObject()) {
+                System.out.println("Found row: " + row);
+            }
+
+        } catch (CouchbaseException ex) {
+            ex.printStackTrace();
+        }
+    }
+}

modules/devguide/examples/java/ConnectStudent.java

@@ -0,0 +1,47 @@
+import com.couchbase.client.java.Bucket;
+import com.couchbase.client.java.Cluster;
+import com.couchbase.client.java.Collection;
+import com.couchbase.client.java.Scope;
+import com.couchbase.client.java.ClusterOptions;
+import java.time.Duration;
+
+public class ConnectStudent {
+
+    public static void main(String[] args) {
+
+        String connectionString = "<<connection-string>>"; // Replace this with Connection String
+        String username = "<<username>>"; // Replace this with username from cluster access credentials
+        String password = "<<password>>"; // Replace this with password from cluster access credentials
+
+        //Connecting to the cluster
+        Cluster cluster = Cluster.connect(connectionString, ClusterOptions.clusterOptions(username, password)
+        // Use the pre-configured profile below to avoid latency issues with your connection.
+                    .environment(env -> env.applyProfile("wan-development"))
+        );
+
+        // The `cluster.bucket` retrieves the bucket you set up for the student cluster.
+        Bucket bucket = cluster.bucket("student-bucket");  
+
+        // Most of the Couchbase APIs are non-blocking. 
+        // When you call one of them, your application carries on and continues to perform other actions while the function you called executes. 
+        // When the function has finished executing, it sends a notification to the caller and the output of the call is processed.
+        // While this usually works, in this code sample the application carries on without waiting for the bucket retrieval to complete after you make the call to `cluster.bucket`. 
+        // This means that you now have to try to retrieve the scope from a bucket object that has not been fully initialized yet. 
+        // To fix this, you can use the `waitUntilReady` call. 
+        // This call forces the application to wait until the bucket object is ready.
+        bucket.waitUntilReady(Duration.ofSeconds(10));  
+
+        // The `bucket.scope` retrieves the `art-school-scope` from the bucket.
+        Scope scope = bucket.scope("art-school-scope");   
+
+        // The `scope.collection` retrieves the student collection from the scope.
+        Collection student_records = scope.collection("student-record-collection"); 
+
+        // A check to make sure the collection is connected and retrieved when you run the application. 
+        // You can see the output using maven.
+        System.out.println("The name of this collection is " + student_records.name()); 
+
+        // Like with all database systems, it's good practice to disconnect from the Couchbase cluster after you have finished working with it.
+        cluster.disconnect();
+    }
+}

modules/devguide/examples/java/InsertCourses.java

@@ -0,0 +1,47 @@
+import com.couchbase.client.java.Bucket;
+import com.couchbase.client.java.Cluster;
+import com.couchbase.client.java.Collection;
+import com.couchbase.client.java.Scope;
+import com.couchbase.client.java.json.JsonObject;
+import com.couchbase.client.java.ClusterOptions;
+
+import java.time.Duration;
+
+public class InsertCourses {
+
+    public static void main(String[] args) {
+
+        String connectionString = "<<connection-string>>"; // Replace this with Connection String
+        String username = "<<username>>"; // Replace this with username from cluster access credentials
+        String password = "<<password>>"; // Replace this with password from cluster access credentials
+
+        Cluster cluster = Cluster.connect(connectionString, ClusterOptions.clusterOptions(username, password)
+                    .environment(env -> env.applyProfile("wan-development"))
+        );
+
+        Bucket bucket = cluster.bucket("student-bucket");
+        bucket.waitUntilReady(Duration.ofSeconds(10));
+        Scope scope = bucket.scope("art-school-scope");
+
+        // The code here is similar to creating a student record, but it writes to a different collection.
+        Collection course_records = scope.collection("course-record-collection");   
+
+        addCourse(course_records, "ART-HISTORY-000001", "art history", "fine art", 100);
+        addCourse(course_records, "FINE-ART-000002", "fine art", "fine art", 50);
+        addCourse(course_records, "GRAPHIC-DESIGN-000003", "graphic design", "media and communication", 200);
+
+        cluster.disconnect();
+    }
+
+    private static void addCourse(Collection collection, String id, String name,
+                                  String faculty, int creditPoints) {
+
+        JsonObject course = JsonObject.create()
+                .put("course-name", name)
+                .put("faculty", faculty)
+                .put("credit-points", creditPoints);
+
+        collection.upsert(id, course);
+
+    }
+}

modules/devguide/examples/java/InsertStudent.java

@@ -0,0 +1,44 @@
+import com.couchbase.client.java.Bucket;
+import com.couchbase.client.java.Cluster;
+import com.couchbase.client.java.Collection;
+import com.couchbase.client.java.Scope;
+import com.couchbase.client.java.json.JsonObject;
+import com.couchbase.client.java.ClusterOptions;
+
+import java.time.Duration;
+import java.time.LocalDate;
+import java.time.format.DateTimeFormatter;
+
+public class InsertStudent {
+
+    public static void main(String[] args) {
+
+        String connectionString = "<<connection-string>>"; // Replace this with Connection String
+        String username = "<<username>>"; // Replace this with username from cluster access credentials
+        String password = "<<password>>"; // Replace this with password from cluster access credentials
+
+        Cluster cluster = Cluster.connect(connectionString, ClusterOptions.clusterOptions(username, password)
+                    .environment(env -> env.applyProfile("wan-development"))
+        );
+
+        Bucket bucket = cluster.bucket("student-bucket");
+        bucket.waitUntilReady(Duration.ofSeconds(10));
+        Scope scope = bucket.scope("art-school-scope");
+        Collection student_records = scope.collection("student-record-collection");    
+
+        // This `JsonObject` class creates and populates the student record.
+        JsonObject hilary = JsonObject.create()
+                .put("name", "Hilary Smith")
+                .put("date-of-birth",
+                        LocalDate.of(1980, 12, 21)
+                                .format(DateTimeFormatter.ISO_DATE));
+
+        // The `upsert` function inserts or updates documents in a collection. 
+        // The first parameter is a unique ID for the document, similar to a primary key used in a relational database system. 
+        // If the `upsert` call finds a document with a matching ID in the collection, it updates the document. 
+        // If there is no matching ID, it creates a new document.
+        student_records.upsert("000001", hilary);  
+
+        cluster.disconnect();
+    }
+}

modules/hello-world/pages/overview.adoc

@@ -112,10 +112,10 @@ How-to guides to help you start your development journey with Couchbase and the
 
 [.column]
 .Easy to Connect & Get Started
-* xref:hello-world:start-using-sdk.adoc[Quickstart Guide]
+* xref:hello-world:start-using-sdk.adoc[Getting Started]
 * xref:hello-world:sample-application.adoc[]
+* xref:hello-world:student-record-developer-tutorial.adoc[Beginners' Couchbase Tutorial]
 * xref:howtos:managing-connections.adoc[]
-// * xref:hello-world:student-record-developer-tutorial.adoc[Beginners' Couchbase Tutorial]
 
 [.column]
 .Search, Query, Analyze

modules/hello-world/pages/platform-help.adoc

@@ -39,7 +39,7 @@ SDKMAN! -- the Software Development Kit Manager -- enables multiple Java version
 This third party tool is unnecessary in most production environments, but ideal for development machines.
 Installation instructions can be found on the https://sdkman.io/install[SDKMAN! website]. 
 
-Once SDKMAN! is installed, use it to install the latest version of Scala 2.13:
+Once SDKMAN! is installed, use it to install the latest version of Java:
 
 [source,console]
 ----

modules/hello-world/pages/start-using-sdk.adoc

@@ -42,6 +42,10 @@ We'll explore creating and retrieving data records in more detail <<create-read-
 (and touch lightly upon a little of Java's functional programming approach as we go), 
 after walking through a quick installation.
 
+TIP: This page walks you through a quick installation, and CRUD examples against the Data Service.
+Elsewhere in this section you can find a fully worked-through xref:hello-world:sample-application.adoc[] and,
+for those new to document (NoSQL) databases, our xref:hello-world:student-record-developer-tutorial.adoc[Student Record Tutorial].
+
 
 == Before You Start