Class 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

      Nested Classes 
      Modifier and Type Class Description
      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

      Constructors 
      Modifier Constructor Description
      protected TestEnvironment​(TestEnvironment o)  
        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.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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
    • 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()
      • 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.