com.sun.javatest
Class TestEnvironment

java.lang.Object
  com.sun.javatest.TestEnvironment

public class TestEnvironment
extends java.lang.Object

This class provides "environments", as embodied by groups of related properties. Environments have a name, and consist of those properties provided whose names do not begin with "env.", and in addition, those properties provided whose names begin "env.env-name.". In addition, an environment may inherit the properties of another environment by defining a property env.env-nameinherits=inherited-env-name The values of the environment's properties are split into words and various substitutions are performed.

The preferred way to make an environment is via a configuration interview, avoiding the use of the env.env-name prefix, which is retained for backwards compatibility with older test suites that read environments from environment (.jte) files.

Nested Class Summary

class	TestEnvironment.Element A class representing an entry in a test environment.
static class	TestEnvironment.Fault This exception is used to report resolving values in an environment.

Constructor Summary

	TestEnvironment(java.lang.String name, java.util.Map[] propTables, java.lang.String[] propTableNames) Construct an environment for a named group of properties.
	TestEnvironment(java.lang.String name, java.util.Map propTable, java.lang.String propTableName) Construct an environment for a named group of properties.
protected	TestEnvironment(TestEnvironment o)

Method Summary

static void	addDefaultPropTable(java.lang.String name, java.util.Map propTable) Add a default set of properties to be included when environments are created.
static void	clearDefaultPropTables() Remove all previously registered default property tables.
TestEnvironment	copy() Create a copy of the current environment.
java.util.Collection	elements() Enumerate the elements for this environment, including any inherited elements.
java.util.Collection	elementsUsed() Get a collection containing those entries in this environment that have been referenced, either directly via lookup, or indirectly via the $ syntax in other entries.
java.lang.String	getDescription() Get the description of this environment, as given by the "description" entry.
java.util.HashMap	getExtraValues()
java.lang.String[]	getInherits() Get the list of names of inherited environments, including this environment, in reverse order or inheritance (ie this one, parent, grandparent etc).
java.lang.String	getName() Get the distinguishing name for the properties of this environment.
boolean	hasUndefinedValues() Check if the environment has any undefined values.
java.util.Set	keys() Enumerate the keys for this environment, including any inherited keys.
java.lang.String[]	lookup(java.lang.String key) Lookup a named property in the environment.
void	put(java.lang.String name, java.lang.String value) A backdoor method to add global properties to the environment.
void	put(java.lang.String name, java.lang.String[] value) A backdoor method to add global properties to the environment.
void	putUrlAndFile(java.lang.String name, java.io.File f) A backdoor method to add global properties to the environment that have a value that might be desired as both a file and a URL.
void	resetElementsUsed() Reset the record of entries in this environment that have been referenced.
java.lang.String[]	resolve(java.lang.String s) Resolve a value in the environment by splitting it into words and performing various substitutions on it.

Methods inherited from class java.lang.Object

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

Constructor Detail

TestEnvironment

public TestEnvironment(java.lang.String name,
                       java.util.Map propTable,
                       java.lang.String propTableName)
                throws TestEnvironment.Fault

Construct an environment for a named group of properties.

Parameters:

name - The name by which to identify the group of properties for this environment

propTable - Dictionaries containing (but not limited to) the properties for this environment.

propTableName - The name of the property table, for use in diagnostics etc

Throws:

TestEnvironment.Fault - if there is an error in the table

TestEnvironment

public TestEnvironment(java.lang.String name,
                       java.util.Map[] propTables,
                       java.lang.String[] propTableNames)
                throws TestEnvironment.Fault

Construct an environment for a named group of properties.

Parameters:

name - The name by which to identify the group of properties for this environment

propTables - Dictionaries containing (but not limited to) the properties for this environment. They should be ordered so that values specified in later tables override those specified in subsequent tables.

propTableNames - The names of the property tables, for use in diagnostics etc

Throws:

TestEnvironment.Fault - if there is an error in the given tables

TestEnvironment

protected TestEnvironment(TestEnvironment o)

Method Detail

addDefaultPropTable

public static void addDefaultPropTable(java.lang.String name,
                                       java.util.Map propTable)

Add a default set of properties to be included when environments are created.

Parameters:

name - a name for this collection or properties, so that the source of the properties can be identified when browing an environment

propTable - a table of properties to be included when environments are created

Throws:

java.lang.NullPointerException - if either name or propTable is null.

See Also:

clearDefaultPropTables()

clearDefaultPropTables

public static void clearDefaultPropTables()

Remove all previously registered default property tables.

See Also:

addDefaultPropTable(java.lang.String, java.util.Map)

copy

public TestEnvironment copy()

Create a copy of the current environment.

Returns:

a copy of the current environment

getName

public java.lang.String getName()

Get the distinguishing name for the properties of this environment.

Returns:

The name used to distinguish the properties of this environment

getDescription

public java.lang.String getDescription()

Get the description of this environment, as given by the "description" entry.

Returns:

the description of this environment, or null if not given

getInherits

public java.lang.String[] getInherits()

Get the list of names of inherited environments, including this environment, in reverse order or inheritance (ie this one, parent, grandparent etc).

Returns:

an array containing the names of inherited environments

put

public void put(java.lang.String name,
                java.lang.String value)

A backdoor method to add global properties to the environment. The value is not subject to any substitutions.

Parameters:

name - The name of the property to be written

value - The value of the property to be written

put

public void put(java.lang.String name,
                java.lang.String[] value)

A backdoor method to add global properties to the environment. The value is not subject to any substitutions.

Parameters:

name - The name of the property to be written

value - The value of the property to be written

putUrlAndFile

public void putUrlAndFile(java.lang.String name,
                          java.io.File f)

A backdoor method to add global properties to the environment that have a value that might be desired as both a file and a URL. The URL form is installed as a property with "URL" appended to the given property name. The values are not subject to any substitutions. URL result constructed using the following expression - f.toURI().toASCIIString();

Parameters:

name - The name of the property to be written

f - The file indicating the value to be stored.

getExtraValues

public java.util.HashMap getExtraValues()

Returns:

all external global properties.

lookup

public java.lang.String[] lookup(java.lang.String key)
                          throws TestEnvironment.Fault

Lookup a named property in the environment.

Parameters:

key - The name of the property to look up

Returns:

The resolved value of the property

Throws:

TestEnvironment.Fault - is thrown if there is a problem resolving the value of the property

See Also:

resolve(java.lang.String)

resolve

public java.lang.String[] resolve(java.lang.String s)
                           throws TestEnvironment.Fault

Resolve a value in the environment by splitting it into words and performing various substitutions on it. White-space separates words except inside quoted strings. `$name' and `${name}' are replaced by the result of calling `lookup(name)'. `$/' is replaced by the platform-specific file separator; `$:' is replaced by the platform-specific path separator; and `$$' is replaced by a single `$'. No substitutions are performed inside single-quoted strings; $ substitutions are performed in double-quoted strings.

Parameters:

s - The string to be resolved

Returns:

An array of strings containing the words of the argument, after substitutions have been performed.

Throws:

TestEnvironment.Fault - This is thrown if there is a problem resolving the value of the argument.

hasUndefinedValues

public boolean hasUndefinedValues()

Check if the environment has any undefined values. These are entries containing the text VALUE_NOT_DEFINED.

Returns:

true if and only if there are any entries containing the text VALUE_NOT_DEFINED.

keys

public java.util.Set keys()

Enumerate the keys for this environment, including any inherited keys. Use `lookup' to find the values of the individual keys.

Returns:

An enumeration that yields the various keys, explicit or inherited, that are available in this environment. The keys do not include the `env.environment-name.' prefix of the corresponding property names.

elementsUsed

public java.util.Collection elementsUsed()

Get a collection containing those entries in this environment that have been referenced, either directly via lookup, or indirectly via the $ syntax in other entries.

Returns:

a collection of those entries in this environment that have been referenced.

See Also:

resetElementsUsed()

resetElementsUsed

public void resetElementsUsed()

Reset the record of entries in this environment that have been referenced.

See Also:

elementsUsed()

elements

public java.util.Collection elements()

Enumerate the elements for this environment, including any inherited elements.

Returns:

An enumeration that yields the various elements, explicit or inherited, that are available in this environment.