verinec.adaptation
Class Translator

java.lang.Object
  verinec.adaptation.Translator

public class Translator
extends Object

Main class to translate a configuration.

If you have a nodes document including the global definitions, it can be translated automagically by translate(Element). Of course, it must contain the necessary definitions of the translation namespace for node types (service translators) and target.

You can also use translateNode(Element) to translate one node. In this case you will have to expand the variables (i.e. using the DataUtil.expandVariables and resolve type information using resolveNodeType(Element,Element).

Use Distribute to interpret the configuration XML and distribute the configuration onto the machines.

Version:

$Revision: 989 $

Author:

david.buchmann at unifr.ch

See Also:

Custom Translators Howto

Field Summary

private Logger	logger
private ITranslationRepository	rep

Constructor Summary

Translator(ITranslationRepository repo)
Instantiate the translator, using repository repo

Method Summary

private XSLTransformer	getResolver() Get the resolver xslt translator to resolve node types.
private String	getServiceType(String servicename, Element node) Determine the service type from that service element and the node type.
private void	process(Element node, Element parent, boolean doTranslation) Common procedure for both translation and restriction of a configuration.
private Element	processService(Element node, String service, boolean doTranslation) Translate or restrict a single service.
private void	resolveMacros(Element node) Resolve macros within attribute values.
Element	resolveNodeType(Element node, Element globals) Resolve the type- and target-id's to types and targets inside the node configuration information.
Document	restrict(Element nodes) Creates the restriction information for a set of network nodes.
Document	restrictNode(Element node) Extract the restriction information of an expanded and resolved node.
Document	translate(Element nodes) Translates a set of network nodes.
Document	translateNode(Element node) Translate a single expanded and resolved node.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

logger

private Logger logger

rep

private ITranslationRepository rep

Constructor Detail

Translator

public Translator(ITranslationRepository repo)

Instantiate the translator, using repository repo

Parameters:

repo - The repository this instance will use for loading xsl stylesheets

Method Detail

translate

public Document translate(Element nodes)
                   throws VerinecException

Translates a set of network nodes.

This method will expand variables, resolve the type and then do the actual translation.

Parameters:

nodes - A <nodes> element containing tr:typedef and node children

Returns:

A document of type configuration.xsd

Throws:

VerinecException - if an error occurs during translation

restrict

public Document restrict(Element nodes)
                  throws VerinecException

Creates the restriction information for a set of network nodes.

Only services that use something restricted will create a service tag containing warnings within the node tag.

Parameters:

nodes - A <nodes> element containing tr:typedef and node children

Returns:

A document of type configuration.xsd

Throws:

VerinecException - if processing fails.

translateNode

public Document translateNode(Element node)
                       throws VerinecException

Translate a single expanded and resolved node. Normally, it is easyier to use the method translate(Element) because you won't need to expand the node yourselves.

The node Element has to be expanded and resolved for the translation to find the correct type information for the translation. verinec.util.DataUtil.expandVariables(Document) and resolveNodeType(Element,Element).

The result is a configuration document containing a set of service tags. The service tags contain meta information and data for configuration files in result-file tags.

Code Example:
//nodes_with_vars is a <nodes> element, containing variable definitions and at least one node element

//first, expand variables
Element expanded = DataUtil.expandVariables(nodes_with_vars);

//we test if it is valid (not mandatory)
SchemaValidator val = new SchemaValidator();
if (! val.validate(expanded)) {
throw new Exception("Expanding produced invalid xml");
}

//then resolve types

List nodes = expanded.getChildren("node", VerinecNamespaces.NS_NODE);
Element node1=(Element)nodes.get(0);
...

Translator translator = new Translator(TranslationRepFactory.createRepository());

node1=translator.resolveNodeType(node1, expanded);

XMLOutputter out = new XMLOutputter(Format.getPrettyFormat());
System.out.println("Unvalidated output of resolving type and target");
out.output(node1, System.out);
Only services with a translator specifycation in the nodetype tag are processed. It is an error to use translateNode with a node that has no nodetype.

Parameters:

node - The node definition to translate (expanded and resolved)

Returns:

A document of type configuration.xsd

Throws:

VerinecException - if processing fails.

restrictNode

public Document restrictNode(Element node)
                      throws VerinecException

Extract the restriction information of an expanded and resolved node.

The result is a restriction Document with information about all restrictions that would apply if this node is translated with its type information. Only services that use something restricted will create a service tag containing warnings within the node tag.
Node must fullfill the same requirements as for translateNode(Element).

Parameters:

node - The node definition to translate (expanded and resolved).

Returns:

Document of type restrictions.xsd

Throws:

VerinecException - if processing fails.

process

private void process(Element node,
                     Element parent,
                     boolean doTranslation)
              throws VerinecException

Common procedure for both translation and restriction of a configuration. Processes all services specified in the nodetype tag. The result is attached to the argument parent.

Parameters:

node - The configuration to process.

parent - The element to attach resulting data to.

doTranslation - Whether we do translation or restriction.

Throws:

VerinecException - if processing fails.

processService

private Element processService(Element node,
                               String service,
                               boolean doTranslation)
                        throws VerinecException

Translate or restrict a single service.

Parameters:

node - The configuration data node.

service - Name of the service to process.

doTranslation - Whether we do translation or restriction.

Returns:

XML fragment of the result.

Throws:

VerinecException - if processing fails.

getServiceType

private String getServiceType(String servicename,
                              Element node)
                       throws VerinecException

Determine the service type from that service element and the node type.

Parameters:

servicename - Name of the service.

node - The node itselves (for the tr:nodetype local translator selection).

Returns:

The name of the translation to be used for this service.

Throws:

VerinecException - if there is no definition in the nodetype and no local servicetype tag

resolveNodeType

public Element resolveNodeType(Element node,
                               Element globals)
                        throws VerinecException

Resolve the type- and target-id's to types and targets inside the node configuration information.

The node type declaration in tr:nodetype can specify a global node type and can specify translations for individual services in the tr:service children. Locally defined translators overwrite the ones of the global type.

This method will attach the correct type information to each nodetype, for the translateNode and restrictNode methods to find the correct translator and for the translator xsl to find the target for a service.

Additionally it does resolve the {!macro} references in attribute values. This is not done during variable expanding, because the macros are relative to their location within the document. (You will see the difference when you use a macro in a standard target, e.g. to use the hostname of the node the config file is for in an scp target.) To use {! literally in an attribute, you have to escape it with a backslash, that is \{! (note you do not need to escape a parenthesis { if it is not followed by an exclamation mark).

Currently available macros are

• hostname: The hostname attribute of the node enclosing the macro.

todo: We should consider allowing i.e. XPath expressions as macro instead of explicitely coding expressions. A plugin system for macros would be nice.

Parameters:

node - A node to translate.

globals - All global values as provided by the repository. (that is, enclosed in the nodes tag)

Returns:

A resolved node element suitable for translateNode.

Throws:

VerinecException - if processing fails.

resolveMacros

private void resolveMacros(Element node)
                    throws VerinecException

Resolve macros within attribute values. See resolveNodeType(Element,Element) for more information about the macro mechanism.

Parameters:

node - The node element maybe containing macros.

Throws:

VerinecException - if the macro can not be resolved.

getResolver

private XSLTransformer getResolver()
                            throws VerinecException

Get the resolver xslt translator to resolve node types.

Returns:

The xslt processor to resolve node types.

Throws:

VerinecException - if XSL resource can not be loaded.