ImaProperties ("Eclipse Amlen" Javadoc Reference)

Package com.ibm.ima.jms

## Interface ImaProperties

-     public interface ImaProperties

  Defines a set of properties used primarily to configure IBM MessageSight JMS client administered objects.

  Properties are defined for the IBM MessageSight JMS client administered objects which are created using ImaJmsFactory. These administered objects implement the ImaProperties interface. The Connection, Session, MessageConsumer, and MessageProducer objects within the IBM MessageSight JMS client also implement the ImaProperties interface with read only properties using the properties of the objects from which they were created.

  In the IBM MessageSight JMS client there are three administered objects:

  ConnectionFactory
    The ConnectionFactory implementation in the IBM MessageSight JMS client implements the three connection factory interfaces: ConnectionFactory, TopicConnectionFactory, and QueueConnectionFactory.
  Queue
    The Queue implementation in the IBM MessageSight JMS client implements two destination interfaces: Destination and Queue.
  Topic
    The Topic implementation in the IBM MessageSight JMS client implements two destination interfaces: Destination and Topic.
  The Connection, Session, MessgeConsumer, and MessageProducer objects within the IBM MessageSight JMS client contain a set of read only properties. These properties are derived from the objects used to create them. Some of the read only properties present state information. Where this is the case, the properties are modified and kept current internally by the JMS client. Properties with names containing the string "user" (other than "userid") can be modified in the read only properties. The MessageProducer and MessageConsumer objects within the IBM MessageSight JMS client contain a set of read only properties which are based on the Destination properties but are expanded as required. If the MessageProducer is created without a Destination, some of these properties will not be set.

  To get the properties associated with any IBM MessageSight object, you can cast it to ImaProperties, or use ImaJmsFactory.getProperties(). In either case, you should either check that the object is an instance of ImaProperties, or catch the ClassCastException.

  Each administered object has a set of properties and these have a simple validation routine. The validation is not done when the property is set, but when validate() is called. The single property validation methods throw a JMSException which is also an ImaJmsException. The multiple property form of validate returns an array of ImaJmsException objects. The properties are valid when the single property validate() methods do not throw exceptions, or when the multiple property form of validate() returns null.

  The names of known properties are processed independent of case and the names are mapped to the preferred case when the property is set.

  When a connection is created with a userid and password, the property "userid" is set on the connection object.

  See Also:
    `The set of properties which can be set for each of the IBM MessageSight JMS client administered objects.`

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static String` | `COPYRIGHT` |
    `static boolean` | `NOWARNINGS` | Do not include warning messages in the array of strings returned by validate.
    `static boolean` | `WARNINGS` | Include warning messages in the array of strings returned by validate.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addValidProperty​(String name, String validator)` | Adds a property name to the set of properties to validate.
    `void` | `clear()` | Clears all properties.
    `boolean` | `exists​(String name)` | Checks if a property has been set.
    `Object` | `get​(String name)` | Returns the value of the specified property as an Object.
    `boolean` | `getBoolean​(String name, boolean default_value)` | Returns the value of the specified property as a boolean.
    `int` | `getInt​(String name, int default_value)` | Returns the value of the specified property as an int.
    `String` | `getString​(String name)` | Returns the value of the specified property as a String.
    `Set<String>` | `propertySet()` | Returns the set of properties.
    `Object` | `put​(String name, Object value)` | Sets a property.
    `void` | `putAll​(Map<String,​Object> map)` | Sets multiple properties.
    `Object` | `remove​(String name)` | Removes a property.
    `int` | `size()` | Gets the number of properties in this object.
    `ImaJmsException[]` | `validate​(boolean nowarn)` | Validates all properties for this object.
    `void` | `validate​(String name, boolean nowarn)` | Validates the named property.
    `void` | `validate​(String name, Object value, boolean nowarn)` | Validates the named property and value.

- - ### Field Detail

    - #### COPYRIGHT

          static final String COPYRIGHT

      See Also:
        Constant Field Values

    - #### WARNINGS

          static final boolean WARNINGS

      Include warning messages in the array of strings returned by validate.
      See Also:
        Constant Field Values

    - #### NOWARNINGS

          static final boolean NOWARNINGS

      Do not include warning messages in the array of strings returned by validate. Use this setting to ignore warnings.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### clear

          void clear()
              throws javax.jms.JMSException

      Clears all properties.
      Throws:
        `IllegalStateException` - If the properties are read only
        `javax.jms.JMSException`

    - #### exists

          boolean exists​(String name)

      Checks if a property has been set.
      Parameters:
        `name` - The name of the property
      Returns:
        true if the property has been set.

    - #### get

          Object get​(String name)

      Returns the value of the specified property as an Object. Any serializable object can be returned as a property value for an administered object
      Parameters:
        `name` - The name of the property
      Returns:
        The object value of the property, or null if it does not exist.

    - #### getInt

          int getInt​(String name,
                     int default_value)

      Returns the value of the specified property as an int. If the property is an enumeration, return the value of the enumeration. If the value is a Boolean, return 0 for false and 1 for true.

      If the property does not exist or cannot be converted to an integer, return the default_value.

      Parameters:
        `name` - The name of the property
        `default_value` - The value to return if the property is missing or not an integer.
      Returns:
        The integer value of the property, or default_value if the property does not exist or cannot be converted to an integer.

    - #### getBoolean

          boolean getBoolean​(String name,
                             boolean default_value)

      Returns the value of the specified property as a boolean. If the property is an enumeration, if the enumerated value is 0 it is false; all other values are true. If the value is an integer, the value 0 is false; all other values are true.

      If the property does not exist or cannot be converted to a boolean, return the default_value.

      Parameters:
        `name` - The name of the property
        `default_value` - The value to return if the property is missing or not a boolean.
      Returns:
        The boolean value of the property, or default_value if the property does not exist or cannot be converted to a boolean.

    - #### getString

          String getString​(String name)

      Returns the value of the specified property as a String. All properties can be represented as a string, but for complex objects the string is only a reference to the object.
      Parameters:
        `name` - The name of the property
      Returns:
        The string value of the property. If the property does not exist, return null.

    - #### propertySet

          Set<String> propertySet()

      Returns the set of properties. This set is a copy of the properties at the time of the call.
      Returns:
        A Set containing the property names available

    - #### put

          Object put​(String name,
                     Object value)
              throws javax.jms.JMSException

      Sets a property.

      Very little checking is done at the time of the set. It is strongly recommended that a validate method be run on the property either before or after it is set. Any serializable object can be set as a value.

      Parameters:
        `name` - The name of the property
        `value` - The new value for the property
      Returns:
        The previous value of the property, which can be null
      Throws:
        `javax.jms.JMSException` - For an internal error of if the object is not serializable
        `IllegalStateException` - If the properties are read-only

    - #### putAll

          void putAll​(Map<String,​Object> map)
               throws javax.jms.JMSException

      Sets multiple properties. Any serializable object can be set as a value.
      Parameters:
        `map` - A map of property name to property values.
      Throws:
        `javax.jms.JMSException` - If any of the property names or values are not valid
        `IllegalStateException` - If the properties are read-only

    - #### remove

          Object remove​(String name)

      Removes a property.
      Parameters:
        `name` - The name of the property to remove
      Returns:
        The previous value of the property, which can be null
      Throws:
        `IllegalStateException` - If the properties are read-only

    - #### size

          int size()

      Gets the number of properties in this object.
      Returns:
        The number of properties in this object.

    - #### validate

          ImaJmsException[] validate​(boolean nowarn)

      Validates all properties for this object. If no errors are found, a null String array is returned.

      This form of validate is able to check that combinations of properties are correct.

      Parameters:
        `nowarn` - Do not include warning messages in the array of messages returned.
      Returns:
        A set of ImaJmsException objects indicating the errors found. or null if no errors are found.

    - #### validate

          void validate​(String name,
                        boolean nowarn)
                 throws javax.jms.JMSException

      Validates the named property. The error string consists of a message ID followed by a colon (:) followed by the message text.

      This form of validate can be used to validate a single property. It is not able to validate any case two or more properties are invalid in combination.

      Parameters:
        `name` - The name of a property
        `nowarn` - Do not include warning messages in the array of messages returned.
      Throws:
        `javax.jms.JMSException` - With the error which was found. This JMSException will always an instance of ImaJmsException.

    - #### validate

          void validate​(String name,
                        Object value,
                        boolean nowarn)
                 throws javax.jms.JMSException

      Validates the named property and value.

      The error string consists of a message ID followed by a colon (:) followed by the message text.

      This form of validate can be used to validate a property before it is set. It can be used in an administration tool.

      Parameters:
        `name` - The name of a property
        `value` - The value to check
        `nowarn` - Do not include warning messages in the array of messages returned.
      Throws:
        `javax.jms.JMSException` - With the error which was found. This JMSException will always an instance of ImaJmsException.

    - #### addValidProperty

          void addValidProperty​(String name,
                                String validator)

      Adds a property name to the set of properties to validate. When the properties are validated using one of the validate() methods, it is an error to have an unknown property. This method allows you to make the property known and adds a simple validation rule. When a property name is added as a valid property, it is allowed for all instances of the same base object type.

      The validation of property names is done in a case independent manner. The name as specified is considered the preferred form.

      Added properties are not used by the IBM MessageSight JMS client, but are kept along with the system properties for use by an application.

      If the name is already a valid property, this method has no effect.

      The validator can be a string which begins with one of the characters:

      B Boolean
        The property must be a boolean, or an integer, or a string which is one of: on, off, true, false, enable, disable, 0, 1.
      I Integer
        The property must be a Number or a String which can be converted to an integer.
      U Unsigned integer
        The property must be a Number or a String which can be converted an integer, and must not be negative.
      S String
        The property may be of any type, since all types can be converted to String.
      Parameters:
        `name` - The name of the property to add
        `validator` - The string indicating the type of the property
      Throws:
        `IllegalStateException` - If the properties are read-only