Properties in OKI OSIDs


Mark J. Norton

Sept. 23, 2003



Properties are currently handled using two mechanisms in the OKI OSIDs (v1.0). Properties and PropertiesIterator objects are defined as interfaces in osid.shared. Elsewhere (such as osid.filing), properties are handled by java.util.Map.

Given that properties are already being used throughout the OSIDs, it is important that solid, generic support be provided for properties and that they be used consistently throughout the OSIDs. This document is a set of proposed extensions to the existing support for properties.

This set of classes has been implemented. Download Properties_1_1.zip to view java sources and javadoc.
Requirements

  1. A property consists of a key and value pair.
  2. Support must be provided to group properties together into a property group.
  3. Grouped properties should share a similar type.
  4. It should be possible to group property groups.
  5. Both keys and values should be arbitrary objects.
  6. Support should be provided to add a new property.
  7. Support should be provided to add a new property group.
  8. Support should be provided to change the value of a property.
  9. Support should be provided to access a value given a key.
  10. Support should be provided for iterating over key/value pairs.
  11. Support should be provided for iterating over sets of property groups.
  12. Commonly used value types should be provided.
  13. Properties must be serializable.

Design

A key and value pair is considered to be a Property. When treated as a pair, these entities are contained in an object called a Property. While keys and values may be any arbitrary objects, support needs to be provided for the most common representations. Most keys will be strings. Values are typically boolean, byte, int, long, float, double, String, or a SerializableObject. Since there are differences in the way that Java handles atomic data types versus objects, a set of wrapper objects will be created which extend a basic wrapper called PropertyValue.


Given these wrappers, a Property consists of a key (which is a serializable obect) and a value, which is either a PropertyValue or a SerializableObject.

Properties are grouped together into typed sets called Properties. This is essentially the same object defined by osid.shared.Properties, with minor changes and new methods added. Each Property object has an osid.Type and maintains a list of key/value pairs. How this done is an implementation detail, but the Properties object needs to provide support for accessing values given a key and iterating over key/value pairs.


Definitions

The Properties class defines a type group of properties. The original interface had three simple methods to get a list of keys, get a value given a key (was getProperty()), and get the type of this group. To these, a set of methods have been added to iterate over Property pairs, iterate over sub-property groups, add a new group, and add a property pair.

public interface Properties extends java.io.Serializable {

/* These methods were part of the original osid.shared.Properties. */
SerializableObjectIterator getKeys();
Serializable getValue (Serializable key); // Was getProperty().
Type getType();

/* These methods are proposed. */
PropertyIterator getProperties();
PropertiesIterator getPropertiesGroups();
void addPropertiesGroup (Properties propGroup);
void addProperty (Property prop);
void addProperty (Serializable key, Serializable value);
Property getProperty (Serializable key);
void setProperty (Property prop);
void setValue (Serializable key, Serializable value);
TypeIterator getPropertiesGroupTypes ();
}

The Property interface defines a new class which represents a key and value pairing. As such, it had methods for getting the key or value, and setting the key or value.

public interface Property extends java.io.Serializable {

Serializable getKey();
Serializable getValue();
void setKey (Serializable key);
void setValue (Serializable value);
}

The PropertiesIterator interface is identical to osid.shared.PropertiesInterface, but it has been refined to providing an iterator over property groups. It returns a Properties object when it iterates, which is a group of properties.

public interface PropertiesIterator extends java.io.Serializable {

boolean hasNext();
Properties next();
}

The PropertyIterator is proposed to iterate over key / value pairings, represented as Property objects. It returns a Property object as it iterates.

public interface PropertyIterator extends java.io.Serializable {

boolean hasNext();
Property next();
}

The PropertyValue class provides an abstract definition of property value wrappers. Since each value type is different, this has no methods.

public abstract PropertyValue extends java.io.Serializable {

}

The PropertyValueByte class is a wrapper for a byte value.

pubic class PropertyValueByte extends PropertyValue {

byte getValue();
void setValue (byte value);
}

The PropertyValueInt class is a wrapper for an int value.

pubic class PropertyValueInt extends PropertyValue {

int getValue();
void setValue (byte int
}

The PropertyValueLong class is a wrapper for a long value.

pubic class PropertyValueLong extends PropertyValue {

long getValue();
void setValue long value);
}

The PropertyValueFloat class is a wrapper for a float value.

pubic class PropertyValueFloat extends PropertyValue {

float getValue();
void setValue float value);
}

The PropertyValueDouble class is a wrapper for a double value.

pubic class PropertyValueDouble extends PropertyValue {

double getValue();
void setValue double value);
}

The PropertyValueChar class is a wrapper for a char value.

pubic class PropertyValueChar extends PropertyValue {

char getValue();
void setValue char value);
}

The PropertyValueString class is a wrapper for a string value. Strings are something of a special case. They could be included directly in a Property value, since a String is an object in Java. The wrapper is provided for consistency, and may be optionally used.

pubic class PropertyValueString extendsPropertyValue {

string getValue();
void setValue string value);
}

The PropertyValueBoolean class is a wrapper for a boolean value.

pubic class PropertyValueBoolean extends PropertyValue {

boolean getValue();
void setValue boolean value);
}