Package sim.util

Class Properties

java.lang.Object
sim.util.Properties
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
CollectionProperties, SimpleProperties
public abstract class Properties extends Object implements Serializable
The abstract superclass of Property inspectors. Such a beast inspects an object and returns a list of variables for which there are get and possibly set methods.

There are two such inspectors: SimpleProperties (inspects objects for their slots) and CollectionProperties (inspects Collections, Maps, and arrays for their contents). The easiest way to get an appropriate Properties subclass instance is to simply call the static method Properties.getProperties(object to inspect, .... ). See the SimpleProperties and CollectionProperties classes for specifics about how they define what a Property is. SimpleProperties in particular will beinteresting..

Property inspectors enumerate the Properties in their provided object. SimpleProperties will enumerate each of the slots; and CollectionProperties will enumerate the elements in the corresponding array, Map, Collection, etc. You get the number of Properties with numProperties(). Properties have the following features:

  • Property Name (Readable). A string, usually the name of the instance variable in the object, a stringified number ("1", "203", etc.) for Collections or Arrays, or a stringified version of the key in a Map.
  • Property Value (Readable and possibly Writable). An object representing the value of the property. Numbers etc. are wrapped in their corresponding wrapper classes.
  • Writability (Readable).
  • Type (Readable). The type of the object as a Class. ints return Integer.TYPE, etc.
  • Composite Nature (Readable). Whether or not the Property is composite or atomic. Atomic types are int, float, etc., plus String.
  • Domain (Readable). Whether or not the object has defined a Domain (a set or range of legal values) for the Property. Domains allow a GUI to set up sliders, pull-down menus and combo-boxes, etc.
  • Description (Readable). A string describing an extended description of the property. Returns null (the default) if there is no extended description.
  • Hiddenness (Readable). A boolean indicating whether the property should be shown to the user.
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected Object
    object
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    Properties()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    protected abstract Object
    _setValue(int index, Object value)
     
    String
    betterToString(Object obj)
    Call this to get a prettier print-name for an object -- converting arrays to a nicer format, for example.
    String
    getDescription(int index)
    Returns the description of the property at the given index.
    Object
    getDomain(int index)
    Returns the domain of the property at the given index.
    abstract String
    getName(int index)
    Returns the name of the property at the given index.
    Object
    getObject()
    Returns the original object from which the properties are extracted
    static Properties
    getProperties(Object object)
    Returns a Properties object for the given object.
    static Properties
    getProperties(Object object, boolean expandCollections, boolean includeSuperclasses, boolean includeGetClass)
    Deprecated.
    use the full version
    static Properties
    getProperties(Object object, boolean expandCollections, boolean includeSuperclasses, boolean includeGetClass, boolean includeExtensions)
    Deprecated.
    use the full version
    static Properties
    getProperties(Object object, boolean expandCollections, boolean includeSuperclasses, boolean includeGetClass, boolean includeExtensions, boolean allowProxy)
    Returns a Properties object for the given object.
    abstract Class
    getType(int index)
    Returns the Class (or for primitive objects, the primitive TYPE) of the property at the given index.
    protected Class
    getTypeConversion(Class type)
     
    abstract Object
    getValue(int index)
    Returns the value of the property at the given index.
    int
    indexForName(String name)
    Returns the index with the given name, else -1 if doesn't exist.
    boolean
    isComposite(int index)
    Returns true if the property at the given index is a "Composite" object, meaning it's not a primitive type (double, int, etc.) nor a String.
    boolean
    isHidden(int index)
    Returns true if the class requested that this property be hidden from the user.
    abstract boolean
    isReadWrite(int index)
    Returns true if the property at the given index is both readable and writable (as opposed to read-only).
    abstract boolean
    isVolatile()
    Returns true if the number or order of properties could change at any time
    abstract int
    numProperties()
    Returns the number of properties discovered in the object.
    Object
    setValue(int index, Object value)
    Sets the current value of the property.
    Object
    setValue(int index, String value)
    Sets the current value of the property to the value parsed from the given string.
    protected String
    typeToName(Class type)
     

    Methods inherited from class java.lang.Object

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

  • Field Details

    • object

      protected Object object

  • Constructor Details

    • Properties

      public Properties()

  • Method Details

    • getProperties

      public static Properties getProperties(Object object)
      Returns a Properties object for the given object. If the object is an array, Map, Indexed, or Collection, then it will be treated using CollectionProperties. Otherwise it will be treated using SimpleProperties. The returned SimpleProperties will include superclasses properties. The Class property will NOT be included. The domFoo() and hideFoo() property extension methods are respected. Domains will always be produced according to the rules in the comments for getDomain(index) below. Proxies and dynamic properties are always permitted.

    • getProperties

      public static Properties getProperties(Object object, boolean expandCollections, boolean includeSuperclasses, boolean includeGetClass)
      Deprecated.
      use the full version
      Returns a Properties object for the given object. If expandCollections is true, then if object is a Map, Indexed, or Collection, then it will be treated using CollectionProperties. Otherwise it will be treated using SimpleProperties. Arrays are always treated using CollectionProperties. If includeSuperclasses is true, then any SimpleProperties will include superclasses. If includeGetClass is true, then the Class property will be included. The domFoo() and hideFoo() property extension methods are respected. Proxies and dynamic properties are always permitted.

    • getProperties

      public static Properties getProperties(Object object, boolean expandCollections, boolean includeSuperclasses, boolean includeGetClass, boolean includeExtensions)
      Deprecated.
      use the full version
      Returns a Properties object for the given object. If expandCollections is true, then if object is a Map, Indexed, or Collection, then it will be treated using CollectionProperties. Otherwise it will be treated using SimpleProperties. Arrays are always treated using CollectionProperties. If includeSuperclasses is true, then any SimpleProperties will include 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. Proxies and dynamic properties are always permitted.

    • getProperties

      public static Properties getProperties(Object object, boolean expandCollections, boolean includeSuperclasses, boolean includeGetClass, boolean includeExtensions, boolean allowProxy)
      Returns a Properties object for the given object. If expandCollections is true, then if object is a Map, Indexed, or Collection, then it will be treated using CollectionProperties. Otherwise it will be treated using SimpleProperties. Arrays are always treated using CollectionProperties. If includeSuperclasses is true, then any SimpleProperties will include superclasses. If includeGetClass is true, then the Class property will be included. If allowProxy is true, then proxies and dynamic properties are permitted. The domFoo() and hideFoo() property extension methods are respected if includeExtensions is true.

    • getObject

      public Object getObject()
      Returns the original object from which the properties are extracted

    • isVolatile

      public abstract boolean isVolatile()
      Returns true if the number or order of properties could change at any time

    • numProperties

      public abstract int numProperties()
      Returns the number of properties discovered in the object.

    • getValue

      public abstract Object getValue(int index)
      Returns the value of the property at the given index.

    • getDomain

      public Object getDomain(int index)
      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.

    • getDescription

      public String getDescription(int index)
      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.

    • isReadWrite

      public abstract boolean isReadWrite(int index)
      Returns true if the property at the given index is both readable and writable (as opposed to read-only).

    • isComposite

      public boolean isComposite(int index)
      Returns true if the property at the given index is a "Composite" object, meaning it's not a primitive type (double, int, etc.) nor a String.

    • isHidden

      public boolean isHidden(int index)
      Returns true if the class requested that this property be hidden from the user. By default, false.

    • getName

      public abstract String getName(int index)
      Returns the name of the property at the given index.

    • indexForName

      public int indexForName(String name)
      Returns the index with the given name, else -1 if doesn't exist. O(n^2)

    • getType

      public abstract Class getType(int index)
      Returns the Class (or for primitive objects, the primitive TYPE) of the property at the given index.

    • _setValue

      protected abstract Object _setValue(int index, Object value)

    • setValue

      public Object setValue(int index, Object value)
      Sets the current value of the property. Simple values (byte, int, etc.) must be boxed (into Byte, Integer, etc.). Then returns the current (hopefully changed) value of the property. Returns null if an error occurs or if the index is out of the range [0 ... numProperties() - 1 ]

    • setValue

      public Object setValue(int index, String value)
      Sets the current value of the property to the value parsed from the given string. Then returns the current (hopefully changed) value of the property. Returns null if an error occurs or if the index is out of the range [0 ... numProperties() - 1 ]

    • getTypeConversion

      protected Class getTypeConversion(Class type)

    • betterToString

      public String betterToString(Object obj)
      Call this to get a prettier print-name for an object -- converting arrays to a nicer format, for example.

    • typeToName

      protected String typeToName(Class type)