Package sim.util

Class SimpleProperties

java.lang.Object
sim.util.Properties
sim.util.SimpleProperties
All Implemented Interfaces:
Serializable

public class SimpleProperties extends Properties implements 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). You can also hide a property by creating a boolean method called hideFoo() which returns true.

A few classes have special hard-coded properties because they lack get() and set() methods. Notably: CharSequences (Strings, StringBuffers, StringBuilders, etc.) have toString() considered a property, integer Numbers have longValue() considered a property, other Numbers have doubleValue() considered a property, and Booleans have booleanValue() considered a property. In all cases the name of the property is simply "Value" and it is read-only.

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 your property type is a float or double, you can return a domain in the form of an Interval, with a double-valued minimum maximum value. This will typically result in the GUI creating a slider.
  • If your property type is an integer type (byte/short/int/long), you can return a domain in the form of an Interval with a long-valued minimum and maximum value. This will typically result in the GUI creating a slider.
  • If your property type is an integer type (byte/short/int/long), and you want your domain to be just the integers 0 ... n, you can return an array (n long) of Strings, each representing a name for the corresponding integer value. This will typically result in the GUI creating a pop-up list or menu, displaying those string labels, and then setting the property to the equivalent number. 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. Furthermore you have another property called Bar that you want hidden entirely. You can easily do this by making your class Proxiable and providing an inner-class proxy like this:


 import sim.util.Proxiable;

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

If the object provided to SimpleProperties is sim.util.Propertied, then SimpleProperties will not scan the object, but instead query the object for a Properties of its own, using the object's properties() method. All accesses to the SimpleProperties will simply get routed to that Properties object instead. This is another filter approach which enables dynamically changing properties, or properties based on features other than get... and set... methods.

See Also:
  • Constructor Details

    • SimpleProperties

      public SimpleProperties(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. The domFoo() and hideFoo() property extension methods are respected.
    • SimpleProperties

      public SimpleProperties(Object o, boolean allowProxy)
      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. The domFoo() and hideFoo() property extension methods are respected.
    • SimpleProperties

      public SimpleProperties(Object o, boolean includeSuperclasses, boolean includeGetClass)
      Deprecated.
      Use the full form
      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. The domFoo() and hideFoo() property extension methods are respected.
    • SimpleProperties

      public SimpleProperties(Object o, boolean includeSuperclasses, boolean includeGetClass, boolean includeExtensions)
      Gathers all properties for the object, possibly including ones defined in superclasses. If includeGetClass is true, then the Class property will be included. The domFoo() and hideFoo() property extension methods are respected if includeExtensions is true.
    • SimpleProperties

      public SimpleProperties(Object o, boolean includeSuperclasses, boolean includeGetClass, boolean includeExtensions, boolean allowProxy)
      Gathers all properties for the object, possibly including ones defined in superclasses. If includeGetClass is true, then the Class property will be included. The domFoo() and hideFoo() property extension methods are respected if includeExtensions is true.
  • Method Details

    • makeAlphabeticalComparator

      public Comparator makeAlphabeticalComparator()
    • makeSimpleComparator

      public Comparator makeSimpleComparator(String[] filter)
    • sortAlphabetically

      public SimpleProperties sortAlphabetically()
      Sorts the properties by an Alphabetical Comparator (provided by makeAlphabeticalComparator()). If the underlying object is Propertied, sorting has no effect. Returns the original SimpleProperties, now sorted.
    • sort

      public SimpleProperties sort(String[] filter)
      Sorts the properties by an Simple Comparator (provided by makeSimpleComparator()). If the underlying object is Propertied, sorting has no effect. Returns the original SimpleProperties, now sorted.
    • sortProperties

      public void sortProperties(Comparator c)
      Deprecated.
      Use sort(...) instead.
    • sort

      public SimpleProperties sort(Comparator c)
      Sorts the properties by the following comparator, which takes two java.lang.reflect.Method objects: these are getMethods for two properties. Note that if SimpleProperties has an auxillary, this method does nothing.

      By default SimpleProperties sorts alphabetically by method name, breaking ties by number of arguments (fewer arguments appear earlier), and breaking ties further by lexicographic comparison of the output of each Method's toGenericString() method.

      If the underlying object is Propertied, sorting has no effect.

      Returns the original SimpleProperties, now sorted.

    • 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 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 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 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
    • _setValue

      protected Object _setValue(int index, Object value)
      Specified by:
      _setValue in class Properties
    • getDescription

      public String getDescription(int index)
      Description copied from class: Properties
      Returns the description of the property at the given index. Descriptions are defined by methods of the form desProperty() and are either null (no description), or are Strings, possibly including HTML data. The primary function of description methods is to provide tooltip information for widgets describing the Property.
      Overrides:
      getDescription in class Properties
    • getDomain

      public 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
    • isHidden

      public boolean isHidden(int index)
      Description copied from class: Properties
      Returns true if the class requested that this property be hidden from the user. By default, false.
      Overrides:
      isHidden in class Properties
    • getPropertiesSubset

      public SimpleProperties getPropertiesSubset(String[] propertyNames, boolean retain)
      Produces a new SimpleProperties which is a strict subset of the existing SimpleProperties where the properties found in propertyNamesToRetain are retained and other properties are removed. The existing SimpleProperties must not use an auxillary. The new SimpleProperties has the same volatility and object as the original.
    • toString

      public String toString()
      Overrides:
      toString in class Object