2 Basic Concepts

2.1 Repositories

A repository is a collection of packages (usually libraries) and metadata about packages

• The metadata identifies
  • the package,
  • the versions available,
  • their dependencies on other packages, and
  • the location from which the package may be downloaded.
• In some cases, the metadata may point to other repositories as the actual download location.

2.1.1 Common Java Repositories

The Java world is dominated by

2.1.2 Local Repositories

It’s common for development organizations to host their own repository.

• A place to put their own deliverables
• A “cache” to speed access to libraries commonly used by many developers within the organization.
  • preserve older versions needed for a project baseline

Local repositories can be

2.2 Identifying Packages

Packages are typically identified by

• The group or organization

  • Generally given in the Java style of a reversed URL, e.g. org.apache.ant, edu.odu.cs.extract
  • Like some Hollywood celebrities, some organizations become big enough stars to be simply known by a single name, e.g., junit

• The artifact name

  • E.g., junit, hamcrest-core, apache-commons

• Version number

  • Single versions are identified exactly: 4.12
  • Depending on the build manger being used, you may be able to specify things like
    • 4.11+: 4.11 or later
    • latest.integration: latest official release
    • 1.2-SNAPSHOT: a version under development. The stapshot modifier serves as a notice that the actual package may be updated without a change in version number.

2.3 Scopes

Not every library that your project needs is needed all of the time.

• If your “main code” uses a library, you would need that during compilation, testing, and possibly packaging.
• Libraries like junit would only be needed when compiling and running the unit tests.
• Libraries like findbugs, checkstyle (discussed later in the semester) are only used during report generation.
• A build manager may support “plug-ins” that extend or modify the build process. These plug-ins are typically packaged much like other 3rd-party libraries, but are needed much earlier in the build process.

So build managers allow you to import libraries in selected scopes which indicate when the library is actually needed.

This affects

• Whether a library is downloaded or updated during a given build.
• Java CLASSPATH and other settings made available to the build steps.

3 Adding Libraries to a Java Project in Different Build Managers

3.1 Maven

3.1.1 Specifying a Dependency

• Examine the pom.xml file and look for the dependencies section.

• You’ll see something like

    <dependencies>
  	<groupId>junit</groupId>
  	<artifactId>junit</artifactId>
  	<version>4.10</version>
  	<scope>test</scope>
    </dependencies>
  
  

  • Could also say [4.12,] to get versions 4.12 or greater

3.1.2 Fetching Dependencies

When the build is run (e.g. mvn package):

• Maven does a transitive search over the dependencies for a project

  • Tries to find a mutually compatible set of versions
    • Helps if you give it some flexibility

• Maven then downloads the required libraries automatically

  • Downloaded libraries are cached (e.g., ~/.m2)

3.1.3 Transitive Dependencies

How does Maven know whether junit itself depends on other libraries?

3.1.4 Choosing Repositories

• Technically, our project has two repositories

  • a remote repository, at ibiblio
  • a local repository holding my cache

• Team projects will often employ an intermediate shared repository

  • reduce cache duplication
  • provide a mechanism for managing subproject modules
  • provide a common storage area for libraries not available on ibiblio
  • preserve older versions needed for a project baseline

3.1.5 Example: specifying a repository

In pom.xml:

  <repositories>
     <repository>
        <snapshots>
           <enabled>false</enabled>
        </snapshots>
        <id>central</id>
           <name>libs-release</name>
           <url>http://archive350.cs.odu.edu:8080/artifactory/libs-release</url>
    </repository>
  </repositories>

• We could then, for example, import early versions of zipdiff and trilead-ssh that were part of the baseline for the Extract project
  • At the time they were added to the project baseline, they were not in the remote Maven repository
  • As time has passed, those libraries were added, but have started with versions later than the project baseline

3.2 Ivy (ant)

3.2.1 Getting Started with Ivy

Again, let’s start with the build.xml for an Ant project.

E.g.,

3.2.2 Fetching Ivy

Start by having our build file actually load Ivy

3.2.3 Specifying our Desired Libraries

We list the libraries our project needs in a separate ivy.xml file

<ivy-module version="2.0">
  <dependencies>
    <dependency org="de.jflex" name="jflex" rev="1.4.3"/>
    <dependency org="junit" name="junit" rev="4.10"/>
  </dependencies>
</ivy-module>

This should look familiar to the section from the Maven pom:

  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.10</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
  

3.2.4 Invoking Ivy

Once Ivy is installed, we can invoke it:

3.2.5 Set Up Classpaths

… to use the newly downloaded libraries.

3.2.6 Ivy & Repositories

• Ivy can use most maven repositories.

• Choice of repositories is controlled by an ivysettings.xml file.

  • By default, uses the same ibiblio service that is Maven’s default.

An example of an ivysettings.xml file:

3.2.7 Ivy & Eclipse

3.3.1 Selecting libraries in Gradle

In build.gradle:

apply plugin: 'java'


⋮

repositories {
    jcenter()   ➀

    // Use my own CS dept repo
    ivy {      ➁
        url 'https://secweb.cs.odu.edu/~zeil/ivyrepo'
    }
}



dependencies { ➂
    compile 'net.sf.saxon:saxon-dom:8.7+'
    testCompile 'junit:junit:4.12'
    testRuntime 'edu.odu.cs.zeil:reportAccumulator:1.1+'

}

Here you see both the choice of libraries ➂ and of repositories ➀, ➁.

The dependencies indicate

• The scope (e.g., testCompile, which actually includes compiling and running of the unit tests)

• The package, specified as organization:package:versionNumber

4 Eclipse and Library Management

Each of the build/library managers we have discussed have support in Eclipse

• May provide special editors for editing the build manager configuration files.

• Provide ways to launch the build manager from within Eclipse

  • Sometimes it’s easier to launch separately in a separate window, e.g., from the command line from the Gradle GUI mode.

    • Remember to “refresh” the project in Eclipse afterwards

• Most importantly, allows Eclipse Java projects to use any 3rd-party libraries fetched by the build/library manager.

  • Otherwise the built-in Eclipse compilation and smart-editing features would mistakenly believe that your code was full of references to non-existent classes and funnctions.

• May allow some management of the cache of old libraries.

4.1 Eclipse and Maven

• Can also hope for convenience functions

  • In particular, POM editors

• Two plugins currently

  • m2eclipse, older plugin
  • Eclipse IAM

• Allows you to create new Maven projects or to import existing ones into Eclipse.

4.2 Eclipse and Ant/Ivy

4.3 Eclipse and Gradle

Eclipse has various Gradle plugins available.

The most popular seems to be the BuildShip package, available from the Gradle Marketplace (in the Eclipse Help menu).

• Allows import (only) of existing Gradle projects

• Allows launching Gradle from within Eclipse

  • from a special Gradle Tasks panel, not from the package explorer.

• Allows Eclipse Java projects to find 3rd-party libraries loaded by Gradle.

5 Complicating Factors

5.1 Plug-ins

Plug-ins to build managers are generally handled separately from other items, though the syntax is often similar.

• For example, in gradle, plug-ins are handled in a buildscript section:

  buildscript {
      repositories {
          jcenter()
      }
      dependencies {
          classpath 'org.hidetake:gradle-ssh-plugin:2.2.0+'
      }
  }
  

  • The syntax and options within the buildscript area are almost identical to the way we handle normal packages.

• Maven has a similar approach, isolating plug-ins in a <plugins> section.

5.2 Publishing

Publishing artifacts to a repository is also supported by maven, Ant/Ivy, & Gradle.

• Typically more complicated.

  • mainly because most repositories are open to download, but require login credentials to upload.

Example: in Gradle build.xml

publishing {
    publications {
        ivyJava(IvyPublication) {
            organisation 'edu.odu.cs.zeil'
            module 'cowem-plugin'
            revision project.version
            descriptor.status = 'integration'   // milestone, release
            descriptor.branch = 'v1'

            from components.java
        }
    }

    repositories {
        ivy {
            name 'ivyRepo'
            url 'sftp://atria.cs.odu.edu:22/home/zeil/secure_html/ivyrepo'
            // Readable via https://www.cs.odu.edu/~zeil/ivyrepo
            credentials {
                ⋮
            }
        }
    }
}

5.3 Login Credentials

Providing login credentials to a build is problematic.

• Can’t insert passwords into the build file, because the build file will be checked in to version control, so we would be publishing our credentials in plain view, for all time!

A common work-around is to store a few build “properties” in a file in the user’s home directory, not kept as part of the package version control.

Example: in Gradle build.xml

// Credentials are loaded from ~/.gradle/gradle.properties
if(project.hasProperty("ivyRepoUser")){        ➀
    ext.ivyRepoUser = "$ivyRepoUser";
} else {
    ext.ivyRepoUser = "user";
}
if(project.hasProperty("ivyRepoPass")){
    ext.ivyRepoPass = "$ivyRepoPass";
} else {
    ext.ivyRepoPass = "password";
}

⋮

publishing {
    ⋮
            credentials {                    ➁
                username project.ivyRepoUser
                password project.ivyRepoPass
            }
    ⋮
}

• ➀ looks to see if properties ivyRepoUser and ivyRepoPass were loaded from ~/.gradle/gradle.properties. If so, it adds them as “extension” properties of the current gradle project.

• ➁ passes those new extension properties as login credentials to a repository.

  • If the person running the build di not have a ~/.gradle/gradle.properties or it did not contain the properties ivyRepoUser and ivyRepoPassproeprties, then attempted uploads to the repository would use a default username and password that would, presumably, fail.