Package com.xceptance.xlt.api.util

# Class XltProperties

java.lang.Object
com.xceptance.xlt.api.util.XltProperties

public abstract class XltProperties extends Object
The property keeper. Loads and stores the properties of the entire tool. Single instance implementation.

The process of looking up a property uses multiple fall-backs. When resolving the value for the key "foo.bar", for instance, the following effective keys are tried, in this order:

1. the test user name plus simple key, e.g. "TOrder.foo.bar"
2. the test class name plus simple key, e.g. "posters.loadtest.tests.TOrder.foo.bar"
3. the simple key, i.e. "foo.bar"

This multi-step process allows for test-user-specific or test-class-specific overrides of certain settings, while falling back to the globally defined values if such specific settings are absent.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `DEFAULT_PROPERTIES`
  Constants to indicate the name of the base properties
  `static final String`
  `DEVELOPMENT_PROPERTIES`
  `static final String`
  `PROJECT_PROPERTIES`
  `static final String`
  `SECRET_PROPERTIES`
  `static final String`
  `SYSTEM_PROPERTIES`
  `static final String`
  `TEST_PROPERTIES`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `XltProperties()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract XltProperties`
  `clear()`
  Clears all properties but does not do anything else.
  `abstract boolean`
  `containsKey(String key)`
  Checks whether there is a mapping for the specified key in this property list.
  `abstract Path`
  `getConfigDirectory()`
  Returns the test suite's config directory.
  `abstract Properties`
  `getCopyOfProperties()`
  Returns a copy of all the internally stored properties, with any placeholder resolved.
  `abstract Path`
  `getDataDirectory()`
  Returns the test suite's data directory.
  `abstract String`
  `getEffectiveKey(Session session, String bareKey)`
  Returns the effective key to be used for property lookup via one of the getProperty(...) methods.
  `abstract String`
  `getEffectiveKey(String testCaseClassName, String userName, String bareKey)`
  Behaves like `getEffectiveKey(Session, String)` but without the session dependency
  `static XltProperties`
  `getInstance()`
  Returns the one and only XltProperties instance.
  `abstract Properties`
  `getProperties()`
  Returns a reference to the properties.
  `abstract Map<String,String>`
  `getPropertiesForKey(String domainKey)`
  Returns all properties whose name starts with the given domain key.
  `abstract Optional<String>`
  `getProperty(Session session, String key)`
  Searches for the property with the specified key in this property list.
  `abstract String`
  `getProperty(String key)`
  Searches for the property with the specified key in this property list.
  `abstract boolean`
  `getProperty(String key, boolean defaultValue)`
  Searches for the property with the specified key in this property list.
  `abstract int`
  `getProperty(String key, int defaultValue)`
  Searches for the property with the specified key in this property list.
  `abstract long`
  `getProperty(String key, long defaultValue)`
  Searches for the property with the specified key in this property list.
  `abstract String`
  `getProperty(String key, String defaultValue)`
  Searches for the property with the specified key in this property list.
  `abstract LinkedHashMap<String,Properties>`
  `getPropertyBuckets()`
  Returns an ordered list of property sources.
  `abstract String`
  `getPropertyRandomValue(String key, String defaultValue)`
  Returns one value of the given multi-value property.
  `abstract long`
  `getStartTime()`
  Returns the start time of the test in milliseconds since 1970.
  `abstract String`
  `getVersion()`
  Returns the product version.
  `abstract boolean`
  `isDevMode()`
  Do we run in dev mode such as Maven or Eclipse or similar?
  `abstract boolean`
  `isLoadTest()`
  Do we run in load test mode?
  `abstract void`
  `removeProperty(String key)`
  Removes the property with the given key from the internal properties store.
  `abstract void`
  `setProperties(Properties newProperties)`
  Method for changing the properties during runtime.
  `abstract void`
  `setProperty(String key, String value)`
  Sets a property during runtime.

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### DEFAULT_PROPERTIES

    public static final String DEFAULT_PROPERTIES
    Constants to indicate the name of the base properties
    See Also:
      - Constant Field Values

  - ### PROJECT_PROPERTIES

    public static final String PROJECT_PROPERTIES
    See Also:
      - Constant Field Values

  - ### TEST_PROPERTIES

    public static final String TEST_PROPERTIES
    See Also:
      - Constant Field Values

  - ### DEVELOPMENT_PROPERTIES

    public static final String DEVELOPMENT_PROPERTIES
    See Also:
      - Constant Field Values

  - ### SECRET_PROPERTIES

    public static final String SECRET_PROPERTIES
    See Also:
      - Constant Field Values

  - ### SYSTEM_PROPERTIES

    public static final String SYSTEM_PROPERTIES
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### XltProperties

    public XltProperties()

- ## Method Details

  - ### getInstance

    public static XltProperties getInstance()
    Returns the one and only XltProperties instance.
    Returns:
      the XltProperties singleton

  - ### containsKey

    public abstract boolean containsKey(String key)
    Checks whether there is a mapping for the specified key in this property list.
    Parameters:
      `key` - the property key
    Returns:
      `true` if there is a mapping, `false` otherwise

  - ### getCopyOfProperties

    public abstract Properties getCopyOfProperties()
    Returns a copy of all the internally stored properties, with any placeholder resolved.
    Returns:
      the properties

  - ### getProperties

    public abstract Properties getProperties()
    Returns a reference to the properties. This is mainly here for speed. Deal with it at your own discretion. You are not supposed to modify these!
    Returns:
      the properties

  - ### getPropertyBuckets

    public abstract LinkedHashMap<String,Properties> getPropertyBuckets()
    Returns an ordered list of property sources. This allows a more tailored access if needed. Don't write to these properties, because XLT will not pay any attention. This is mainly meant when you want to extend the property concept in a test suite for your own pleasure. Please keep in mind that this is all shared across test threads, hence it is read-only which is also in parts enforced.

  - ### getPropertiesForKey

    public abstract Map<String,String> getPropertiesForKey(String domainKey)
    Returns all properties whose name starts with the given domain key. The domain is stripped from the resulting property names.
    Parameters:
      `domainKey` - domain for the properties
    Returns:
      a map with all matching properties

  - ### getProperty

    public abstract String getProperty(String key)
    Searches for the property with the specified key in this property list. The method returns null if the property is not found. This method will lookup the session from the context automatically!
    Parameters:
      `key` - the property key
    Returns:
      the value of the key

  - ### getProperty

    public abstract Optional<String> getProperty(Session session, String key)
    Searches for the property with the specified key in this property list. The method returns null if the property is not found. In most cases, `getProperty(String)`} will be sufficient. For testing and more advanced use cases, a session context can be passed in.
    Parameters:
      `session` - the session information to use to enhance the lookup
      `key` - the property key
    Returns:
      the value of the key
    Since:
      7.0.0

  - ### getProperty

    public abstract boolean getProperty(String key, boolean defaultValue)
    Searches for the property with the specified key in this property list. The method returns the default value argument if the property is not found.
    Parameters:
      `key` - the property key
      `defaultValue` - the defaultValue if key not found
    Returns:
      the value of the key as a boolean

  - ### getProperty

    public abstract int getProperty(String key, int defaultValue)
    Searches for the property with the specified key in this property list. The method returns the default value argument if the property is not found.
    Parameters:
      `key` - the property key
      `defaultValue` - the defaultValue if key not found
    Returns:
      the value of the key as an int

  - ### getProperty

    public abstract long getProperty(String key, long defaultValue)
    Searches for the property with the specified key in this property list. The method returns the default value argument if the property is not found.
    Parameters:
      `key` - the property key
      `defaultValue` - the defaultValue if key not found
    Returns:
      the value of the key as a long

  - ### getProperty

    public abstract String getProperty(String key, String defaultValue)
    Searches for the property with the specified key in this property list. The method returns the default value argument if the property is not found. The key is upper-cased before the property will be searched.
    Parameters:
      `key` - the property key
      `defaultValue` - the defaultValue if key not found
    Returns:
      the value of the key

  - ### getPropertyRandomValue

    public abstract String getPropertyRandomValue(String key, String defaultValue)
    Returns one value of the given multi-value property. Multiple values are separated by comma, semicolon, or space. The returned value is chosen randomly from the set of values.
    Parameters:
      `key` - the name of the property
      `defaultValue` - the default property value (a multi-value)
    Returns:
      one of the values, chosen randomly

  - ### getStartTime

    public abstract long getStartTime()
    Returns the start time of the test in milliseconds since 1970.
    Returns:
      the start time of the test in milliseconds

  - ### getEffectiveKey

    public abstract String getEffectiveKey(Session session, String bareKey)
    Returns the effective key to be used for property lookup via one of the getProperty(...) methods.

    When looking up a key, "password" for example, the following effective keys are tried, in this order:

    1. the prefix "secret." plus the simple key to ensure precedence of secret properties over public ones
    2. the test user name plus simple key, e.g. "TAuthor.password"
    3. the test class name plus simple key, e.g. "com.xceptance.xlt.samples.tests.TAuthor.password"
    4. the simple key, e.g. "password"
    This method has been opened so that property extensions can use this logic for their own purpose if needed.
    Parameters:
      `session` - the session to get utility data from
      `bareKey` - the bare property key, i.e. without any prefixes
    Returns:
      the first key that produces a result
    Since:
      7.0.0

  - ### getEffectiveKey

    public abstract String getEffectiveKey(String testCaseClassName, String userName, String bareKey)
    Behaves like `getEffectiveKey(Session, String)` but without the session dependency
    Parameters:
      `testCaseClassName` - the classname the property might have been extended with
      `userName` - the current username which might be in the property name
      `bareKey` - the key without any prefixes
    Returns:
    Since:
      7.0.0

  - ### getVersion

    public abstract String getVersion()
    Returns the product version.
    Returns:
      the version string, e.g. "1.1.0"

  - ### getConfigDirectory

    public abstract Path getConfigDirectory()
    Returns the test suite's config directory.
    Returns:
      the config directory path

  - ### getDataDirectory

    public abstract Path getDataDirectory()
    Returns the test suite's data directory.
    Returns:
      the data directory path

  - ### removeProperty

    public abstract void removeProperty(String key)
    Removes the property with the given key from the internal properties store.
    Parameters:
      `key` - the property key

  - ### setProperties

    public abstract void setProperties(Properties newProperties)
    Method for changing the properties during runtime. Can be called multiple times to add additional properties. It does not apply System properties automatically anymore!!! If you need that in your logic, simply run `#setProperties(System.getProperties()`
    Parameters:
      `newProperties` - complete new set of properties, will be added to existing properties and overwrites already defined properties with new values. None existing properties will be added.

  - ### setProperty

    public abstract void setProperty(String key, String value)
    Sets a property during runtime. Overwrites an existing property with the same name. Does not re-apply any java system settings.
    Parameters:
      `key` - new property key
      `value` - new property value

  - ### clear

    public abstract XltProperties clear()
    Clears all properties but does not do anything else. This is a dangerous operation!
    Returns:
      the cleared instance

  - ### isLoadTest

    public abstract boolean isLoadTest()
    Do we run in load test mode?
    Returns:
      true if this instance is running a load test aka this is executed by an agent

  - ### isDevMode

    public abstract boolean isDevMode()
    Do we run in dev mode such as Maven or Eclipse or similar?
    Returns:
      true if this instance is running a dev mode, false otherwise