Paths are references to sources of data. They are similar in concept to file system paths used to access files or XPath expressions used to access data in a structured document. All access to data of any kind from a renderer is performed via paths. Paths can be used to access the values of server interface properties, text in localized properties files, localized properties resources in the database and other values. The terminology used to describe the parts of a path is shown in the figure below.
- Prefix Path
- Selector
- Predicate
- Step
- Extended Path
The above path can be read as follows:
- The prefix path identifies the type of the data source. Here, /data/si indicates that it is a reference to the data of a server interface property.
- The following two path steps identify the name of the server interface (as declared in the UIM) and the full name of the property. Here, the dtls$list$address property of the DISPLAY server interface is referenced.
- A path step may have a selector or a selector followed by one or more predicates. The predicate is used to qualify the data identified by the path up to that point. Here, the predicate [1] is used to select the first address from the list of addresses in the property. Where predicates are used as numeric indexes, the index of the first value is one, as in XPath.
- An individual value of a server interface list property is selected by the first four steps of the path. The fifth step, ADD1, is the beginning of an extended path that will be resolved, not by the DataAccessor, but by the domain marshal plug-in associated with the domain of the identified server interface property. Here, ADD1 may, if the marshal is the SimpleXPathMarshal described in Extending Paths for XML Data Access, select the value of an ADD1 element in an XML document that is the value of the server interface property.
For more information about the general structure of paths and their manipulation in code, refer to the Javadoc for the Path and Step interfaces in the curam.util.common.path package.
The Field object passed to a render method contains a Binding object that specifies a source path and/or a target path. Renderer plug-ins do not need to be concerned about the form of these paths, or what type of data sources they reference; renderer plug-ins only need to resolve these paths to their values and should do so without inspecting the paths or depending on then being in any particular form. It is this unquestioning processing of any given path that allows renderer plug-ins to be reused easily in many different contexts and in rendering cascades.
Renderer plug-ins resolve paths the DataAccessor object available from the RendererContext object passed to the render method. There are a number of DataAccessor methods that can be called. They all take a single path argument:
- get(Path)
- Gets the formatted text value of the data. For domain-specific data, this is the value returned by the format method of the converter plug-in for that domain.s
- getRaw(Path)
- Gets the raw value of the data. For domain-specific data, this is the value passed to the format method of the converter plug-in. The type of the value is also the same as the type returned by the parse method of the converter plug-in.
- getList(Path)
- Gets the list of formatted text values of the data.
- getRawList(Path)
- Gets the list of raw values of the data.
- count(Path)
- Gets a count of the number of values that will be returned by getList or getRawList.
Where the data is not domain-specific, such as the contents of a properties file, the getRaw method usually returns the same string value as the get method. Some data sources may only support a subset of these methods. The get method is always supported, but the getList, getRawList and count methods may not be supported for all data sources. There are other methods on the DataAccessor, but their use is not supported in the Cúram application.