Summary
OsidRecord Types identify an interface attached to Extensibles.
The OsidRecord Type
OsidRecords are a means of extending an Extensible. Extensibles encompass both the OsidObject family including OsidQueries, OsidQueryInspectors, OsidForms, and OsidSearchOrders, as well as searches and search results.
Designing An OsidRecord Specification
OsidRecords are interface specifications. They allow the OSID specification to be extended into more specific domains. Another way of saying it is that an OsidRecord extends the agreement between an OSID Consumer and an OSID Provider.
Thinking In Terms of Agreements
There is a tendency to pull the agreement to one side or the other. If an implementor is specifying an OsidRecord, it tends to be generic and often includes other agreements (e.g. object types, property names) for which the OSID Consumer must have knowledge. If an application writer is specifying an OsidRecord, it tends to tie concepts together the OSIDs themselves separated for interoperability.
The trick is to separate yourself and imagine two unknown people, one implementing the interface and the other consuming it, and the likelihood their code will interoperate. Can they reach agreement looking at nothing else other than the OsidRecord specification? This is the same process used for making the OSIDs.
Watch for Cascading Agreements
The OsidRecord mechanism relies on an agreement on the identity of the OsidRecord itself. This identity is expressed as an OsidRecord Type. The OSID Consumer asks for the OsidRecord corresponding to that identifier and the OSID Provider provides it. If there is no agreement on this identifier, there is no interoperability. Knowledge of the identifier includes knowledge of the OsidRecord specification which is its method signatures.
Consider this one:
public interface GenericAssetRecord
implements org.osid.repository.records.AssetRecord {
public String getProperty(String name);
}
While this looks like I can use it for all sorts of things, how does someone use this? There isn't a way for someone on the outside (OSID Consumer) to understand what to do without an additional specification.
The dilemma can be expressed in terms of agreements. I have added additional agreements for the property name and how to process the return value bringing the total number of agreements to three. Most often, one is enough.
Example
public interface PhotographAssetRecord
implements org.osid.repository.records.AssetRecord {
/**
* Gets the ISO Speed rating as a cardinal value.
*/
public long getISOSpeedRating();
/**
* Gets the numerator of the exposure or shutter speed
* as a cardinal value.
*
* The numerator and denominator form the fractional value
* for the exposure time.
*/
public long getExposureNumerator();
/**
* Gets the denominator of the exposure or shutter speed
* as a cardinal value.
*
* The numerator and denominator form the fractional value
* for the exposure time.
*/
public long getExposureDenominator();
/**
* Gets the aperture as a cardinal value.
*/
public long getAperture();
/**
* Gets the focal length equivalent to a 35mm camera.
*/
public java.math.BigDecimal get35MMFocalLength();
}
public interface SongDurationAssetRecord
implements org.osid.repository.records.AssetRecord {
/**
* Gets the duration of the song.
*/
public org.osid.calendaring.Duration getDuration();
}
public interface SongLyricsAssetRecord
implements org.osid.repository.records.AssetRecord {
/**
* Gets the lyrics of the song.
*/
public org.osid.locale.DisplayText getLyrics();
}
Think Compliance, Not Plumbing
I included three examples of AssetRecords. The presence of a PhotographAssetRecord says that this Asset is a photograph and there's some exif-ish information about how it was taken. An OSID Consumer interested in such information would learn that specification. The specificity helps the two parties interoperate across this boundary.
I split the music side into multiple AssetRecords. It tightens the specification in the hopes that if it is a good one, others may adopt it. If it defines the kitchen sink, it may hinder adoption. Managing lyrics feels like a different business than offering a calculated duration. OSID Providers may want to choose what they bite off and support.
How can an OSID Provider be compliant with your OsidRecord? Can an OSID Consumer rely on your OsidRecord? Designing a domain-specific OsidRecord often entails understanding the audience. The same information can be surfaced through different interface designs because their use may be different enough to warrant it.
For example, including the lyrics in the SongLyricsAssetRecord may serve an application which simply displays them. It may not serve a karaoke player well without a more complex interface design.
Supporting Interfaces
org.osid.repository.records.AssetRecord adds to org.osid.repository.Asset and is only one of several OsidRecords needed to support all aspects. A complete specification would include:
- org.osid.repository.records.AssetQueryRecord
- org.osid.repository.records.AssetQueryInspectorRecord
- org.osid.repository.records.AssetFormRecord
- org.osid.repository.records.AssetSearchOrderRecord
Often it is easy enough to mirror the methods like the OSIDs do.
Left Hand / Right Hand Agreements
Sometimes, an OsidRecord is used solely for the purpose of shuttling some information between one OSID Provider and another. These situations tend to be more pragmatic and less of a standards committee meeting.
It is recommended to scrub these OsidRecords on the way out before reaching a wider audience.