Build and Run

      +

      Description — Build and run a starter app to validate your install of Couchbase Lite on Java
      Abstract — This content provides sample code and instructions that enable you to test your Couchbase Lite for java installation.
      Related Content — Install | Prerequisites | Build and Run |

      Build a Getting Started App

      This section explains how to validate your configured build environment by building a starter app that uses many of Couchbase Lite’s more common features.

      The GettingStarted app demonstrates how to use Couchbase Lite. Console and Web App versions are available.

      Example 1. Development-type Scenarios
      Desktop App
      Ensure you added the Couchbase Lite dependency to your build.gradle file

      Create, build and run a new project using the following GettingStarted.java code:

      
      private void getStarted() throws CouchbaseLiteException, URISyntaxException {
          (1)
          // One-off initialization
          CouchbaseLite.init();
          System.out.println("CBL Initialized");
      
          (2)
          // Create a database
          Database database = new Database("mydb");
          System.out.println("Database created: mydb");
      
          (3)
          // Create a new collection (like a SQL table) in the database.
          Collection collection = database.createCollection("myCollection", "myScope");
          System.out.println("Collection created: " + collection);
      
          (4)
          // Create a new document (i.e. a record)
          // and save it in a collection in the database.
          MutableDocument mutableDoc = new MutableDocument()
              .setString("version", "2.0")
              .setString("language", "Java");
          collection.save(mutableDoc);
      
          (5)
          // Retrieve immutable document and log the database generated
          // document ID and some document properties
          Document document = collection.getDocument(mutableDoc.getId());
          if (document == null) {
              System.out.println("No such document :: " + mutableDoc.getId());
          }
          else {
              System.out.println("Document ID :: " + document.getId());
              System.out.println("Learning :: " + document.getString("language"));
          }
      
          (6)
          // Retrieve and update a document.
          document = collection.getDocument(mutableDoc.getId());
          if (document != null) {
              collection.save(document.toMutable().setString("language", "Kotlin"));
          }
      
          (7)
          // Create a query to fetch documents with language == "Kotlin"
          Query query = QueryBuilder.select(SelectResult.all())
              .from(DataSource.collection(collection))
              .where(Expression.property("language")
                  .equalTo(Expression.string("Kotlin")));
      
          try (ResultSet rs = query.execute()) {
              System.out.println("Number of rows :: " + rs.allResults().size());
          }
      
          //  (8)
          // OPTIONAL -- if you have Sync Gateway Installed you can try replication too
          // Create a replicator to push and pull changes to and from the cloud.
          // Be sure to hold a reference somewhere to prevent the Replicator from being GCed
          if (SG_URI != null) { replicator = startRepl(SG_URI, collection); }
      }
      
      private Replicator startRepl(String uri, Collection collection) throws URISyntaxException {
          CollectionConfiguration collConfig = new CollectionConfiguration()
              .setPullFilter((doc, flags) -> "Java".equals(doc.getString("language")));
      
          ReplicatorConfiguration replConfig = new ReplicatorConfiguration(
              new URLEndpoint(new URI(uri)))
              .addCollection(collection, collConfig)
              .setType(ReplicatorType.PUSH_AND_PULL)
              .setAuthenticator(new BasicAuthenticator("sync-gateway", "password".toCharArray()));
      
          Replicator repl = new Replicator(replConfig);
      
          // Listen to replicator change events.
          // Use `token.remove()` to stop the listener
          ListenerToken token = replicator.addChangeListener(change -> {
              System.out.println("Replicator state :: " + change.getStatus().getActivityLevel());
          });
      
          // Start replication.
          repl.start();
      
          return repl;
      }
      1 Initialize the library
      2 Create a database
      3 Create a collection
      4 Create a new document
      5 Retrieve document and log its ID
      6 Retrieve the document as mutable and change the language to Kotlin and save it
      7 Query the database output count and id to log
      8 Optionally, initiate a replication

      On running the app, you should see the document ID and property printed to the console together with a query result showing the number of rows in the database.

      This shows the document was successfully persisted to the database.

      See [About the Getting Started App] for more on the app itself

      Web App

      This section explains how to set-up a build project to create Couchbase Lite web apps using gradle and Intellij IDEA.

      Steps

      1. Create a new project folder and add a build.gradle file similar to this one.

        include::example$GetStartedWS/build.gradle.sample
      2. Within Intellij IDEA, open the new project folder

        If you don’t have auto-import enabled, then accept the Import from Gradle prompt that appears at the bottom right of the screen.

      3. Create a Java class DBManager using this code:

        
        (1)
        // One-off initialization
        private void init() {
            CouchbaseLite.init();
        }
        
        (2)
        // Create a database
        public Database createDb(String dbName) throws CouchbaseLiteException {
            return new Database(dbName);
        }
        
        (3)
        // Create a new named collection (like a SQL table)
        // in the database's default scope.
        public Collection createCollection(Database database, String collName) throws CouchbaseLiteException {
            return database.createCollection(collName);
        }
        
        (4)
        // Create a new document (i.e. a record)
        // and save it in a collection in the database.
        public String createDoc(Collection collection) throws CouchbaseLiteException {
            MutableDocument mutableDocument = new MutableDocument()
                .setFloat("version", 2.0f)
                .setString("language", "Java");
            collection.save(mutableDocument);
            return mutableDocument.getId();
        }
        
        (5)
        // Retrieve immutable document and log the database generated
        // document ID and some document properties
        public Document retrieveDoc(Collection collection, String docId) throws CouchbaseLiteException {
            return collection.getDocument(docId);
        }
        
        (6)
        // Retrieve and update a document.
        public void updateDoc(Collection collection, String docId) throws CouchbaseLiteException {
            Document document = collection.getDocument(docId);
            if (document != null) {
                collection.save(
                    document.toMutable().setString("language", "Kotlin"));
            }
        }
        
        (7)
        // Create a query to fetch documents with language == Kotlin.
        public List<Map<String, Object>> queryDocs(Collection collection) throws CouchbaseLiteException {
            Query query = QueryBuilder.select(SelectResult.all())
                .from(DataSource.collection(collection))
                .where(Expression.property("language").equalTo(Expression.string("Kotlin")));
            List<Map<String, Object>> results = new ArrayList<>();
            try (ResultSet rs = query.execute()) {
                for (Result result: rs) { results.add(result.toMap()); }
            }
            return results;
        }
        
        (8)
        // OPTIONAL -- if you have Sync Gateway Installed you can try replication too.
        // Create a replicator to push and pull changes to and from the cloud.
        // Be sure to hold a reference somewhere to prevent the Replicator from being GCed
        public Replication startReplicator(Collection collection, ReplicatorChangeListener listener)
            throws URISyntaxException {
            CollectionConfiguration collConfig = new CollectionConfiguration()
                .setPullFilter((doc, flags) -> "Java".equals(doc.getString("language")));
        
            ReplicatorConfiguration replConfig =
                new ReplicatorConfiguration(
                    new URLEndpoint(new URI("ws://localhost:4984/getting-started-db")))
                    .addCollection(collection, collConfig)
                    .setType(ReplicatorType.PUSH_AND_PULL)
                    .setAuthenticator(new BasicAuthenticator("sync-gateway", "password".toCharArray()));
        
            Replicator replicator = new Replicator(replConfig);
        
            // Listen to replicator change events.
            // Use `token.remove()` to stop the listener
            ListenerToken token = replicator.addChangeListener(listener);
        
            // Start replication.
            replicator.start();
        
            return new Replication(replicator, token);
        }
      4. Create a Servlet similar to the one found in the example GettingStartedServlet

      5. Create an index.html file in src/main/web app with the following content:

        include::example$GetStartedWS/src/main/webapp/index.html
      6. Create a showDbItems.jsp file in src/main/web app with the following content:

        include::example$GetStartedWS/src/main/webapp/showDbItems.jsp
      7. Build, deploy and run the app using jettyRun

        GradleMenuWebApp
        1. Point your browser to: `localhost:8080/'

          This opens the browser at your index.html page.

        2. Select the here link

          This launches the servlet and displays the results in showdDbItems.jsp.

      + About the Starter App::

      +

      The GettingStarted app will:

      • Create a database

        The app creates its database in the /getting-started.cblite2 directory relative to its root location when run (See: Finding a Database File).

      Explicitly state your required database location when creating your database (see: Finding a Database File for how to do this)
      • Add content to the DB

      • Run a simple query counting the DB rows

      • Start a one-shot, bi-directional replication using Sync Gateway and _Couchbase Server

      • Produce a simple report on the db Contents

        cblOutput
      Before starting your app ensure you have started both your Couchbase Server and _Sync Gateway instances.