Tutorial Objective

The aim of this tutorial is to establish a good understanding of the local protocal and how it can be leveraged in build and runtime environments.

Definition of an Local Artifact

An local artifact is any streamable resource locatable using the local URL protocol. Examples of resources include - property files, XML files, files containing meta data, serialized objects, images, etc. The local protocol resolves uri value relative to the users local preferences directory - specifically ${dpml.prefs}. All resources in the prefs directory are maintained under the CLASSIC layout (i.e. ${dpml.prefs}/[group]/[name]-[VERSION].[TYPE] or ${dpml.prefs}/[group]/[name].[TYPE] for non-versioned resources). The protocol structure is as follows:

local:[type]:[group]/[name]

or:

local:[type]:[group]/[name]#[version]

To locate a resource Transit maps the [type], [group], [name], and [version] fields of the artifact URI to a URL using the CLASSIC layout.

Using Local Artifacts

The following code demonstrates the use of a local artifact to retrieve a property file from PREFS and supply it as an input stream to a Properties object. We construct a new URL using a local artifact specification that declares a resource type of "properties", a group named "dpml/test", with the name "example-property-file". We then pass the URLs resource stream to a new Property instance and print out the value of a property declared in the properties resource.

URL url = new URL( "local:properties:dpml/test/demo-property-file" );
InputStream input = url.openStream();
Properties properties = new Properties();
properties.load( input );
String message = properties.getProperty( "tutorial.message" );
System.out.println( message );