Converter Pattern

Overview

Converters wrap one underlying OsidObject, OsidRecord, or OsidList and presents it through a different OSID interface. The conversion is live: nothing is copied at construction, and each method delegates to the underlying object, so later changes to the source are visible through the converter.

Converters compose. OsidList converters pulls each OsidObject from the underlying OsidLIstist performs conversons as it goes. OsidNode converts over that node's OsidObject and over its parent and child OsidNode lists, so an entire hierarchy can be traversed through the target interface without materializing it.

Javadoc Reference

net.okapia.osid.jamocha.adapter.converter

Converter Families

Five families make up the package. The first four narrow a domain term to a type the whole specification shares; the last crosses between domains.

Converts	Example	Package
any OsidList to an `IdList`	`RouteToIdList`	`converter.mapping.route.route`
OsidNode to a hierarchy `Node`	`LocationNodeToNode`	`converter.mapping.locationnode`
OsidNodeListlist to a hierarchy `NodeList`	`LocationNodeToNodeList`	`converter.mapping.locationnode`
CatalogList to the catalog OsidList	`LocationNodeToLocationList`	`converter.mapping.locationnode`
catalog to another domain's catalog	`CatalogToRepository`	`converter.repository.repository`

The catalog family covers all four shapes of a catalog, one set per OsidCatalog in the specification.

Converts	Class	Package
OsidObject	`CatalogToRepository`	`converter.repository.repository`
OsidNode	`CatalogNodeToRepositoryNode`	`converter.repository.repositorynode`
OsidList	`CatalogNodeToRepositoryNodeList`	`converter.repository.repositorynode`
OsidRecord	`CatalogRecordToRepositoryRecord`	`converter.repository.records.repositoryrecord`

Naming and Placement

A converter is named SourceToTarget and is a final class over an abstract template in the sibling spi package.

It lives beside whichever end is domain-specific. For the first four families that is the source, because the target — IdList, a hierarchy Node — belongs to no one domain. For a catalog conversion both ends are catalogs, so placement follows the target: the source, cataloging, is the domain-neutral end. When both ends sit in the same domain, the converter stays with its source.

Example

CatalogHierarchySession session = catalogingManager.getCatalogHierarchySession();
CatalogNode catalogs = session.getCatalogNodes(catalogId, 0, 5, false);

RepositoryNode repositories = new CatalogNodeToRepositoryNode(catalogs, true);
Repository repository = repositories.getRepository();
RepositoryNodeList children = repositories.getChildRepositoryNodes();

Class Declaration Pattern

public final class SourceToTarget
extends AbstractSourceToTarget
implements Target

Constructor Pattern

SourceToTarget(Source source)

Parameter	Type	Description
`source`	`Source`	the term being converted

OsidRecord Handling

OsidRecords are specific to an OsidObject. These converters are a quick and dirty way to pop an OsidRecord of one OsidObject into another.

SourceToTarget(Source source, boolean includeRecords)

Parameter	Type	Description
`source`	`Source`	the OsidObject being converted
`includeRecords`	`boolean`	whether the OsidRecords of the underlying term are brought up as they are

When includeRecords is false — the behavior of the single-argument constructor — the converted OsidObject reports no OsidRecord types, hasRecordType() is false, and the record accessor and getPropertiesByRecordType() throw UnsupportedException.

When it is true, the source's record types are reported unchanged and the record accessor returns the underlying record wrapped in a record converter, so the reported types and the accessor always agree. The flag propagates: a node converter passes it to the object and to the parent and child list converters it creates.