Home

Awesome

ph-diver

javadoc Maven Central

ph-diver - PH Digitally Versioned Resources - in collaboration with ecosio Logo

The modules contained in this repository provide access to versioned resources that reside on several external resource types like HTTP servers, local disks or in-memory data structures.

This library consists of the following submodules:

The reason why the several types of repositories are separated, is mainly because of specific runtime dependencies needed, and to avoid that your dependencies are bloated if you only need a specific kind of repository.

DVR Coordinate

The DVR Coordinate, short for Digitally Version Resource Coordinate, is an identifier for any technical artefact (file) very similar to Maven coordinates.

Hint: The original term was "VESID" which was very much focused on validation artefacts. Each VESID is a DVR Coordinate, but not vice versa. DVR Coordinate defines the syntax constraints required to be adhered to by all applications. The terminology was changed for version 2 (DVRID) and version 3 of the library.

DVR Coordinate Contents

Each DVR Coordinate consists of a combination of:

The limitations in the allowed characters for the different parts are meant to allow an easy representation on file systems.

DVR Coordinate string representation

Each DVR Coordinate can be represented in a single string in the form groupID:artifactID:version[:classifier].

The string representation of version numbers is a bit tricky, because 1, 1.0 and 1.0.0 are all semantically equivalent. Thats why it was decided, that trailing zeroes for minor and micro versions are NOT contained in the string representation, to be as brief as possible So e.g., for version 1.0.0 the string representation must be 1; for version 3.2.0, the string representation must be 3.2. Versions using a classifier like 3.0.0-SNAPSHOT are represented as 3-SNAPSHOT. Versions that only consist of a classifier like 0.0.0-XYZ are represented only as the classifier XYZ. That is a work around to be able to handle all kind of versions, but they are treated with a major version of 0, a minor version of 0 and a micro version of 0.

Repository

A repository is an abstract tree like structure to act as the source for artefacts (files).

Each repository item is uniquely addressed with a RepoStorageKey that basically is a path structure. The content of a repository item is represented via class RepoStorageItem.

A repository itself is represented as implementations of class IRepoStorage. Each repository is always readable, and optionally writable and optionally allows for deletion.

Several repositories may be chained together for reading. E.g., first the local file system is queried for a resource - if the artefact is not found locally, another remote repository might be used instead. The local caching of remote resources is also supported, to limit the necessity for external access.

Table of Contents per Group ID and Artefact ID

Since v1.0.1 a special "table of contents" (ToC) is supported per Group ID and Artefact ID. It contains all the versions of that combination and allows for easy access of the latest version, without iterating any directory structure. The filename used is toc-diver.xml per default.

An extended API is available for repository storage implementations via the IRepoStorageWithToc interface.

Maven usage

Add the following to your pom.xml to use e.g. the HTTP repository artifact, replacing x.y.z with the latest version:

<dependency>
  <groupId>com.helger.diver</groupId>
  <artifactId>ph-diver-repo-http</artifactId>
  <version>x.y.z</version>
</dependency>

Alternate usage as a Maven BOM:

<dependency>
  <groupId>com.helger.diver</groupId>
  <artifactId>ph-diver-parent-pom</artifactId>
  <version>x.y.z</version>
  <type>pom</type>
  <scope>import</scope>
</dependency>

News and Noteworthy

My personal Coding Styleguide | It is appreciated if you star the GitHub project if you like it.