org.tinyjee.maven.dim.extensions
Class XmlLoader

java.lang.Object
  java.util.AbstractMap<K,V>
      java.util.HashMap<String,Object>
          org.tinyjee.maven.dim.extensions.XmlLoader

All Implemented Interfaces:

Serializable, Cloneable, Map<String,Object>

public class XmlLoader
extends HashMap<String,Object>

XmlLoader is a 'source-class' compatible helper class that can load and transform XML/JSON content and provide XPath and DOM oriented access to the document elements when used in combination with a velocity template.

The loader supports remote URLs (e.g. REST-services) and local paths to get the XML (or JSON) content (similar to the standard inclusion engine).

Use this loader when you want to access the parsed content of XML (or JSON) markup using the DOM API with the option to apply optional XSL transformations. This extension is not needed if your aim is to include code snippets that are selected using XPath expressions.

Usage:

%{include|source=template.vm|source-class=org.tinyjee.maven.dim.extensions.XmlLoader|xml=file.xml}

or when using the alias:

%{include|source=template.vm|source-xml=file.xml}

include XML after XSL transformation:

%{include|source-xml=file.xml|xsl=transform-to-html.xsl}

Author:

Juergen_Kellerer, 2011-10-06

See Also:

Serialized Form

Nested Class Summary

static class

XmlLoader.AliasHandler Implements the "PARAM_ALIAS" alias functionality.

Nested classes/interfaces inherited from class java.util.AbstractMap

AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>

Field Summary

static String	OUT_PARAM_DOCUMENT Is set with the parsed document object (Document) and can be accessed from velocity templates.
static String	OUT_PARAM_ORIGINAL_DOCUMENT Is set with the original parsed document as it existed before applying any transformations.
static String	OUT_PARAM_ORIGINAL_XPATH Is the same as "xpath" but configured to match on the original document.
static String	OUT_PARAM_SCHEMA_MAP If filled with a map of all loaded XML schemata (in case of schema loading is enabled).
static String	OUT_PARAM_XPATH Is set with an implementation of "XPathEvaluator" that is configured to match xpath expressions against DOM tree of document.
static String	PARAM_ADD_DECLARATION Optional parameter, enables the inclusion of the XML declaration (<?
static String	PARAM_ADD_XSL Optional parameter, sets a relative or absolute URL to an XSL file that is added as standard template to the document being included but it is not executed.
static String	PARAM_ALIAS Defines a shortcut for the request properties 'source-class' and 'xml'.
static String	PARAM_INDENT Optional parameter, toggles whether the XML is indented before inclusion.
static String	PARAM_JSON Experimental: Sets the URL or local path to JSON encoded content that is translated to XML and included.
static String	PARAM_LOAD_SCHEMA Enum parameter that specifies whether XML schemata are loaded in order to include them with the XML content.
static String	PARAM_NAMESPACE_AWARE Optional parameter, toggles whether the XML parser handles namespaces.
static String	PARAM_XML Sets the URL or local path to the XML file to load inside the request parameters.
static String	PARAM_XML_CLASS Sets a fully qualified class name to a class that either provides a Document instance, a Source or is annotated with XmlRootElement.
static String	PARAM_XSL Optional parameter, sets the path to an XSL file that is used to transform the given input.

Constructor Summary

XmlLoader(File baseDir, Map<String,Object> requestParams)
Constructs a new XML loader.

Method Summary

Methods inherited from class java.util.HashMap

clear, clone, containsKey, containsValue, entrySet, get, isEmpty, keySet, put, putAll, remove, size, values

Methods inherited from class java.util.AbstractMap

equals, hashCode, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

equals, hashCode

Field Detail

PARAM_ALIAS

public static final String PARAM_ALIAS

Defines a shortcut for the request properties 'source-class' and 'xml'.

If this parameter is present inside the request parameters list, the system will effectively behave as if 'source-class' and 'xml' where set separately.

See Also:

Constant Field Values

PARAM_XML

public static final String PARAM_XML

Sets the URL or local path to the XML file to load inside the request parameters.

The specified file is resolved in exactly the same way as when using the parameter "source" (see Macro reference).

Note: When no further source is specified, the xml loader sets the serialized representation of this file as the content that is included by the macro. If a source IS specified, the defined out parameters are set and allow DOM or XPath based access to the document structure.

See Also:

Constant Field Values

PARAM_XML_CLASS

public static final String PARAM_XML_CLASS

Sets a fully qualified class name to a class that either provides a Document instance, a Source or is annotated with XmlRootElement.

The specified class is resolved in exactly the same way as when using the parameter "source-class" (see Macro reference).

In addition to fully qualified class names, this parameter supports also factory methods that create the classes:

• my.package.MyClass
• my.package.MyClass.getInstance()
• my.package.MyClassFactory.getMyClass()
• my.package.MyClassFactory.getInstance().getMyClass()

Source class is implemented as a convenience parameter to "xml=class:", thus using the xml=class:my.pa.. is exactly the same as using xml-class=my.pa... Effectively this means that if this loader is used with the alias syntax, xml classes can be used via source-xml=class:my.package.MyClass.

See Also:

Constant Field Values

PARAM_JSON

public static final String PARAM_JSON

Experimental: Sets the URL or local path to JSON encoded content that is translated to XML and included.

JSON to XML transcoding is currently experimental and is primarily meant to be used for XSL or XPath matching on a JSON source (e.g. from a REST web service). See PositioningJsonDocumentBuilder for details on how JSON is mapped to XML.

See Also:

Constant Field Values

PARAM_XSL

public static final String PARAM_XSL

Optional parameter, sets the path to an XSL file that is used to transform the given input.

The specified file is resolved in exactly the same way as when using the parameter "source" (see Macro reference).

When a transformation is performed, all given macro call parameters are passed to the XSL processor making them available as xsl params when using global definitions like:
<xsl:param name="my-macro-param" select="'default-value'">

See Also:

Constant Field Values

PARAM_ADD_XSL

public static final String PARAM_ADD_XSL

Optional parameter, sets a relative or absolute URL to an XSL file that is added as standard template to the document being included but it is not executed.

This is useful to place <?xml-stylesheet ... declarations in included content.

See Also:

Constant Field Values

PARAM_ADD_DECLARATION

public static final String PARAM_ADD_DECLARATION

Optional parameter, enables the inclusion of the XML declaration (<?xml...) if set to "true".

See Also:

Constant Field Values

PARAM_LOAD_SCHEMA

public static final String PARAM_LOAD_SCHEMA

Enum parameter that specifies whether XML schemata are loaded in order to include them with the XML content. (Default: false) Possible values for this parameter are: (true|false|local-only)

Note: Enabling this option does not enable schema validation, it enables loading schema content into the output parameter schemaMap.

See Also:

Constant Field Values

PARAM_INDENT

public static final String PARAM_INDENT

Optional parameter, toggles whether the XML is indented before inclusion.

See Also:

Constant Field Values

PARAM_NAMESPACE_AWARE

public static final String PARAM_NAMESPACE_AWARE

Optional parameter, toggles whether the XML parser handles namespaces.

The default value for this option is 'true' when an XML transformation is specified (= xsl is set). Without a xml transformation namespace awareness is turned off by default to simplify xpath based matching.

See Also:

Constant Field Values

OUT_PARAM_DOCUMENT

public static final String OUT_PARAM_DOCUMENT

Is set with the parsed document object (Document) and can be accessed from velocity templates.

See Also:

Constant Field Values

OUT_PARAM_ORIGINAL_DOCUMENT

public static final String OUT_PARAM_ORIGINAL_DOCUMENT

Is set with the original parsed document as it existed before applying any transformations. When xsl is not set, originalDocument and document are the same.

See Also:

Constant Field Values

OUT_PARAM_SCHEMA_MAP

public static final String OUT_PARAM_SCHEMA_MAP

If filled with a map of all loaded XML schemata (in case of schema loading is enabled).

The map contains entries of the format:

[
     "schema-system-id": Document,
     ...
 ]

Note: Schema loading works with any input type that defines a schema (including schema generation on JAXB classes).

Tipp: Schema content can either be included in the site, parts can be included via XPath matching or finally schema files can also be linked using:

 Referenced XML schemata:<ul>
 #foreach($entry in $schemaMap.entrySet())
    #if($entry.key.startWith("http"))
        #set($href=$entry.key)
    #else
        #set($href=$globals.attachContent($entry.key, $xpath.serialize($entry.value)))
    #end
    <li><a href="$href">$href</a></li>
 #end </ul>
 

See Also:

Constant Field Values

OUT_PARAM_XPATH

public static final String OUT_PARAM_XPATH

Is set with an implementation of "XPathEvaluator" that is configured to match xpath expressions against DOM tree of document.

Usage (from within a velocity template):
Title of $document.documentURI is: $xpath.findText("/html/head/title")

Note: When namespace-aware is set to true, elements are matched using namespace prefixes. This is true also for the default namespace configured via xmlns="http://some/namespace". The xpath evaluator assigns the prefix "default" for the default namespace in order to make it accessible for an xpath evaluation.
E.g. the XHTML example from above changes to $xpath.findText("/default:html/default:head/default:title"). As a consequence, other namespace URIs that use a prefix of "default" will be ignored and are therefore unsupported.

See Also:

Constant Field Values

OUT_PARAM_ORIGINAL_XPATH

public static final String OUT_PARAM_ORIGINAL_XPATH

Is the same as "xpath" but configured to match on the original document.

See Also:

Constant Field Values

Constructor Detail

XmlLoader

public XmlLoader(File baseDir,
                 Map<String,Object> requestParams)
          throws Exception

Constructs a new XML loader.

Parameters:

baseDir - the base dir to of the maven module.

requestParams - the request params of the macro call.

Throws:

Exception - In case of loading or transforming fails.