org.quattor.pan.template

Class BuildContext

java.lang.Object

org.quattor.pan.template.BuildContext

All Implemented Interfaces:

Context

public class BuildContext
extends Object
implements Context

Contains the global context for the evaluation of a machine profile. Separate hashes are kept for functions, types, and variables allowing them to have identical names. The root element allows properties or resources to be found in the tree of configuration information.

Author:

loomis

Field Summary

Fields

Modifier and Type	Field and Description
CompilerOptions.DeprecationWarnings	deprecationWarnings

Constructor Summary

Constructors

Constructor and Description
BuildContext() Constructs a new Context object intended for testing.
BuildContext(Compiler compiler, Template objectTemplate) Constructs a new context for the given root element.

Method Summary

Methods

Modifier and Type	Method and Description
void	clearSelf()
IteratorMap	createIteratorMap()
LocalVariableMap	createLocalVariableMap(ListResource argv)
HashResource	createRelativeRoot() Initializes the relative root for this context and returns the old relative root.
Element	dereferenceVariable(String name, boolean lookupOnly, Term[] terms) Return the Element which corresponds to the given variable name.
Element	executeDmlBlock(Operation dml)
boolean	executeDmlValidationBlock(Operation dml, Element self)
Map<Path,List<FullType>>	getBindings() This method returns an unmodifiable, ordered map of the type bindings.
int	getCallLimit()
Template	getCurrentTemplate()
Set<SourceFile>	getDependencies() Returns an unmodifiable copy of the dependencies.
CompilerOptions.DeprecationWarnings	getDeprecationWarnings()
Element	getElement(Path path) Pull the value of an element from a configuration tree.
Element	getElement(Path path, boolean errorIfNotFound) Pull the value of an element from a configuration tree.
String	getFinalReason(Path p)
FullType	getFullType(String name) Return the type associated with the given name or null if it doesn't exist.
FunctionDefinition	getFunction(String name) Return the function definition associated with the given name or null if it doesn't exist.
Element	getGlobalVariable(String name) Return the Element which corresponds to the given variable name without duplicating the value.
int	getIterationLimit()
Resource.Iterator	getIterator(Resource resource) Get the iterator for the given resource or null if the iterator has not been registered.
Element	getLocalVariable(String name) Return the value associated with a local variable.
Set<String>	getObjectDependencies() Returns an unmodifiable copy of the object dependencies.
String	getObjectName() Get the name of the object template.
Template	getObjectTemplate() Returns the object Template which is the basis of this ObjectContext.
List<String>	getRelativeLoadpaths()
HashResource	getRoot() Returns the root element for this context.
Element	getSelf()
String	getTraceback(SourceRange sourceRange)
Element	getVariable(String name) Return the Element which corresponds to the given variable name.
Template	globalLoad(String name) A method to load a template from the global cache.
Template	globalLoad(String name, boolean lookupOnly) A method to load a template from the global cache.
void	initializeSelfHolder(SelfHolder selfHolder)
boolean	isCompileTimeContext() This flag indicates if this context is a special one used for the compile-time evaluation of DML blocks.
boolean	isFinal(Path p)
boolean	isSelfFinal()
Template	localAndGlobalLoad(String name, boolean lookupOnly)
Template	localLoad(String name) A method to load a template from the local cache.
SourceFile	lookupFile(String name)
void	popTemplate(Level logLevel, String logMessage)
void	printTraceback(SourceRange sourceRange)
void	pushTemplate(Template template, SourceRange sourceRange, Level logLevel, String logMessage)
void	putElement(Path path, Element value)
void	removeGlobalVariable(String name) Unconditionally remove a global variable.
GlobalVariable	replaceGlobalVariable(String name, Element value, boolean finalFlag) Replaces the given global variable with the given value.
void	resetSelf(Element newValue)
void	restoreIteratorMap(IteratorMap iteratorMap)
void	restoreLocalVariableMap(LocalVariableMap localVariableHolder)
HashResource	restoreRelativeRoot(HashResource previousValue) Retrieve and clear the relative root for this context.
void	restoreSelf(SelfHolder self)
GlobalVariable	retrieveGlobalVariable(String name)
SelfHolder	saveSelf()
void	setBinding(Path path, FullType fullType, Template template, SourceRange sourceRange) This method associates a type definition to a path.
void	setCurrentTemplate(Template template)
void	setFinal(Path p)
void	setFullType(String name, FullType fullType, Template template, SourceRange sourceRange) Associate the given type with the given name within this ObjectContext.
void	setFunction(String name, Operation function, Template template, SourceRange sourceRange) Define the given DML block as a function with the given name in this context.
void	setGlobalVariable(String name, Element value) Set the variable to the given value, preserving the status of the final flag.
void	setGlobalVariable(String name, Element value, boolean finalFlag) Set the variable to the given value.
void	setGlobalVariable(String name, GlobalVariable variable) Set the variable to the given GlobalVariable.
void	setIterator(Resource resource, Resource.Iterator iterator) Register a Resource iterator in the context.
void	setLocalVariable(String name, Element value) Set the local variable to the given value.
void	setLocalVariable(String name, Term[] terms, Element value) Set the local variable to the given value.
void	setObjectAndLoadpath() Set the name of the object template.
void	setRelativeLoadpaths(List<String> rpaths)
void	turnOffObjectDependencyChecking() Turn off the object dependency checking.

Methods inherited from class java.lang.Object

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

Field Detail

deprecationWarnings

public final CompilerOptions.DeprecationWarnings deprecationWarnings

Constructor Detail

BuildContext

public BuildContext()

Constructs a new Context object intended for testing.

BuildContext

public BuildContext(Compiler compiler,
            Template objectTemplate)

Constructs a new context for the given root element. The function, type, and variable hashes are initially empty. (In particular, the object variable is not automatically defined.

Parameters:

compiler - reference to the compiler and options

objectTemplate - An "object" Template to construct

Method Detail

getObjectTemplate

public Template getObjectTemplate()

Returns the object Template which is the basis of this ObjectContext.

Specified by:

getObjectTemplate in interface Context

getRoot

public HashResource getRoot()

Returns the root element for this context.

Specified by:

getRoot in interface Context

restoreRelativeRoot

public HashResource restoreRelativeRoot(HashResource previousValue)

Retrieve and clear the relative root for this context.

Specified by:

restoreRelativeRoot in interface Context

Parameters:

previousValue - previous value of the relative root to restore

Returns:

value of the relative root which was replaced

createRelativeRoot

public HashResource createRelativeRoot()

Initializes the relative root for this context and returns the old relative root. The old value should be restored when the processing of the structure template is finished.

Specified by:

createRelativeRoot in interface Context

Returns:

old value of the relative root

getDependencies

public Set<SourceFile> getDependencies()

Returns an unmodifiable copy of the dependencies.

Specified by:

getDependencies in interface Context

getObjectDependencies

public Set<String> getObjectDependencies()

Returns an unmodifiable copy of the object dependencies.

Specified by:

getObjectDependencies in interface Context

turnOffObjectDependencyChecking

public void turnOffObjectDependencyChecking()

Turn off the object dependency checking. This should only be turned off after the build phase is complete.

Specified by:

turnOffObjectDependencyChecking in interface Context

localLoad

public Template localLoad(String name)

A method to load a template from the local cache. Returns null if the template is not in the cache.

Specified by:

localLoad in interface Context

globalLoad

public Template globalLoad(String name)

A method to load a template from the global cache. This may trigger the global cache to compile the template.

Specified by:

globalLoad in interface Context

localAndGlobalLoad

public Template localAndGlobalLoad(String name,
                          boolean lookupOnly)

Specified by:

localAndGlobalLoad in interface Context

globalLoad

public Template globalLoad(String name,
                  boolean lookupOnly)

A method to load a template from the global cache. This may trigger the global cache to compile the template.

Specified by:

globalLoad in interface Context

lookupFile

public SourceFile lookupFile(String name)

Specified by:

lookupFile in interface Context

createLocalVariableMap

public LocalVariableMap createLocalVariableMap(ListResource argv)

Specified by:

createLocalVariableMap in interface Context

restoreLocalVariableMap

public void restoreLocalVariableMap(LocalVariableMap localVariableHolder)

Specified by:

restoreLocalVariableMap in interface Context

createIteratorMap

public IteratorMap createIteratorMap()

Specified by:

createIteratorMap in interface Context

restoreIteratorMap

public void restoreIteratorMap(IteratorMap iteratorMap)

Specified by:

restoreIteratorMap in interface Context

setObjectAndLoadpath

public void setObjectAndLoadpath()

Set the name of the object template. Define the necessary variables.

Specified by:

setObjectAndLoadpath in interface Context

getObjectName

public String getObjectName()

Description copied from interface: Context

Get the name of the object template.

Specified by:

getObjectName in interface Context

getFunction

public FunctionDefinition getFunction(String name)

Return the function definition associated with the given name or null if it doesn't exist. It will always return null if the argument is null.

Specified by:

getFunction in interface Context

Parameters:

name - name of the function to retrieve

Returns:

FunctionDefinition associated with the given name or null if it doesn't exist

setFunction

public void setFunction(String name,
               Operation function,
               Template template,
               SourceRange sourceRange)
                 throws EvaluationException

Define the given DML block as a function with the given name in this context. Note that functions may not be redefined; attempting to do so will throw an EvaluationException.

Specified by:

setFunction in interface Context

Parameters:

name - name for the function

function - code for the function as a DML block

template - template in which this function is defined (used for error handling)

sourceRange - location in the template where this function is defined (used for error handling)

Throws:

EvaluationException - if a function with the given name already exists

getBindings

public Map<Path,List<FullType>> getBindings()

This method returns an unmodifiable, ordered map of the type bindings.

Specified by:

getBindings in interface Context

Returns:

unmodifiable, ordered map of the type bindings

setBinding

public void setBinding(Path path,
              FullType fullType,
              Template template,
              SourceRange sourceRange)

This method associates a type definition to a path. These bindings are checked as part of the validation process. Note that there can be more than one binding per path.

Specified by:

setBinding in interface Context

Parameters:

path - absolute path to bind to the type

fullType - data type to use

template - template where the binding was defined (used for error handling)

sourceRange - location in the template where the binding was defined (used for error handling)

getFullType

public FullType getFullType(String name)

Return the type associated with the given name or null if it doesn't exist. It will always return null if the argument is null.

Specified by:

getFullType in interface Context

Parameters:

name - name of the type to retrieve

Returns:

FullType associated with this name or null if it doesn't exist

setFullType

public void setFullType(String name,
               FullType fullType,
               Template template,
               SourceRange sourceRange)
                 throws EvaluationException

Associate the given type with the given name within this ObjectContext. This will throw an EvaluationException if the type is already defined.

Specified by:

setFullType in interface Context

Parameters:

name - name to associate to the type

fullType - data type to use for the definition

template - template where the type is defined (used for error handling)

sourceRange - location in the template where the type is defined (used for error handling)

Throws:

EvaluationException - if there is already a type associated with the given name

setGlobalVariable

public void setGlobalVariable(String name,
                     Element value)

Set the variable to the given value, preserving the status of the final flag. This will unconditionally set the value without checking if the value is final; be careful. The value must already exist.

Specified by:

setGlobalVariable in interface Context

setGlobalVariable

public void setGlobalVariable(String name,
                     GlobalVariable variable)

Set the variable to the given GlobalVariable. If variable is null, then the global variable definition is removed.

Specified by:

setGlobalVariable in interface Context

Parameters:

name - global variable name

variable - GlobalVariable to associate with name

replaceGlobalVariable

public GlobalVariable replaceGlobalVariable(String name,
                                   Element value,
                                   boolean finalFlag)

Replaces the given global variable with the given value. The flag indicates whether or not the variable should be marked as final. Note, however, that this routine does not respect the final flag and replaces the value unconditionally. The function returns the old value of the variable or null if it didn't exist.

Specified by:

replaceGlobalVariable in interface Context

setGlobalVariable

public void setGlobalVariable(String name,
                     Element value,
                     boolean finalFlag)

Set the variable to the given value. If the value is null, then the variable will be removed from the context.

Specified by:

setGlobalVariable in interface Context

setIterator

public void setIterator(Resource resource,
               Resource.Iterator iterator)

Register a Resource iterator in the context.

Specified by:

setIterator in interface Context

getIterator

public Resource.Iterator getIterator(Resource resource)

Get the iterator for the given resource or null if the iterator has not been registered.

Specified by:

getIterator in interface Context

removeGlobalVariable

public void removeGlobalVariable(String name)

Unconditionally remove a global variable. This should never be called from user code. It is used to handle special variables like "self".

Specified by:

removeGlobalVariable in interface Context

getGlobalVariable

public Element getGlobalVariable(String name)

Return the Element which corresponds to the given variable name without duplicating the value. This is useful when dealing with SELF or with variables in a context where it is known that the value won't be modified.

Specified by:

getGlobalVariable in interface Context

retrieveGlobalVariable

public GlobalVariable retrieveGlobalVariable(String name)

Specified by:

retrieveGlobalVariable in interface Context

pushTemplate

public void pushTemplate(Template template,
                SourceRange sourceRange,
                Level logLevel,
                String logMessage)

Specified by:

pushTemplate in interface Context

popTemplate

public void popTemplate(Level logLevel,
               String logMessage)

Specified by:

popTemplate in interface Context

printTraceback

public void printTraceback(SourceRange sourceRange)

Specified by:

printTraceback in interface Context

getTraceback

public String getTraceback(SourceRange sourceRange)

Specified by:

getTraceback in interface Context

setCurrentTemplate

public void setCurrentTemplate(Template template)

Specified by:

setCurrentTemplate in interface Context

getCurrentTemplate

public Template getCurrentTemplate()

Specified by:

getCurrentTemplate in interface Context

getElement

public Element getElement(Path path)
                   throws EvaluationException,
                          ValidationException

Pull the value of an element from a configuration tree. This can either be an absolute or external path. An EvaluationException will be thrown if the path cannot be found. This is equivalent to getElement(path, true).

Specified by:

getElement in interface Context

Parameters:

path - absolute or external path to lookup

Returns:

Element associated to the given path

Throws:

EvaluationException - if the path cannot be found or the path is relative

ValidationException

getElement

public Element getElement(Path path,
                 boolean errorIfNotFound)
                   throws EvaluationException

Pull the value of an element from a configuration tree. This can either be an absolute, relative, or external path.

Specified by:

getElement in interface Context

Parameters:

path - path to lookup

errorIfNotFound - if true an EvaluationException will be thrown if the path can't be found

Returns:

Element associated to the given path

Throws:

EvaluationException - if the path can't be found and errorIfNotFound is set, or if the path is relative and relativeRoot isn't set

putElement

public void putElement(Path path,
              Element value)

Specified by:

putElement in interface Context

executeDmlBlock

public Element executeDmlBlock(Operation dml)

Specified by:

executeDmlBlock in interface Context

executeDmlValidationBlock

public boolean executeDmlValidationBlock(Operation dml,
                                Element self)
                                  throws ValidationException

Specified by:

executeDmlValidationBlock in interface Context

Throws:

ValidationException

getLocalVariable

public Element getLocalVariable(String name)

Return the value associated with a local variable. This method will NOT attempt to look up a global variable if a local variable of the same name is not found.

Specified by:

getLocalVariable in interface Context

Parameters:

name - name of the variable to lookup

Returns:

the value of the associated local variable or null if the local variable does not exist

getVariable

public Element getVariable(String name)

Return the Element which corresponds to the given variable name. It will first check local variables and then global variables. This method will return null if the variable doesn't exist or the argument is null. Note that this will clone the value before returning it, if it came from a global variable.

Specified by:

getVariable in interface Context

Parameters:

name - name of the variable to lookup

Returns:

Element corresponding to the given variable name or null if it could not be found

dereferenceVariable

public Element dereferenceVariable(String name,
                          boolean lookupOnly,
                          Term[] terms)
                            throws InvalidTermException

Return the Element which corresponds to the given variable name. It will first check local variables and then the parent context. This method will return null if the variable doesn't exist or the argument is null. Note that this will clone the final value, if it originated from a global variable.

Specified by:

dereferenceVariable in interface Context

Parameters:

name - name of the variable to lookup

lookupOnly - flag indicating if only a lookup should be done

terms - values for dereferencing the given variable

Returns:

Element value of the associated dereferenced variable

Throws:

InvalidTermException

setLocalVariable

public void setLocalVariable(String name,
                    Element value)
                      throws EvaluationException

Set the local variable to the given value. If the value is null, then the corresponding variable will be removed. If there is a global variable of the same name, then an EvaluationException will be thrown. This method does not allow children of the referenced value to be set.

Specified by:

setLocalVariable in interface Context

Parameters:

name - name of the local variable

value - value to use or null to remove the variable

Throws:

EvaluationException - if there is a global variable with the same name as the local variable

setLocalVariable

public void setLocalVariable(String name,
                    Term[] terms,
                    Element value)
                      throws EvaluationException

Set the local variable to the given value. If the value is null, then the corresponding variable will be removed. If there is a global variable of the same name, then an EvaluationException will be thrown.

Specified by:

setLocalVariable in interface Context

Parameters:

name - name of the local variable

terms - terms used to dereference the variable, or null if the variable is to be used directly

value - value to use or null to remove the variable

Throws:

EvaluationException - if there is a global variable with the same name as the local variable

getCallLimit

public int getCallLimit()

Specified by:

getCallLimit in interface Context

getIterationLimit

public int getIterationLimit()

Specified by:

getIterationLimit in interface Context

isFinal

public boolean isFinal(Path p)

Specified by:

isFinal in interface Context

getFinalReason

public String getFinalReason(Path p)

Specified by:

getFinalReason in interface Context

setFinal

public void setFinal(Path p)

Specified by:

setFinal in interface Context

isCompileTimeContext

public boolean isCompileTimeContext()

This flag indicates if this context is a special one used for the compile-time evaluation of DML blocks. Such contexts are very limited in the functionality that is provided.

Specified by:

isCompileTimeContext in interface Context

Returns:

flag indicating if this is a compile-time context

initializeSelfHolder

public void initializeSelfHolder(SelfHolder selfHolder)

Specified by:

initializeSelfHolder in interface Context

isSelfFinal

public boolean isSelfFinal()

Specified by:

isSelfFinal in interface Context

getSelf

public Element getSelf()

Specified by:

getSelf in interface Context

clearSelf

public void clearSelf()

Specified by:

clearSelf in interface Context

saveSelf

public SelfHolder saveSelf()

Specified by:

saveSelf in interface Context

restoreSelf

public void restoreSelf(SelfHolder self)

Specified by:

restoreSelf in interface Context

resetSelf

public void resetSelf(Element newValue)

Specified by:

resetSelf in interface Context

setRelativeLoadpaths

public void setRelativeLoadpaths(List<String> rpaths)

Specified by:

setRelativeLoadpaths in interface Context

getRelativeLoadpaths

public List<String> getRelativeLoadpaths()

Specified by:

getRelativeLoadpaths in interface Context

getDeprecationWarnings

public CompilerOptions.DeprecationWarnings getDeprecationWarnings()

Specified by:

getDeprecationWarnings in interface Context