Getting Started with Maven

Kiji is intended to be used as a library within your own Java project. You should include KijiSchema and its dependencies on your project’s classpath when compiling and running your application.

We develop Kiji using Apache Maven, a build lifecycle and dependency management system. We encourage you to use Maven to develop your own application as well; you can use our Maven repository (a collection of release artifacts and dependencies) to incorporate KijiSchema and other dependencies in your system.

If you clone the Kiji source code from github, you will need to use Maven to build the projects. Each Maven project specifies its dependencies and build configuration in its POM file. These projects are auto-configured to retrieve their dependencies from our Maven repository.

Configuring your Build Environment

You can configure your own build environment to search our Maven repository when compiling your own applications.

Create a file named $HOME/.m2/settings.xml and include the following text:

<?xml version="1.0" encoding="UTF-8"?>
<settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd" xmlns="http://maven.apache.org/SETTINGS/1.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <profiles>
    <profile>
      <repositories>
        <repository>
          <id>kiji-repos</id>
          <name>kiji-repos</name>
          <url>https://repo.wibidata.com/artifactory/kiji</url>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
          <id>kiji-plugins</id>
          <name>kiji-plugins</name>
          <url>https://repo.wibidata.com/artifactory/kiji</url>
        </pluginRepository>
      </pluginRepositories>
      <id>kiji-profile</id>
    </profile>
  </profiles>
  <activeProfiles>
    <activeProfile>kiji-profile</activeProfile>
  </activeProfiles>
</settings>

If you already have a settings.xml, be sure to add the <repository> and <pluginRepository> to your existing profile.

You can depend on each module (KijiSchema, KijiMR, etc) individually. But if you are depending on many such modules, it can be difficult to ensure that you have selected compatible versions of each.

Including The Entire Kiji Framework

The easiest way to get started is to declare a direct dependency on the entire Kiji framework. This will include all Kiji client artifacts as part of your project’s dependencies. This may be more artifacts than you require, but is the simplest way to get started.

To depend on the entire framework:

<dependencies>
  ...

  <dependency>
    <groupId>org.kiji.framework</groupId>
    <artifactId>kiji-framework</artifactId>
    <version>1.0.3</version>
    <scope>provided</scope>
  </dependency>

  ...
</dependencies>

This will automatically depend on the kiji-cdh4-platform. You can choose a different platform if you’d like by explicitly depending on one.

Selecting Individual Modules

If you want to have control over which individual modules are included in your project, you should declare the following as the parent pom:

<parent>
  <groupId>org.kiji.framework</groupId>
  <artifactId>framework-pom</artifactId>
  <version>1.0.3</version>
</parent>

This includes a <dependencyManagement> section that describes the version numbers of compatible Kiji framework components. Your pom file’s <dependencies> section can then include just the groupId and artifactId components for each dependency; the version will be populated from the parent pom.

For example:

<dependency>
  <groupId>org.kiji.schema</groupId>
  <artifactId>kiji-schema</artifactId>
</dependency>

You will still need to specify which components you rely on. e.g., KijiSchema, KijiMR, etc. You must also select a kiji-platform definition to specify which versions of Hadoop and HBase you want to use.

For example:

<dependency>
  <groupId>org.kiji.platforms</groupId>
  <artifactId>kiji-cdh4-platform</artifactId>
</dependency>

Because you typically launch Kiji applications by running bin/kiji jar /path/to/example.jar, you can list KijiSchema, KijiMR, etc. as provided dependencies; the runtime environment will provide the implementation jars, so you do not need to bundle them in your application. If you intend to bundle your application (e.g., for deployment within a Tomcat container), you should list your scope as:

      <scope>compile</scope>

KijiSchema depends on both Hadoop and HBase, but supports multiple versions of each. To include consistent versions of Hadoop and HBase as transitive dependencies of your application, you should also list a provided-scope dependency on a Kiji platform, like kiji-cdh4-platform. This ensures that Hadoop and HBase (and their dependencies) will automatically be included in the set of dependencies for your application too.

For an example application (and in particular, pom.xml file), see the source code for the Kiji phonebook example.

Nightly builds

Developers who wish to work on Kiji itself, or want to test Kiji features still under development in their applications should also enable access to the nightly builds, published by our continuous integration server. Add the following <repository> definition to your settings.xml file to enable access to nightly SNAPSHOT builds of artifacts:

        <repository>
          <id>kiji-nightly</id>
          <name>kiji-nightly</name>
          <url>https://repo.wibidata.com/artifactory/kiji-nightly</url>
        </repository>

Note that these builds are highly unstable and should not be used unless you plan to modify Kiji projects directly. Bugs in nightly builds may cause serious problems, including data loss.