org.quattor.pan.template
Interface Context

All Known Implementing Classes:

BuildContext, CompileTimeContext

public interface 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

static java.lang.String

TPL_VAR

Method Summary

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(java.lang.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)
java.util.Map<Path,java.util.List<FullType>>	getBindings() This method returns an unmodifiable, ordered map of the type bindings.
int	getCallLimit()
Template	getCurrentTemplate()
java.util.Set<SourceFile>	getDependencies() Returns an unmodifiable copy of the dependencies.
int	getDeprecationLevel()
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.
boolean	getFailOnWarn()
java.lang.String	getFinalReason(Path p)
FullType	getFullType(java.lang.String name) Return the type associated with the given name or null if it doesn't exist.
FunctionDefinition	getFunction(java.lang.String name) Return the function definition associated with the given name or null if it doesn't exist.
Element	getGlobalVariable(java.lang.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(java.lang.String name) Return the value associated with a local variable.
java.util.Set<java.lang.String>	getObjectDependencies() Returns an unmodifiable copy of the object dependencies.
Template	getObjectTemplate() Returns the object Template which is the basis of this ObjectContext.
java.util.List<java.lang.String>	getRelativeLoadpaths()
HashResource	getRoot() Returns the root element for this context.
Element	getSelf()
java.lang.String	getTraceback(SourceRange sourceRange)
Element	getVariable(java.lang.String name) Return the Element which corresponds to the given variable name.
Template	globalLoad(java.lang.String name) A method to load a template from the global cache.
Template	globalLoad(java.lang.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(java.lang.String name, boolean lookupOnly)
Template	localLoad(java.lang.String name) A method to load a template from the local cache.
SourceFile	lookupFile(java.lang.String name)
void	popTemplate(java.util.logging.Level logLevel, java.lang.String logMessage)
void	printTraceback(SourceRange sourceRange)
void	pushTemplate(Template template, SourceRange sourceRange, java.util.logging.Level logLevel, java.lang.String logMessage)
void	putElement(Path path, Element value)
void	removeGlobalVariable(java.lang.String name) Unconditionally remove a global variable.
GlobalVariable	replaceGlobalVariable(java.lang.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(java.lang.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(java.lang.String name, FullType fullType, Template template, SourceRange sourceRange) Associate the given type with the given name within this ObjectContext.
void	setFunction(java.lang.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(java.lang.String name, Element value) Set the variable to the given value, preserving the status of the final flag.
void	setGlobalVariable(java.lang.String name, Element value, boolean finalFlag) Set the variable to the given value.
void	setGlobalVariable(java.lang.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(java.lang.String name, Element value) Set the local variable to the given value.
void	setLocalVariable(java.lang.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(java.util.List<java.lang.String> rpaths)
void	turnOffObjectDependencyChecking() Turn off the object dependency checking.

Field Detail

TPL_VAR

static final java.lang.String TPL_VAR

See Also:

Constant Field Values

Method Detail

getObjectTemplate

Template getObjectTemplate()

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

getRoot

HashResource getRoot()

Returns the root element for this context.

restoreRelativeRoot

HashResource restoreRelativeRoot(HashResource previousValue)

Retrieve and clear the relative root for this context.

Parameters:

previousValue - previous value of the relative root to restore

Returns:

value of the relative root which was replaced

createRelativeRoot

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.

Returns:

old value of the relative root

getDependencies

java.util.Set<SourceFile> getDependencies()

Returns an unmodifiable copy of the dependencies.

getObjectDependencies

java.util.Set<java.lang.String> getObjectDependencies()

Returns an unmodifiable copy of the object dependencies.

turnOffObjectDependencyChecking

void turnOffObjectDependencyChecking()

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

localLoad

Template localLoad(java.lang.String name)

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

globalLoad

Template globalLoad(java.lang.String name)

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

localAndGlobalLoad

Template localAndGlobalLoad(java.lang.String name,
                            boolean lookupOnly)

globalLoad

Template globalLoad(java.lang.String name,
                    boolean lookupOnly)

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

lookupFile

SourceFile lookupFile(java.lang.String name)

createLocalVariableMap

LocalVariableMap createLocalVariableMap(ListResource argv)

restoreLocalVariableMap

void restoreLocalVariableMap(LocalVariableMap localVariableHolder)

createIteratorMap

IteratorMap createIteratorMap()

restoreIteratorMap

void restoreIteratorMap(IteratorMap iteratorMap)

setObjectAndLoadpath

void setObjectAndLoadpath()

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

getFunction

FunctionDefinition getFunction(java.lang.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.

Parameters:

name - name of the function to retrieve

Returns:

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

setFunction

void setFunction(java.lang.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.

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

java.util.Map<Path,java.util.List<FullType>> getBindings()

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

Returns:

unmodifiable, ordered map of the type bindings

setBinding

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.

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

FullType getFullType(java.lang.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.

Parameters:

name - name of the type to retrieve

Returns:

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

setFullType

void setFullType(java.lang.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.

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

void setGlobalVariable(java.lang.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.

setGlobalVariable

void setGlobalVariable(java.lang.String name,
                       GlobalVariable variable)

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

Parameters:

name - global variable name

variable - GlobalVariable to associate with name

replaceGlobalVariable

GlobalVariable replaceGlobalVariable(java.lang.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.

setGlobalVariable

void setGlobalVariable(java.lang.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.

setIterator

void setIterator(Resource resource,
                 Resource.Iterator iterator)

Register a Resource iterator in the context.

getIterator

Resource.Iterator getIterator(Resource resource)

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

removeGlobalVariable

void removeGlobalVariable(java.lang.String name)

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

getGlobalVariable

Element getGlobalVariable(java.lang.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.

retrieveGlobalVariable

GlobalVariable retrieveGlobalVariable(java.lang.String name)

pushTemplate

void pushTemplate(Template template,
                  SourceRange sourceRange,
                  java.util.logging.Level logLevel,
                  java.lang.String logMessage)

popTemplate

void popTemplate(java.util.logging.Level logLevel,
                 java.lang.String logMessage)

printTraceback

void printTraceback(SourceRange sourceRange)

getTraceback

java.lang.String getTraceback(SourceRange sourceRange)

setCurrentTemplate

void setCurrentTemplate(Template template)

getCurrentTemplate

Template getCurrentTemplate()

getElement

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).

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

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.

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

void putElement(Path path,
                Element value)

executeDmlBlock

Element executeDmlBlock(Operation dml)

executeDmlValidationBlock

boolean executeDmlValidationBlock(Operation dml,
                                  Element self)
                                  throws ValidationException

Throws:

ValidationException

getLocalVariable

Element getLocalVariable(java.lang.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.

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

Element getVariable(java.lang.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.

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

Element dereferenceVariable(java.lang.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.

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

void setLocalVariable(java.lang.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.

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

void setLocalVariable(java.lang.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.

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

int getCallLimit()

getIterationLimit

int getIterationLimit()

isFinal

boolean isFinal(Path p)

getFinalReason

java.lang.String getFinalReason(Path p)

setFinal

void setFinal(Path p)

isCompileTimeContext

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.

Returns:

flag indicating if this is a compile-time context

initializeSelfHolder

void initializeSelfHolder(SelfHolder selfHolder)

isSelfFinal

boolean isSelfFinal()

getSelf

Element getSelf()

clearSelf

void clearSelf()

saveSelf

SelfHolder saveSelf()

restoreSelf

void restoreSelf(SelfHolder self)

resetSelf

void resetSelf(Element newValue)

setRelativeLoadpaths

void setRelativeLoadpaths(java.util.List<java.lang.String> rpaths)

getRelativeLoadpaths

java.util.List<java.lang.String> getRelativeLoadpaths()

getDeprecationLevel

int getDeprecationLevel()

getFailOnWarn

boolean getFailOnWarn()