fr.gael.drb.query
Class ExternalVariable

java.lang.Object
  fr.gael.drb.query.ExternalVariable

public class ExternalVariable
extends Object

Variable declared as external in the XQuery module prologs.

The variable may be provided before any phase of the processing of the XQuery script. In most cases, the list of external variables is however, augmented during the static analysis phase and used during the dynamic evaluation phase.

Regarding the default value, it is evaluated as soon as the variable has been declared. The default value is not re-evaluated each time they are use, and therefore, their value is independent from the context during any dynamic evaluation phase.

Constructor Summary

protected

ExternalVariable(fr.gael.drb.query.QName name, fr.gael.drb.query.SequenceType sequence_type, DrbSequence default_value) Constructor of an external variable.

Method Summary

Object	clone() Clones the current instance.
DrbSequence	getDefaultValue() Returns the default value of the variable.
String	getLabel() Deprecated. this operation shall no longer be used as far as the label will no longer be supported in further versions of the engine.
String	getName() Returns the string form of the qualified name of the variable.
fr.gael.drb.query.QName	getQName() Returns the qualified name of the variable.
protected fr.gael.drb.query.SequenceType	getSequenceType() Returns the sequence type of the variable.
String	getSequenceTypeName() Returns the string form of the qualified name of the sequence type of the variable.
DrbSequence	getValue() Returns the value of the variable.
void	initialize(fr.gael.drb.query.DynamicContext context) Returns the value of the variable.
boolean	isExternal() Checks if this variable is declared as external.
protected void	setLabel(String label) Deprecated. this operation shall no longer be used as far as the label will no longer be supported in further versions of the engine.
protected void	setName(String name) Assigns a new name to the variable.
void	setValue(DrbItem value) Assigns item as value of the variable.
void	setValue(DrbSequence value) Assigns a value to the variable.
String	toString() Returns a detailed description of the variable and its value.

Methods inherited from class java.lang.Object

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

Constructor Detail

ExternalVariable

protected ExternalVariable(fr.gael.drb.query.QName name,
                           fr.gael.drb.query.SequenceType sequence_type,
                           DrbSequence default_value)

Constructor of an external variable.

Parameters:

name - string form of the variable qualified name.

sequence_type - the type of the variable.

default_value - the default value of the variable.

Method Detail

getDefaultValue

public DrbSequence getDefaultValue()

Returns the default value of the variable. The default value is computed from the value part of the external variable declaration of the XQuery prolog. This evaluation may have lead to dynamic errors if the query is not well-formed or contain a forbidden cyclic reference to the declared variable. In those cases of error, the exception are caught and a empty sequence is returned.

Returns:

the default value of the variable if any, or null otherwise.

setLabel

protected void setLabel(String label)

Deprecated. this operation shall no longer be used as far as the label will no longer be supported in further versions of the engine.

Set the label of the external variable. The label is an explicit name of the variable that should enhance the human readability and understanding of the variable scope. The language of the label depends on the creator of the variable and thus, the creator of the environment or the XQuery script writer.

Parameters:

label - the label of the external variable.

getLabel

public String getLabel()

Deprecated. this operation shall no longer be used as far as the label will no longer be supported in further versions of the engine.

Returns the label of the external variable. The label is an explicit name of the variable that should enhance the human readability and understanding of the variable scope. The language of the label depends on the creator of the variable and thus, the creator of the environment or the XQuery script writer.

Returns:

the label of the variable, if any or null otherwise.

clone

public Object clone()

Clones the current instance. The instance is duplicated with the same reference to the name, the sequence type and the value of the variable.

Returns:

a reference to the duplicated variable.

setValue

public void setValue(DrbSequence value)
              throws fr.gael.drb.query.TypeCastException

Assigns a value to the variable. The value shall be a sequence. Any previous value of the variable will be overridden. Null values are allowed. If the provided value does not match the variable sequence type, it is converted. A cast exception is thrown if the cast fails.

Parameters:

value - sequence to be assigned as value of the variable.

Throws:

fr.gael.drb.query.TypeCastException

setValue

public void setValue(DrbItem value)

Assigns item as value of the variable. This operation inserts the item in a default sequence and assign the value to the variable. According to the XQuery specifications, an item is equivalent to a singleton, a sequence of exactly one item. However, calls to further getValue() will return a sequence and not an item.

Parameters:

value - item to be assigned as value of the variable.

getValue

public DrbSequence getValue()

Returns the value of the variable.

Returns:

the value of the variable if any, or null otherwise.

initialize

public void initialize(fr.gael.drb.query.DynamicContext context)

Returns the value of the variable. As in default variable, the value is static, the current value is returned whatever context is provided in input.

Parameters:

context - a dynamic context not considered in this impelmentation.

toString

public String toString()

Returns a detailed description of the variable and its value.

Returns:

the variable name and is potential value.

getQName

public fr.gael.drb.query.QName getQName()

Returns the qualified name of the variable. Any variable shall return a qualified name, even if it is not prefixed.

Returns:

the qualified name of the variable.

getName

public String getName()

Returns the string form of the qualified name of the variable.

Returns:

the string form of the qualified name.

setName

protected void setName(String name)

Assigns a new name to the variable. The provided name shall be the qualified name of the variable such as the one provided at construction. The operation replaces the old name with the new one although the prefix part has changed or not. The operation raises a NullPointerException if the provided name is null.

Parameters:

name - the new qualified name of the variable.

getSequenceType

protected fr.gael.drb.query.SequenceType getSequenceType()

Returns the sequence type of the variable. The variable may not have an asigned sequence type. A null reference is therefore returned.

Returns:

the sequence type of the variable.

getSequenceTypeName

public String getSequenceTypeName()

Returns the string form of the qualified name of the sequence type of the variable. The name of the sequence type does not include the occurence indicator.

Returns:

the string form of the qualified name of the sequence type.

isExternal

public boolean isExternal()

Checks if this variable is declared as external. External variables are declared in the prolog and are initialized through the query environment.

Returns:

true if this variable is external and false otherwise.