sim.util
Class SimpleProperties

java.lang.Object
  extended bysim.util.Properties
      extended bysim.util.SimpleProperties
All Implemented Interfaces:
java.io.Serializable

public class SimpleProperties
extends Properties
implements java.io.Serializable

A very simple class for getting and setting object properties. You create this class by passing in the object you'd like to modify. The only properties that are considered are ones which are simple (or boxed) booleans, bytes, shorts, ints, longs, floats, doubles, characters, or strings. Alternatively, you can get a class like this by calling Properties.getProperties(...), which will return either a SimpleProperties or a CollectionProperties, depending on which is appropriate and the flags you have passed in.

A property Foo exists in a class if there is a getFoo() or isFoo() method. ReadWrite properties are ones for which there is ALSO a setFoo(prop) method. If the property is a numerical one, you can also provide a domain in the form of a function called domFoo(), which returns either an array of Objects or a sim.util.Interval. If no domain function exists, or if the domain function returns null, then it is assumed the property has no domain (it can take on any value).

The idea behind domains is to make it easy to create graphical interfaces (sliders, pop-up menus) for the user to set properties, where it's often convenient to know beforehand what values the property can be set to in order to construct the GUI widget appropriately. Here are the domain rules (other than null). If the domain is an Interval, then it is assumed that the property can only take on the values defined within that Interval. Intervals can have both Doubles and Longs as min and max values: if the Interval has Double min/max values, then the interval is assumed to be real-valued, but if the Interval has Long min/max values, then the interval is assumed have integer values only (2.3 wouldn't be a valid setting for the property). If the domain is an array of objects, then the property must be an integer (or long, or short, or byte) property. In this case, it is presumed that the only values the property can take on are the integers 0 through array.length-1, and that the array's elements have toString() values which are representative of those integers. For example, a property called Format might allow the number values 0, 1, and 2, and might have "names" in the array called "Left Justified", "Right Justified", and "Centered" respectively.

This class allows you to set and get properties on the object via boxing the property (java.lang.Integer for int, for example). You can also pass in a String, and SimpleProperties will parse the appropriate value out of the string automatically without you having to bother checking the type.

If any errors arise from generating the properties, setting them, or getting their values, then the error is printed to the console, but is not thrown: instead typically null is returned.

If the object provided to SimpleProperties is sim.util.Proxiable, then SimpleProperties will call propertiesProxy() on that object to get the "true" object whose properties are to be inspected. This makes it possible for objects to create filter objects which only permit access to certain properties. Generally speaking, such proxies (and indeed any object whose properties will be inspected) should be public, non-anonymous classes. For example, imagine that you've got get/set methods on some property Foo, but you only want SimpleProperties to recognize the get method. You can easily do this by making your class Proxiable and providing a proxy which only gets Foo, not sets it, as so:


 public class MyClass extends Proxiable
     {        
     int foo;
    
     public int getFoo() { return foo; }
     public void setFoo(int val) { foo = val; }
    
     public class MyProxy
         {
         public int getFoo() { return foo; }
         }
   
     public Object propertiesProxy() { return new MyProxy(); }
     }
 

See Also:
Serialized Form

Constructor Summary
SimpleProperties(java.lang.Object o)
          Gathers all properties for the object, including ones defined in superclasses.
SimpleProperties(java.lang.Object o, boolean includeSuperclasses, boolean includeGetClass)
          Gathers all properties for the object, possibly including ones defined in superclasses.
SimpleProperties(java.lang.Object o, boolean includeSuperclasses, boolean includeGetClass, boolean includeDomains)
          Gathers all properties for the object, possibly including ones defined in superclasses.
 
Method Summary
 java.lang.Object getDomain(int index)
          Returns the domain of the property at the given index.
 java.lang.String getName(int index)
          Returns the name of the given property.
 java.lang.Class getType(int index)
          Returns the return type of the property (see the TYPE_...
 java.lang.Object getValue(int index)
          Returns the current value of the property.
 boolean isReadWrite(int index)
          Returns whether or not the property can be written as well as read Returns false if the index is out of the range [0 ...
 boolean isVolatile()
          Returns true if the number or order of properties could change at any time
 int numProperties()
          Returns the number of properties discovered
 
Methods inherited from class sim.util.Properties
betterToString, getProperties, getProperties, getTypeConversion, isComposite, setValue, setValue, typeToName
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SimpleProperties

public SimpleProperties(java.lang.Object o)
Gathers all properties for the object, including ones defined in superclasses. SimpleProperties will search the object for methods of the form public Object domProperty() which define the domain of the property. See getDomain(int index) for a description of the domain format.


SimpleProperties

public SimpleProperties(java.lang.Object o,
                        boolean includeSuperclasses,
                        boolean includeGetClass)
Gathers all properties for the object, possibly including ones defined in superclasses. If includeGetClass is true, then the Class property will be included. SimpleProperties will search the object for methods of the form public Object domProperty() which define the domain of the property. See getDomain(int index) for a description of the domain format.


SimpleProperties

public SimpleProperties(java.lang.Object o,
                        boolean includeSuperclasses,
                        boolean includeGetClass,
                        boolean includeDomains)
Gathers all properties for the object, possibly including ones defined in superclasses. If includeGetClass is true, then the Class property will be included. If includeDomains is true, then SimpleProperties will search the object for methods of the form public Object domProperty() which define the domain of the property. See getDomain(int index) for a description of the domain format.

Method Detail

isVolatile

public boolean isVolatile()
Description copied from class: Properties
Returns true if the number or order of properties could change at any time

Specified by:
isVolatile in class Properties

numProperties

public int numProperties()
Returns the number of properties discovered

Specified by:
numProperties in class Properties

getName

public java.lang.String getName(int index)
Returns the name of the given property. Returns null if the index is out of the range [0 ... numProperties() - 1 ]

Specified by:
getName in class Properties

isReadWrite

public boolean isReadWrite(int index)
Returns whether or not the property can be written as well as read Returns false if the index is out of the range [0 ... numProperties() - 1 ]

Specified by:
isReadWrite in class Properties

getType

public java.lang.Class getType(int index)
Returns the return type of the property (see the TYPE_... values) Returns -1 if the index is out of the range [0 ... numProperties() - 1 ]

Specified by:
getType in class Properties

getValue

public java.lang.Object getValue(int index)
Returns the current value of the property. Simple values (byte, int, etc.) are boxed (into Byte, Integer, etc.). Returns null if an error occurs or if the index is out of the range [0 ... numProperties() - 1 ]

Specified by:
getValue in class Properties

getDomain

public java.lang.Object getDomain(int index)
Description copied from class: Properties
Returns the domain of the property at the given index. Domains are defined by methods of the form public Object domProperty() and should generally take one of three forms:
null
no domain (domain is infinite).
An array of elements
the domain consists solely of those elements.
A sim.util.Interval
the domain is an inclusive (closed) numerical range defined by the Interval. If the Interval returns Longs, then the domain is considered to be integral; else it is considered to be real-valued.

Overrides:
getDomain in class Properties