The Location API

1 Definition

This API allows developers to easily write data to, or read data from various sources: JVM heap, file system, URL or Maven central artifacts. It is based on the Location interface , which provides the following methods:

public interface Location<T> {
  // Copy the content at this location to another location
  <V> Location<V> copyTo(Location<V> location);
  // Obtain an input stream to read from this location
  InputStream getInputStream();
  // Obtain an output stream to write to this location
  OutputStream getOutputStream():
  // Get this location's path
  T getPath();
  // Get the size of the data this location points to
  long size();
  // Get the content at this location as an array of bytes
  byte[] toByteArray() throws Exception;
}

2 Built-in implementations

2.1 FileLocation

FileLocation represents a path in the file system.

Usage examples:

// create a location pointing to the source file:
Location<String> src = new FileLocation("/home/user/docs/some_file.txt");
// copy the source file to a new location and get the new location
Location<String> dest = src.copyTo(new FileLocation("/home/user/other_file.txt"));

2.2 URLLocation

URLLocation can be used to get data to and from a URL, including HTTP and FTP URLs

Example:

// create a location pointing to a file on an FTP server
Location<URL> src = new URLLocation("ftp://user:password@ftp.host.org/path/myFile.txt");
// download the file from the FTP server to the local file system
Location<String> dest = src.copyTo(new FileLocation("/home/user/destFile.txt"));

2.3 MavenLocation

MavenLocation is an extension of URLLocation which allows downloading Maven artifacts from a Maven repository. Contrary to other Location implementations, this one does not permit uploading data. To enforce this, its getOutputStream() method will always throw an UnsupportedOperationException.

Examples:

// URL to a local repository on the file system
String repositoryURL = "file:///home/me/.m2/repository";

// a location that points to a Maven artifact with default "jar" packaging in the local repository
Location<URL> jar = new MavenLocation(repositoryURL, "org.jppf:jppf-client:6.0-SNAPSHOT");
// copy the artifact to the file system
jar.copyTo(new FileLocation("lib/jppf-client-5.2.9.jar"));

// create a location that points to a Maven artifact with "war" packaging
Location<URL> war = new MavenLocation(repositoryURL, "org.jppf:jppf-admin-web:6.0", "war");
// copy the artifact to the file system
jar.copyTo(new FileLocation("tomcat-7.0/webapps/JPPFWebAdmin.war"));

2.4 MavenCentralLocation

MavenCentralLocation is a convenience Location implemented as a specialization of MavenLocation, where the URL of the Maven repository is implicitely specified as that of the Maven Central repository. As for MavenLocation, it does not permit uploading artifacts to the repository.

Examples:

// create a location that points to a Maven artifact with default "jar" packaging
Location<URL> jar = new MavenCentralLocation("org.jppf:jppf-client:5.2.9");
// copy the artifact to the file system
jar.copyTo(new FileLocation("lib/jppf-client-5.2.9.jar"));

// create a location that points to a Maven artifact with "war" packaging
Location<URL> war = new MavenCentralLocation("org.jppf:jppf-admin-web:6.0", "war");
// copy the artifact to the file system
jar.copyTo(new FileLocation("tomcat-7.0/webapps/JPPFWebAdmin.war"));

2.5 MemoryLocation

MemoryLocation represents a block of data in memory that can be copied from or sent to another location.

Example:

MyClass object = ...;
try (ByteArrayOutputStream baos = new ByteArrayOutputStream();
     ObjectOutputStream oos = new ObjectOutputStream(baos)) {
  // serialize the object
  oos.writeObject(object);
  oos.flush();
  // store the serialized object in a memory location
  Location<byte[]> dataLocation = new MemoryLocation(baos.toByteArray());
  // copy the serialized object to a file
  dataLocation.copyTo(new FileLocation("/home/user/store/object.ser"));
} catch (Exception e) {
  e.printStackTrace();
}

3 Related reference

The location API is notably used to specify a classpath in a job SLA.