The Jena FileManager and LocationMapper

The FileManager is a utility to find and read files into models. There is a standard global FileManager and applications may also define specific ones by constructing addition FileManagers.

The LocationMapper provides alternative locations for RDF data.

The File Manager

Files are named by a string, according to the conventions of their storage system. Typically this is by URI. There are a number of storage system adapters provided:

  • File locator (with own current directory)
  • URL locator
  • Class loader locator
  • Zip file locator

The global file manager has a file location, a URL locator and a class loader (tried in that order). A FileManager can have an associated LocationMapper that transforms names before use. This means local copies of documents can be used transparently to the rest of the application.

There are two categories of operations: loadModel, readModel. Load operations fetch and parse the data into a new memory model. Read operations fetch and parse the data into an existing model. For more complex ways to create a new model see the Assembler documentation.

Each FileManager has an optional in-memory cache of models. When on, loading models will look in the cache first and return a cached model if possible. This cached model is not copied - updates will change the cached version. The default is that cache is off.

In fetching and parsing a file, the file manager will attempt to guess the serialization format, if not explicitly supplied. This is by name extension:

  • .rdf and .owl : RDF/XML
  • .n3 : N3
  • .nt : N-Triples
  • Anything else: RDF/XML

The LocationMapper configuration file

This example uses the RDF subset of N3. Jena has an RDF reader and RDF writer for N3. This is nearly the same as Turtle but allowing international characters and some restrictions due to N3.

Location mapping files are RDF - they may be written in RDF/XML, N3 (file suffix .n3) or N-Triples (file suffix .nt). The default is RDF/XML unless one of these suffices is found.

@prefix lm: <http://jena.hpl.hp.com/2004/08/location-mapping#> .

[] lm:mapping
   [ lm:name "file:foo.n3" ;     lm:altName "file:etc/foo.n3" ] ,
   [ lm:prefix "file:etc/" ;     lm:altPrefix "file:ETC/" ] ,
   [ lm:name "file:etc/foo.n3" ; lm:altName "file:DIR/foo.n3" ]
   .

There are two types of location mapping: exact match renaming and prefix renaming. When trying to find an alternative location, a LocationMapper first tries for an exact match; if none is found, the LocationMapper will search for the longest matching prefix. If two are the same length, there is no guarantee on order tried; there is no implied order in a location mapper configuration file (it sets up two hash tables).

In the example above, file:etc/foo.n3 becomes file:DIR/foo.n3 because that is an exact match. The prefix match of file:/etc/ is ignored.

All string tests are done case sensitively because the primary use is for URLs.

Notes:

  • Property values are not URIs, but strings. This is a system feature, not an RDF feature. Prefix mapping is name rewriting; alternate names are not treated as equivalent resources in the rest of Jena. While application writers are encouraged to use URIs to identify files, this is not always possible.
  • There is no check to see if the alternative system resource is equivalent to the original.

A LocationMapper finds its configuration file by looking for the following files, in order:

  • file:location-mapping.rdf
  • file:location-mapping.n3
  • file:etc/location-mapping.rdf
  • file:etc/location-mapping.n3

This is a specified as a path - note the path separator is always the character ';' regardless of operating system because URLs contain ':'.

Applications can also set mappings programmatically. No configuration file is necessary.

The base URI for reading models with the FileManager will be the original URI, not the alternative location.

Debugging

Using log4j, set the logging level of the classes: org.apache.jena.util.FileManager=ALL org.apache.jena.util.LocationManager=ALL

See also

Javadoc: FileManager LocationMapper