From this mailing list thread...

On our last few design calls we've been working through the generic AttributeType mechanism that we're introducing in 1.9. (

/**
 * Capable of converting T to/from a String that can be persisted in the varchar column of a database. 
 * E.g. a date would be stored as yyyy-mm-dd and an image might be stored as a uri pointing to a 
 * PACS system. Also capable of validating T, e.g. so we can use a plain java.util.Date to represent 
 * "date-in-past" but limit its possible values.
 * Defines a String "datatypeHandled", e.g. "date", "regex-validated-string")
 */
interface CustomDatatypeHandler<T> {
  T fromPersistedString(String);
  String toPersistedString(T);
  void validate(T);
  String render(String persistedValue, String view);
  // can be configured with setHandlerConfiguration(String);
}

/**
 * holds the definition of a custom datatype (which is handled by a handler of the above interface). 
 * For example VisitAttributeType and GlobalProperty (we're able to do typed GPs trivially now)
 */
interface CustomDatatyped {
  String getDatatype(); // required
  /**
   * if specified, will be handled by this specific CustomDatatypeHandler, otherwise it will be handled 
   * by the default handler for this thing's datatype
   */
  String getPreferredHandlerClassname(); // optional
  String getHandlerConfig(); // optional
}

/**
 * for user-defined extensions to core domain objects, which would be handled by adding custom 
 * database columns in a less generic system. E.g. VisitAttributeType implements AttributeType<Visit>
 * datatype/handler specified via CustomDatatyped superinterface
 */
interface AttributeType<OwningType extends Customizable> extends CustomDatatyped, OpenmrsMetadata {
  Integer getMinOccurs();
  Integer getMaxOccurs();
}

/**
 * trivial implementations of AttributeType (via BaseAttributeType)
 */
class VisitAttributeType
class LocationAttributeType
class ProviderAttributeType

/**
 * Implemented by domain classes that may be customized by the user via custom attributes. 
 * E.g. Visit implements Customizable<VisitAttribute>, Location implements Customizable<LocationAttribute>
 * Has convenience methods for dealing with a collection of attributes, of different types:
 */
interface Customizable<AttrClass extends Attribute> {
  Collection<AttrClass> getAttributes();  //includes voided
  Collection<AttrClass> getActiveAttributes();  //non-voided
  void addAttribute(AttrClass);
  void setAttribute(AttrClass);  // voids other attributes of the given type
}

/**
* holds a value managed by a CustomDatatypeHandler. E.g. VisitAttribute, GlobalProperty. 
* Any implementation of this has a corresponding CustomDatatyped implementation. "persistedValue"
* is a String suitable for persisting in a db varchar column; "objectValue" is what you'd want 
* to work with in the API.
*/
interface CustomValue {
  String getPersistedValue();
  void setPersistedValue();
  Object getObjectValue();  // don't remember why this isn't <T>
  void setObjectValue(Object);
}

/**
* value corresponding to an AttributeType (which defines its datatype, whether it's 
* required, whether it can repeat, etc), e.g. VisitAttribute corresponds to VisitAttributeType
*/
interface Attribute<OwningType extends Customizable> implements CustomValue, OpenmrsData {
  OwningType getOwner();
  void setOwner(OwningType);
  AttributeType<OwningType> getAttributeType();
}

/**
* trivial implementation of Attribute (via BaseAttribute)
*/
class VisitAttribute
class LocationAttribute
class ProviderAttribute

/**
* this is interesting in that it both defines a custom datatype and stores its value
*/
class GlobalProperty implements CustomDatatyped, CustomValue

Comments welcome.

Roger's notional x-ray object

Roger's proposal

These use cases all rely on the custom data service object and handler object described below. These three use cases show the way the three different uses of custom datatypes interface with the cdso and handler.

Roger's notes on the custom data service object

These are work notes, see below for the final answer

Interface with the custom datatype consumer (settings (formerly Global Properties from platform 1.8 downwards), object attribute, complex obs)

• one object per consumer – in attribute context, this means one per property type; in the settings (formerly Global Properties from platform 1.8 downwards) context, this means one for each property that is being displayed
• constructor() – default handler, handler config="", minOccurs=0, maxOccurs=1
• constructor(String handler, String handlerConfig, int minOccurs, int maxOccurs)
• the consumer loads the custom datatype with all its values and receives them back via save
  • standard interface

    • data is exchanged through a List<CustomDataRow>; deleted objects have newValue=null, new objects have oldValue=null

      public CustomDataRow {
        public String key;  // optionally set by/returned to consumer
        public String oldValue;  // set by/returned to consumer
        public String newValue;  // returned to consumer
        public String voidReason;  // returned to consumer
        public Object data;  // for internal use by custom data service object
      }
      

      The list is copied to a local list on load and then to a temporary list before returning from save; changes to the list by the consumer have no effect and the data object is never returnd to the customer

    • load(List<CustomDataRow>) (empty indicates no values exist)
    • save() : List<CustomDataRow> throws DataError Exception (empty indicates no values exists and none were added; underlying data is saved)
    • customerIterator() : ListIterator<Integer>
  • alternate interface where maxOccurs=1 (throws UnsupportedOperation Exception if maxOccurs != 1)
    • load(String) (null indicates no value exists)
    • save() : String throws DataError Exception (null indicates not set or voided; underlying data is saved)
    • getVoidReason() : String (returns null if not present)
  • both interfaces
    • cancel() (any changes not previously saved are abandoned and the custom data service object is cleared)
    • isDirty() : Boolean (whether any changed have been made to the list)
    • validate() : List<String> (each element is validated and the multiplicity is validated; any errors found are returned as messages; if no errors are found, returns and empty list and dirty is cleared; calling validate before saving guarantees no error will be thrown)
    • cancel() (changes are discarded and loaded data is cleared)
• the custom data service object delegates handler calls to the handler

The Custom Data Service object as a data service

• differs from other datatype services
  • may delegate to other datatype services
  • may have load-on-demand for large objects
  • may delegate to external data sources
    • may need multiple strategies in get/set methods if allocation of data elements between external and internal services changes depending on the external service
• serves the consumer as a data service for the custom datatype
  • uses integer interface to select an element (=0 after load)
    • size() : int
    • index() : int
    • index(int) : int throws DataError Exception (sets and returns index, throwing error if > size()-1
    • getTitle() : String (exposes the short text representation of the indexed)
  • all elements may be get/set, but UnsupportedOperation Exception may be thrown by non-public or read-only elements
    • implemented by calls to getX(null) or setX(null, parameters), see below
• serves the handler as a data service for the custom datatype
  • exposes the list iterator to the handler
  • all elements may be get/set, but UnsupportedOperation Exception may be thrown by read-only elements
    • implemented by calls to getX(this) or setX(this, parameters)
• serves external data sources as a data service for the custom datatype
  • all elements may be get/set, but UnsupportedOperation Exception may be thrown by read-only elements
    • implemented by calls to getX(this) or setX(this, parameters)

Interface with the handler

• The data service object initializes the handler object with its config
• The data service object maintains the iterator and calls validate() for each element as part of its own validate method
• The handler delegates to the data service object calls to the consumer service or other object services to get necessary information
  • Example: get all possible answer concepts to a question concept extracted by the handler from handler config
  • Example: get all values of this element currently existing in the DB
  • Example: get the birthdate of the patient to whom this attribute belongs

Interface for external data sources

• Any connection setup such as logging into a remote service should be done in the constructor; it should be ready to go when the data service object references it

Roger's final design