Contents |
Documentation
You can generate javadoc for Fresnel by running mvn javadoc:javadoc, which puts all the generated files in TRUNKROOT/target/site/apidocs/; start browsing at index.html. The documentation should be up to date, but it's not been rigorously checked.
Basic Use
The expected use for the Fresnel engine is to read in ontologies, read in a configuration, then apply the configuration to various granularities of data (i.e., one resource, or several resources, or a complete graph) with some optional parameters, resulting in the output of a DOM tree. The transformation of the tree is expected to be accomplished with XSLT, if that transformation is required. Skip to the example if you learn better by reading code instead of words.
Construction
The edu.mit.simile.fresnel.configuration.Configuration class contains the actual Fresnel configuration. The prototype is:
public Configuration(org.openrdf.sesame.repository.Repository configuration,
org.openrdf.sesame.repository.Repository ontologies)
That is, the configuration needs to have been read into a Sesame repository, and the ontologies need to have been read into a separate repository. The constructor parses the configuration into an internal representation. It will throw a ParsingException if the vocabulary is unparseable and an UnresolvableException if it can be parsed but does not make enough sense to be automatically resolved.
Selection
Once the configuration object has been instantiated, it can be applied to subsets of an existing data graph using the select() method, of which there are five variants for granularity and other selection options.
public Selection select(org.openrdf.sesame.repository.Repository in)
Use the above for picking resources out of the existing in graph as well as selecting which properties go with each resource.
public Selection select(org.openrdf.sesame.repository.Repository in,
edu.mit.simile.fresnel.configuration.Group grouping)
Pick resources out of a graph using only those lenses contained in the specified fresnel:Group.
public Selection select(org.openrdf.sesame.repository.Repository in,
org.openrdf.model.Resource focus)
Use whatever lenses apply to the specified rdfs:Resource.
public Selection select(org.openrdf.sesame.repository.Repository in,
org.openrdf.model.Resource focus,
edu.mit.simile.fresnel.configuration.Group grouping)
Use whatever lenses apply to the specified rdfs:Resource, but only those that are contained in the specified fresnel:Group.
public Selection select(org.openrdf.sesame.repository.Repository in,
org.openrdf.model.Resource focus,
edu.mit.simile.fresnel.configuration.Group grouping,
edu.mit.simile.fresnel.purpose.Purpose purpose)
Use whatever lenses apply to the specified rdfs:Resource, but only those that are contained in the specified fresnel:Group and have the specified fresnel:Purpose.
All five return a edu.mit.simile.fresnel.results.Selection object, which is the input to the formatting step.
Format
There is one format() method. If you specified a group in the selection phase, the same group will be used in the formatting phase.
public Selection format(org.openrdf.sesame.repository.Repository in,
Selection select)
The output is an augmented Selection object.
DOM Output
The Selection object can be turned into a DOM tree at any time by calling the render() method, which outputs an org.w3c.dom.Document.
Example
The following example is derived from Longwell, in the edu.mit.simile.longwell.command.ViewCommand class.
1 Configuration conf = LongwellServlet.getLongwellService().getFresnelConfiguration(); 2 Repository allData = (Repository) msg.getProfile().getRepository(); 3 Selection selected = conf.select(allData, (Resource) obj); 4 selected = conf.format(allData, selected); 5 Document src = selected.render(); 6 Transformer transformer = LongwellServlet.getLongwellService().getTemplates().newTransformer(); 7 transformer.setOutputProperty(OutputKeys.INDENT, "yes"); 8 StringWriter stringOut = new StringWriter(); 9 StreamResult result = new StreamResult(stringOut); 10 transformer.transform(new DOMSource(src), result);
Per-line explanation:
- The configuration is read in when the Longwell server starts and is available through an accessor.
- How Longwell makes its data available as a Repository.
- The Longwell rendering is per-resource so it uses the per-resource selection method.
- Formatting the selection tree.
- Rendering the selected and formatted result to a DOM tree.
The rest of the lines transform the DOM tree using XSLT down to a string, stringOut. In Longwell, this string is then placed in a Velocity template for final display to the user.
Advanced Use
This section is for users who intend to use the engine more directly, in less of a black box fashion.
Parsing
Configuration.parse() is a private method. It looks for key properties in the Fresnel vocabulary to find parseable statements - not resources with a certain type. While typing resources like lenses is extremely useful overall, the parser is most concerned with properties and makes the following inferences about how to parse the subject, unless otherwise noted; most are in the Fresnel namespace:
| Property | Inferred type | Class |
|---|---|---|
| instanceLensDomain | InstanceLens | edu.mit.simile.fresnel.selection.InstanceLens
|
| classLensDomain | ClassLens | edu.mit.simile.fresnel.selection.Lens
|
| propertyFormatDomain | PropertyFormat | edu.mit.simile.fresnel.format.Format
|
| instanceFormatDomain | InstanceFormat | edu.mit.simile.fresnel.format.InstanceFormat
|
| classFormatDomain | ClassFormat | edu.mit.simile.fresnel.format.ClassFormat
|
| group | object as Group | edu.mit.simile.fresnel.configuration.Group
|
| SIMILE FSL-specific | ||
| abbreviated | namespace mapping | N/A |
| SIMILE-specific | ||
| facets | FacetSet | edu.mit.simile.fresnel.facets.FacetSet
|
| hides | FacetSet | edu.mit.simile.fresnel.facets.FacetSet
|
Once a type is determined, the subject is passed to each Java class's static implementation of parse(), and an instantiation of the class is returned.
Groups
A fresnel:Group is represented by edu.mit.simile.fresnel.configuration.Group. The Group is meant to bind lenses and formats that work well together into one resource. Each lens and format points to the group (or groups) it's associated with. Furthermore, groups may contain additional information regarding default styles and formats for resources, properties, property labels, and values, along with links to CSS stylesheets, and a list of classes that are considered 'primaries,' the first-class citizens in the data (e.g., foaf:Persons contain references to address resources which aren't listed alongside the people).
