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

      • 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