API:IDataInfo

From Wiketomica
Jump to: navigation, search
API Home Participants API Discussion Demos Downloads Documentation Contact Us Acknowledgements

Reason for existence

IDataInfo is designed to hold non-numeric metadata related to an IData object. Primarily, this is a IDimension and a label (a descriptive string). IDataInfo can be used as a factory for an IData object that with identical structure to the corresponding IData. Although IDataInfo could be merged into IData, the IDataInfo object is useful to have separately so that it can be passed down the Data stream separately from the actual IData, allowing the stream elements to be notified what sort of IData is coming so they can prepare themselves properly. Further work on data-related interfaces continues in bugzilla.

Proposed Interface

We propose the following IDataInfo interface

IDataInfo {

    /**
     * The number of numerical values contained in the IData object.
     */
    readonly attribute int length;

    /**
     * The descriptive label of the data, as given in constructor.
     */
    readonly attribute string label;

    /**
     * Returns an IData object appropriate for this IDataInfo instance.
     */
    IData makeData();
}

Use

We expect IDataSinks to use the IDataInfo they receive to decide if they understand the data structure they're receiving and if some sort of conversion needs to be done. They can use the the IDataInfo as a data factory to create their own IData instance if they want to store (and perhaps send on) some sort of processed or transformed data. The IDataInfo also allows them to create a new IDataInfo instance (via the IDataInfoFactory) that contains their own tag and that's appropriate for their own IData.

IDataInfo's tags can be used to identify and distinguish data that might be collected in an IDataSink (like a plot).

Etomica has a concrete IDataInfo class for each concrete IData class. This allows an IDataInfo recipient to know the concrete IData class without needing an extra method in the IDataInfo interface.

Notes

It's not clear whether one codebase will need to be able to explicitly create new instances of IDataInfo from another codebase. If this is necessary, IDataInfo will need additional method(s) to configure new instances (or they could make an IDataInfoFactory and use that).

The IDataInfo's getLabel typically returns some sort of string built up from the various components along the Data stream. The string is rarely the most appropriate thing to be showing the user although the programmer would probably understand it. Displays typically allow the programmer to override the string.