Package com.sun.javatest
Class TestEnvironment
java.lang.Object
com.sun.javatest.TestEnvironment
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
Nested ClassesModifier and TypeClassDescriptionstatic class
A class representing an entry in a test environment.static class
This exception is used to report resolving values in an environment. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
Construct an environment for a named group of properties.TestEnvironment
(String name, Map[] propTables, String... propTableNames) Deprecated.please use constructor that accepts a list of mapsConstruct an environment for a named group of properties. -
Method Summary
Modifier and TypeMethodDescriptionstatic void
addDefaultPropTable
(String name, Map<String, String> propTable) Add a default set of properties to be included when environments are created.static void
addDefaultPropTable
(String name, Properties propTable) Add a default set of properties to be included when environments are created.static void
Remove all previously registered default property tables.copy()
Create a copy of the current environment.elements()
Enumerate the elements for this environment, including any inherited elements.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.Get the description of this environment, as given by the "description" entry.String[]
Get the list of names of inherited environments, including this environment, in reverse order or inheritance (ie this one, parent, grandparent etc).getName()
Get the distinguishing name for the properties of this environment.boolean
Check if the environment has any undefined values.keys()
Enumerate the keys for this environment, including any inherited keys.String[]
Lookup a named property in the environment.Looks up a string using the test environment and joins the result into a single string.String[]
lookupMultipleOrFail
(String name) Looks up a parameter in the test environment.lookupOneOrEmpty
(String name) Safely looks up a parameter in the test environment.lookupOneOrFail
(String name) Looks up a parameter in the test environment and extracts a single value.lookupOneOrNull
(String name) Safely looks up a parameter in the test environment.void
A backdoor method to add global properties to the environment.void
A backdoor method to add global properties to the environment.void
putUrlAndFile
(String name, 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
Reset the record of entries in this environment that have been referenced.String[]
Resolve a value in the environment by splitting it into words and performing various substitutions on it.Resolves a string using the test environment and joins the result into a single string.String[]
Resolves a string using the test environment.
-
Constructor Details
-
TestEnvironment
public TestEnvironment(String name, Map<String, String> propTable, String propTableName) throws TestEnvironment.FaultConstruct an environment for a named group of properties.- Parameters:
name
- The name by which to identify the group of properties for this environmentpropTable
- 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
@Deprecated public TestEnvironment(String name, Map[] propTables, String... propTableNames) throws TestEnvironment.Fault Deprecated.please use constructor that accepts a list of mapsConstruct an environment for a named group of properties.- Parameters:
name
- The name by which to identify the group of properties for this environmentpropTables
- Array of maps 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
public TestEnvironment(String name, List<Map<String, String>> propTables, String... propTableNames) throws TestEnvironment.FaultConstruct an environment for a named group of properties.- Parameters:
name
- The name by which to identify the group of properties for this environmentpropTables
- List of maps 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
-
-
Method Details
-
addDefaultPropTable
Add a default set of properties to be included when environments are created. Properties are passed in as aMap<String, String>
instance.- Parameters:
name
- a name for this collection or properties, so that the source of the properties can be identified when browing an environmentpropTable
- a table of properties to be included when environments are created- Throws:
NullPointerException
- if either name or propTable is null.- See Also:
-
addDefaultPropTable
Add a default set of properties to be included when environments are created. Properties are passed in as ajava.util.Properties
instance.- Parameters:
name
- a name for this collection or properties, so that the source of the properties can be identified when browing an environmentpropTable
- a table of properties to be included when environments are created- Throws:
NullPointerException
- if either name or propTable is null.- See Also:
-
clearDefaultPropTables
public static void clearDefaultPropTables()Remove all previously registered default property tables.- See Also:
-
copy
Create a copy of the current environment.- Returns:
- a copy of the current environment
-
getName
Get the distinguishing name for the properties of this environment.- Returns:
- The name used to distinguish the properties of this environment
-
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
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
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 writtenvalue
- The value of the property to be written
-
put
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 writtenvalue
- The value of the property to be written
-
putUrlAndFile
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 writtenf
- The file indicating the value to be stored.
-
getExtraValues
- Returns:
- all external global properties.
-
lookup
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
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
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
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
public void resetElementsUsed()Reset the record of entries in this environment that have been referenced.- See Also:
-
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.
-
lookupOneOrFail
Looks up a parameter in the test environment and extracts a single value. If a parameter is found, and it has a non-empty array of values, and the first of these values is not null then that value is returned. Otherwise, an exception is thrown.- Parameters:
name
- parameter to look up.- Returns:
- first of the values associated with the named parameter.
- Throws:
RuntimeException
- iflookup
throwsTestEnvironment.Fault
.ArrayIndexOutOfBoundsException
- iflookup
returns an empty array.NullPointerException
- iflookup
returns null or if the first element of the returned array is null.
-
lookupMultipleOrFail
Looks up a parameter in the test environment. If a parameter is found, returns array of values associated with it. Otherwise, an exception is thrown.- Parameters:
name
- parameter to look up.- Returns:
- array of values associated with the named parameter.
- Throws:
RuntimeException
- iflookup
throwsTestEnvironment.Fault
.NullPointerException
- iflookup
returns null.
-
resolveAndJoinOrFail
Resolves a string using the test environment and joins the result into a single string.- Parameters:
s
- string to resolve.- Returns:
- string obtained by joining array of values produced by the string resolution with spaces.
- Throws:
RuntimeException
- ifresolve
throwsTestEnvironment.Fault
.
-
resolveMultipleOrFail
Resolves a string using the test environment.- Parameters:
s
- string to resolve.- Returns:
- array of values produced by the string resolution.
- Throws:
RuntimeException
- ifresolve
throwsTestEnvironment.Fault
.
-
lookupAndJoinOrFail
Looks up a string using the test environment and joins the result into a single string.- Parameters:
s
- string to resolve.- Returns:
- string obtained by joining array of values produced by the string lookup with spaces.
- Throws:
RuntimeException
- ifresolve
throwsTestEnvironment.Fault
.
-
lookupOneOrNull
Safely looks up a parameter in the test environment. If a parameter is found and has non-empty value then first of the values in the array returned bylookup(String)
is returned. Otherwise, null is returned.- Parameters:
name
- parameter to look up.- Returns:
- first of the values associated with the named parameter, if any; otherwise, null.
-
lookupOneOrEmpty
Safely looks up a parameter in the test environment. If a parameter is found and has non-empty value then first of the values in the array returned bylookup(String)
is returned. Otherwise, empty String is returned.- Parameters:
name
- parameter to look up.- Returns:
- first of the values associated with the named parameter, if any; otherwise, empty String.
-