Class TestEnvironment

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

public class TestEnvironment extends 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.

  • Constructor Details

    • TestEnvironment

      public TestEnvironment(String name, Map<String,String> propTable, 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

      @Deprecated public TestEnvironment(String name, Map[] propTables, String... propTableNames) throws TestEnvironment.Fault
      Deprecated.
      please use constructor that accepts a list of maps
      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 - 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.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 - 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

      protected TestEnvironment(TestEnvironment o)
  • Method Details

    • addDefaultPropTable

      public static void addDefaultPropTable(String name, Map<String,String> propTable)
      Add a default set of properties to be included when environments are created. Properties are passed in as a Map<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 environment
      propTable - a table of properties to be included when environments are created
      Throws:
      NullPointerException - if either name or propTable is null.
      See Also:
    • addDefaultPropTable

      public static void addDefaultPropTable(String name, Properties propTable)
      Add a default set of properties to be included when environments are created. Properties are passed in as a java.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 environment
      propTable - 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

      public TestEnvironment copy()
      Create a copy of the current environment.
      Returns:
      a copy of the current environment
    • getName

      public 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 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 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(String name, 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(String name, 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(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. 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 Map<String,String[]> getExtraValues()
      Returns:
      all external global properties.
    • lookup

      public String[] lookup(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

      public String[] resolve(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 Set<String> 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 Collection<TestEnvironment.Element> 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

      public Collection<TestEnvironment.Element> 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

      public String lookupOneOrFail(String name)
      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 - if lookup throws TestEnvironment.Fault.
      ArrayIndexOutOfBoundsException - if lookup returns an empty array.
      NullPointerException - if lookup returns null or if the first element of the returned array is null.
    • lookupMultipleOrFail

      public String[] lookupMultipleOrFail(String name)
      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 - if lookup throws TestEnvironment.Fault.
      NullPointerException - if lookup returns null.
    • resolveAndJoinOrFail

      public String resolveAndJoinOrFail(String s)
      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 - if resolve throws TestEnvironment.Fault.
    • resolveMultipleOrFail

      public String[] resolveMultipleOrFail(String s)
      Resolves a string using the test environment.
      Parameters:
      s - string to resolve.
      Returns:
      array of values produced by the string resolution.
      Throws:
      RuntimeException - if resolve throws TestEnvironment.Fault.
    • lookupAndJoinOrFail

      public String lookupAndJoinOrFail(String s)
      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 - if resolve throws TestEnvironment.Fault.
    • lookupOneOrNull

      public String lookupOneOrNull(String name)
      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 by lookup(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

      public String lookupOneOrEmpty(String name)
      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 by lookup(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.