Developer Tutorial: Student Record System

<?xml version="1.0" encoding="UTF-8"?>
<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>

    <groupId>org.example</groupId>
    <artifactId>couchbase-java</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>16</maven.compiler.source>
        <maven.compiler.target>16</maven.compiler.target>
        <encoding>UTF-8</encoding>
        <project.build.sourceEncoding>${encoding}</project.build.sourceEncoding>
        <project.reporting.outputEncoding>${encoding}</project.reporting.outputEncoding>
        <project.resources.sourceEncoding>${encoding}</project.resources.sourceEncoding>
        <archetype.encoding>${encoding}</archetype.encoding>
    </properties>

    <!-- The `<dependencies>` section of the code block lists all the libraries required to build your application. In the case of the student record tutorial, you only need the Couchbase client SDK and Log4J. -->
    <dependencies>
        <dependency>
            <groupId>com.couchbase.client</groupId>
            <artifactId>java-client</artifactId>
            <version>3.8.0</version>
        </dependency>
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
            <version>2.0.9</version>
        </dependency>
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-simple</artifactId>
            <version>2.0.9</version>
        </dependency>
    </dependencies>

</project>

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();
    }
}

mvn exec:java -Dexec.mainClass="ConnectStudent" -Dexec.cleanupDaemonThreads=false

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);

    }
}

mvn exec:java -Dexec.mainClass="InsertCourses" -Dexec.cleanupDaemonThreads=false

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);

    }
}

mvn exec:java -Dexec.mainClass="AddEnrollments" -Dexec.cleanupDaemonThreads=false