Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Couchbase Lite on Java — Installing

      +

      Description — Couchbase Lite on Java — a framework for developing offline-first Java applications for mobile and edge
      Abstract — This content provides instructions that enable you to deploy Couchbase Lite on java
      Related Content — Install | Prerequisites | Build and Run

      Introduction

      Couchbase Lite on Java 3.1.6_ enables development and deployment of Couchbase Lite applications to a JVM environment. You can deploy Standalone (Java Desktop/Console) apps or Web Apps (using, for example, Tomcat; including embedded Tomcat deployments).

      Quick Steps

      For experienced developers, this is all you need to add Couchbase Lite for Java 3.1.6 to your application projects.

      • Enterprise Edition

      • Community Edition

      Include the following in your Gradle build.gradle or Maven pom.xml file, as appropriate:

      1. Include the Couchbase Lite for Java dependency in your Gradle build.gradle or Maven pom.xml file, as appropriate:
        couchbase-lite-java:3.1.6

      2. For Gradle:
        Check you have mavenCentral() in repositories (or in settings.gradle).
        Maven automatically checks its own repo for dependencies.

      for Linux, make sure you have followed the additional steps required.

      That’s it! You’re all set to begin developing powerful Couchbase Lite applications.

      Now, try the Getting Started application, which demonstrates use of key CRUD functionality.

      Preparing Your Build Environment

      This section shows how to set up and use Couchbase Lite on Java to build desktop and web applications using gradle, Maven, Tomcat and Intellij IDEA Community Edition. It assumes a familiarity with these products, however you are free to use your own choice of development tools.

      Binaries

      Couchbase Lite on Java binaries are available for both Community (CE) and Enterprise (EE) editions from the Maven repositories. Alternatively, you can download compressed binaries — see the Downloaded Binaries section in Prerequisites

      Prerequisites

      Standalone Apps

      Using Gradle

      1. Create a project folder

      2. Initialize it for a Gradle Java application

      3. Include the content shown in Example 1 in your app-level build.gradle file

      4. Open the project folder in Intellij IDEA and import the gradle settings.

        If you don’t have auto-import set for Gradle projects, then accept the Import Gradle Project prompt that is displayed bottom-right of the screen
        Note the Gradle menu at the extreme right of the screen:
        GradleMenuWebApp

      That’s it. You’re all set to start building your own Couchbase Lite on Java applications — see Build and Run for an example of how to do that.

      Example 1. build.gradle file content

      • Enterprise Edition

      • Community edition

      Compile options
      // Required only if your project has some Kotlin source code
kotlinOptions { jvmTarget = '1.8' }

// Set minimum JVM level to ensure availability of, for example, lambda expressions
compileOptions {
    targetCompatibility 1.8
    sourceCompatibility 1.8

//   ... other section content as required by user
}
      Dependencies
      dependencies {
    implementation "com.couchbase.lite:couchbase-lite-java:3.1.6"

//   ... other section content as required by user
}
      Repositories
      repositories {
    maven {url 'https://mobile.maven.couchbase.com/maven2/dev/'}

//   ... other section content as required by user
    }
      Compile options
      // Required only if your project has some Kotlin source code
kotlinOptions { jvmTarget = '1.8' }

// Set minimum JVM level to ensure availability of, for example, lambda expressions
compileOptions {
    targetCompatibility 1.8
    sourceCompatibility 1.8

//   ... other section content as required by user
}
      Dependencies
      dependencies {
    implementation "com.couchbase.lite:couchbase-lite-java:3.1.6"

//   ... other section content as required by user
}

      Using Maven

      1. Include the content shown in Example 2 in your pom.xml file in the root of your project folder

      2. That’s it — just add your own code

      You’re all set to start building your own Couchbase Lite on Java applications — see Build and Run for an example of how to do that.

      Example 2. pom.xml file content

      • Enterprise Edition

      • Community edition

      Compile properties
      <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>11</maven.compiler.source>
    <maven.compiler.target>11</maven.compiler.target>
</properties>
      Dependencies
      <dependencies>

    <dependency>
      <groupId>com.couchbase.lite</groupId>
      <artifactId>couchbase-lite-java-ee</artifactId>
      <version>3.1.6</version>
    </dependency>

    <!-- ... any other section content as required by user-home  -->
</dependencies>
      Repositories
      <repositories>
  <repository>
    <id>couchbase</id>
    <url>https://mobile.maven.couchbase.com/maven2/dev/</url>
  </repository>
  //   ... any other section content as required by user

</repositories>
      Compile properties
      <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>11</maven.compiler.source>
    <maven.compiler.target>11</maven.compiler.target>
</properties>
      Dependencies
      <dependencies>
  <dependency>
      <groupId>com.couchbase.lite</groupId>
      <artifactId>couchbase-lite-java</artifactId>
      <version>3.1.6</version>
  </dependency>

  //   ... any other section content as required by user
</dependencies>

      Web App Development

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

      Using Maven

      For examples of how to do this using Maven POM files, see — 

      Tomcat

      In our examples here we build and deploy web apps using a gradle plugin based on the com.bmuschko.tomcat plugin. It provides a simple Tomcat harness that can be used from within Intellij IDEA or the command-line — see Embedded Tomcat

      Multiple Web Apps

      Each web application has its own *class loader (WebappX). This loads the classes, jars, and resources found in the application’s WEB-INF/classes and WEB-INF/lib folders, together with any shared jar files from $CATALINA_BASE/lib — see tomcat documentation for more.

      So, if you are running multiple Couchbase Lite web applications, deploy your Couchbase Lite on Java library <pathToCbl>/libs to $CATALINA_BASE/lib. This means you do not need to deploy it in each web app and minimizes the size of each app.

      Configuring Couchbase Lite logging functionality will affect the logging of all web applications as the common class loader shares Couchbase Lite Console, File and Custom logging functionalities across all web apps.

      For information about building a WAR file see Deploying a WAR File

      Prerequisites

      • Ensure your build environment matches the runtime Tomcat environment. Specifically, that the Java and Tomcat versions are the same.

      • If your Tomcat server runs Linux, declare the shared libraries (<pathToCbl>/support) in the $CATALINA_HOME/bin/setenv.sh script file — see: Additional Steps for Linux section in Prerequisites.

      • Ensure the Couchbase Lite jars (<pathToCbl>/lib) are on the executable path within Tomcat — see: Multiple Web Apps

        This also means you should declare the dependencies as providedCompile to avoid them being bundled into the WEB-INF/libs folder

      Steps

      1. Create a project folder and initialize it for a Gradle Java application

        gradle init

      2. Create your build.gradle file, including the Example 3 in your app-level build.gradle:

      3. Open the project folder in Intellij IDEA and import the gradle settings.

      If you don’t have auto-import set for Gradle projects, then accept the Import Gradle Project prompt that is displayed bottom-right of the screen.
      Note the Gradle menu at the extreme right of the screen:
      image::GradleMenuWebApp.png[,300]

      If you want to deploy your app to a local tomcat container then see [Deploying a WAR file to tomcat]

      That’s it. You’re all set to start building your own Couchbase Lite on Java applications — see Building a Getting Started App for an example of how to do that.

      Example 3. build.gradle file content

      • Community

      • Enterprise

      dependencies {
    implementation "com.couchbase.lite:couchbase-lite-java:3.1.6"

//   ... other section content as required by user
}
      repositories {
    maven {url 'https://mobile.maven.couchbase.com/maven2/dev/'}

//   ... other section content as required by user
    }

dependencies {
    implementation "com.couchbase.lite:couchbase-lite-java-ee:3.1.6"

//   ... other section content as required by user
    }

      Embedded Tomcat

      The simplest way to build and deploy your Couchbase Lite on Java web app is to use a gradle plugin that provides a simple Tomcat harness.

      Our examples are based on the com.bmuschko.tomcat plugin — see com.bmuschko.tomcat on Github.

      Including the plugin in your build.gradle file make a number of tomcat tasks available to you. View them using:

      ./gradlew tasks

      This shows that the following web application tasks are now available:

      • tomcatJasper - Runs the JSP compiler and turns JSP pages into Java source.

      • tomcatRun - Uses your files as and where they are and deploys them to Tomcat.

      • tomcatRunWar - Assembles the web app into a war and deploys it to Tomcat.

      • tomcatStop - Stops Tomcat.

      So, to run the app use:

      ./gradlew tomcatRun

      Deploying a WAR File

      To deploy your web app to a local Tomcat instance you need to generate a WAR file. However, you should note that when creating a war file, if you use the implementation dependency type then your Couchbase Lite jar files will be bundled into WEB-INF/lib of the web application. To exclude Couchbase Lite jar files from getting bundled and to use Couchbase Lite in multiple web applications, change the dependency type from implementation to providedCompile

      1. You can do this using the Gradle command below from within your project folder:

        ./gradlew war
        The generated war file will be at <PROJECT ROOT>/build/libs.

      2. Deploy the war file to Tomcat, by copying it to $CATALINA_BASE/webapps

        You can also use Tomcat’s Manager App to deploy the war file — see Tomcat’s Manager App documentation for more detail.

      3. To use common class loader approach to load Couchbase Lite libraries, copy all of the Couchbase Lite jar files in $CATALINA_BASE/lib.

        For linux platform see also — Using Native Libraries for Linux in Prerequisites

      Related Content

      How to . . .
      Learn more . . .
      Dive Deeper . . .

      Mobile Forum | Blog | Tutorials