Resource API¶

ResourceStore¶

Used to manage configuration storage (file system, test harness, or database blob).

InputStream used to access configuration information:

Properties properties = new Properties();
try (InputStream in = resourceStore.get("module/configuration.properties").in() ){
  properties.load(in);
}

An OutputStream is provided for storage (a Resource will be created as needed):

Properties properties = new Properties();
properties.put("hello","world");
try (OutputStream out = resourceStore.get("module/configuration.properties").out() ){
    properties.store( out, null );
}

A Resource can also be extracted to a file if needed:

File file = resourceStore.get("module/logo.png");
BufferedImage img = ImageIO.read( file );

The base directory is available using Paths.BASE (as "" but relative paths (. and .. are not supported). Path assumes a unix-like file system, all paths are relative and use forward slash {@code /} as the separator.

Resource¶

Resource used for configuration storage. Described by getType() as a Type.DIRECTORY, Type.RESOURCE, or are considered Type.UNDEFINED.

Resource contents are streamed using out() and in() methods. The entire contents can be managed in one go using setContents(bytes) and getContents().

try (OutputStream out = resource.out() ){
   properties.store(out)
}

Resource path() provides the complete path relative to the ResourceStore base directory. Use name() to retrieve the resource name (as the last component in the path name sequence).

Resource creation is handled in a lazy fashion, use file() or out() and the resource will be created as required.

Use dir() to create a empty directory. Directories have the ability to list() their contents:

for( Resource child : resource.list()) {
   ...
}

When creating a resource with file(), out() or dir() any required parent directories are created to produce the completed path).

Once created resources can be managed with delete(), renameTo(resource) methods.

Resource supports addListener(listener) / removeListener(listener) event notification allowing code to watch a file for change. A single listener can watch for changes within a folder, with the events providing the path of changed files.

Resource lock() is also supported.

Paths¶

The Paths facade provides methods for working with the relative paths used by ResourceStore.

Helpful methods are provided for working with paths and names:

• name(path)

• extension(path)

• parent(path)

• sidecar(path, extension)

• names(path) processes the path into a list of names as discussed below.

The definition of a path has been expanded to work with the external locations (with Paths.isAbsolute(path) and Paths.names(path)).

Paths are broken down into a sequence of names, as listed by Paths.names(path):

• Path.names("data/tasmania/roads.shp") is represented as a list of data, tasmania, roads.shp.

• On linux Path.names("/src/gis/cadaster/district.geopkg") starts with a marker to indicate an absolute path, resulting in /, src, gis, cadaster, district.geopkg.

• On windows Path.names("D:/gis/cadaster/district.geopkg") starts with a marker to indicate an absolute path, resulting in D:/, gis, cadaster, district.geopkg.

Resources¶

The Resources facade provides lots of common activities for working with Resource.

Most of these perform common activities or check on resource status exists(resource), hidden(resource).

Resources methods provide the flexibility to work with with Resource while not getting caught out in the dfference between DIRECTORY and RESOURCE type.

if( Resources.exists(resource)) {
    // may be a file or a directory
    File fileLocation = Resources.find(resource);
    ...
}

There are also methods to copy contents into a resource:

Resources.copy( file, targetDirectory);

There are also method for working with directories recursively and filtering content:

for (Resource svg : Resources.list( resource, new ExtensionFilter("svg"), true )) {
   ...
}

Files¶

The Files facade provides methods for working with file objects, and one method of critical importace to the Resource API.

The Files.asResource(file) method creates a ResourceAdapter wrapper around an absolute file location. Allows the use of Resource API when working with content outside of the data directory.

GeoServerDataDirectory¶

GeoServerDataDirectory is a special ResourceStore allowing the use of catalog configuration objects to act as a reference point (rather than having to remember the structure of the data directory).

Resource icon = dataDirectory.get( workspaceInfo, "airports.svg");

GeoServerDataDirectory has plenty of methods that still provide direct file access, internally however they are implemented using the Resource API.

public File findDataRoot() throws IOException {
    Resource directory = get("data");
    return Resources.directory(directory);
}

GeoServerResourceLoader¶

The class GeoServerResourceLoader operates as a facade mimicking some of the early file based interaction in our codebase to help during the migration to the ResourceStore API.

The use of location parameters here can reference a relative location in the data directory, or an absolute file location on disk.

Each method here can be expressed using the utility classes:

// Using GeoServerResourceLoader to work with local file
File configuration = loader.createFile(location);
try (OutputStream out = new FileOutputStream(configuration)) {
    xstream.toXML(ogrConfiguration, out);
}

// Using Paths and Resources to work with local file
Resource resource = resources.get(Paths.convert(location));
File configuration = Resources.createNewFile(resource);
try (OutputStream out = new FileOutputStream(configuration)) {
  xstream.toXML(ogrConfiguration, out);
}

// Using Resource directly to work in clustered environment
Resource resource = resourceStore.get(Paths.convert(location));
try (OutputStream out = resource.out()) {
  xstream.toXML(ogrConfiguration, out);
}