Core Service Interface Definitions osid version 3.0.0

The Open Service Interface Definitions (OSIDs) is a service-based architecture to promote software interoperability. The OSIDs are a large suite of interface contract specifications that describe the integration points among services and system components for the purpose of creating choice among a variety of different and independently developed applications and systems, allowing independent evolution of software components within a complex system, and federated service providers.

The OSIDs were initially developed in 2001 as part of the MIT Open Knowledge Initiative Project funded by the Andrew W. Mellon Foundation to provide an architecture for higher education learning systems. OSID 3K development began in 2006 to redesign the capabilities of the specifications to apply to a much broader range of service domains and integration challenges among both small and large-scale enterprise systems.

The osid package defines the building blocks for the OSIDs which are defined in packages for their respective services. This package defines the top-level interfaces used by all the OSIDs as well as specification metadata and the OSID Runtime interface.

Meta Interfaces and Enumerations

OSID: an enumeration listing the OSIDs defined in the specification.

Syntax: an enumeration listing primitive types

Metadata: an interface for describing data constraints on a data element

Interface Behavioral Markers

Interface behavioral markers are used to tag a behavioral pattern of the interface used to construct other object interfaces.

OsidPrimitive: marks an OSID interface used as a primitive. OSID primitives may take the form interfaces if not bound to a language primitive. Interfaces used as primitives are marked to indicate that the underlying objects may be constructed by an OSID Consumer and an OSID Provider must honor any OSID primitive regardless of its origin.

Identifiable: Marks an interface identifiable by an OSID Id.

Extensible: Marks an interface as extensible through OsidRecords.

Browsable: Marks an interface as providing Property inspection for its OsidRecords.

Suppliable: Marks an interface as accepting data from an OSID Consumer.

Temporal: Marks an interface that has a lifetime with begin an end dates.

Subjugateable: Mars an interface that is dependent on another object.

Aggregateable: Marks an interface that contains other objects normally related through other services.

Containable: Marks an interface that contains a recursive reference to itself.

Sourceable: Marks an interface as having a provider.

Federateable: Marks an interface that can be federated using the OSID Hierarchy pattern.

Operable: Marks an interface as responsible for performing operatons or tasks. Operables may be enabled or disabled.

Abstract service Interfaces

OsidProfile: Defines interoperability methods used by OsidManagers.

OsidManager: The entry point into an OSID and provides access to OsidSessions.

OsidProxyManager: Another entry point into an OSID providing a means for proxying data from a middle tier application server to an underlying OSID Provider.

OsidSession : A service interface accessible from an OsidManager that defines a set of methods for an aspect of a service.

Object-like interfaces are generally defined along lines of interoperability separating issues of data access from data management and searching. These interfaces may also implement any of the abstract behavioral interfaces listed above. The OSIDs do not adhere to a DAO/DTO model in its service definitions in that there are service methods defined on the objects (although they can be implemented using DTOs if desired). For the sake of an outline, we’ll pretend they are data objects.

OsidObject: Defines object data. OsidObjects are accessed from OsidSessions. OsidObjects are part of an interface hierarchy whose interfaces include the behavioral markers and a variety of common OsidObjects. All OsidObjects are Identifiable, Extensible, and have a Type. There are several variants of OsidObjects that indicate a more precise behavior.

OsidObjectQuery: Defines a set of methods to query an OSID for its OsidObjects . An OsidQuery is accessed from an OsidSession.

OsidObjectQueryInspector: Defines a set of methods to examine an OsidQuery.

OsidObjectForm: Defines a set of methods to create and update data. OsidForms are accessed from OsidSessions.

OsidObjectSearchOrder: Defines a set of methods to order search results. OsidSearchOrders are accessed from OsidSessions.

Most objects are or are derived from OsidObjects. Some object interfaces may not implement OsidObejct but instead derive directly from interface behavioral markers. Other OsidObjects may include interface behavioral markers to indicate functionality beyond a plain object. Several categories of OsidObjects have been defined to cluster behaviors to semantically distinguish their function in the OSIDs.

OsidCatalog: At the basic level, a catalog represents a collection of other OsidObjects. The collection may be physical or virtual and may be federated to build larger OsidCatalogs using hierarchy services. OsidCatalogs may serve as a control point to filter or constrain the OsidObjects that may be visible or created. Each OsidCatalog may have its own provider identifty apart from the service provider.

OsidRelationship: Relates two OsidObjects. The OsidRelationship represents the edge in a graph that may have its own relationship type and data. OsidRelationships are Temporal in that they have a time in which the relationship came into being and a time when the relationship ends.

OsidRule: Defines an injection point for logic. An OsidRule may represent some constraint, evaluation, or execution. While authoring of OsidRules is outside the scope of the OSIDs, an OsidRule provides the mean to identify the rule and map it to certain OsidObjects to effect behavior of a service.

The most basic operations of an OSID center on retrieval, search, create & update, and notifications on changes to an OsidObject. The more advanced OSIDs model a system behavior where a variety of implicit relationships, constraints and rules come into play.

OsidGovernator: Implies an activity or operation exists in the OSID Provider acting as an Operable point for a set of rules governing related OsidObjects. The OsidGovernator represents an engine of sorts in an OSID Provider and may have its own provider identity.

OsidCompendium : OsidObjects which are reports or summaries based on transactional data managed elsewhere.

Managing data governing rules occurs in a separate set of interfaces from the effected OsidObjects (and often in a separate package). This allows for a normalized set of rules managing a small set of control points in a potentially large service.

OsidEnabler: A managed control point to enable or disable the operation or effectiveness of another OsidObject . Enablers create a dynamic environment where behaviors and relationships can come and go based on rule evauations.

OsidConstrainer: A managed control point to configure the constraints on the behavior of another OsidObject.

OsidProcessor: A managed control point to configure the behavior of another OsidObject where some kins of processing is implied.

Other Abstract Interfaces

OsidSearch: Defines set of methods to manage search options for performing searches.

OsidSearchResults: Defines a set of methods to examine search results.

OsidReceiver: Defines a set of methods invoked for asynchronous notification.

OsidList: Defines a set of methods to sequentially access a set of objects.

OsidNode: An interface used by hierarchy nodes.

OsidCondition: An input or “statement of fact” into an OsidRule evaluation.

OsidInput: An input of source data into an OsidRule processor.

OsidResult: The output from processing an OsidRule.

OsidRecord: An interface marker for an extension to another interface. OsidRecord are negotiated using OSID Types.

Property: Maps a name to a value. Properties are available in OSID objects to provide a simplified view of data that may exist within a typed interface.

PropertyList: A list of properties.

Runtime

OsidRuntimeProfile: The OsidProfile for the runtime OsidManager.

OsidRuntimeManager: The OSID Runtime service.

Abstract Flow

Generally, these definitions are abstract and not accesed directly. They are used as building blocks to define interfaces in the OSIDs themselves. OSIDs derive most of their definitions from a definition in the osid package. The methods that are defined at this abstract level versus the methods defined directly in a specific OSID is determined by the typing in the method signatures. The osid package interfaces are a means of ensuring consistency of common methods and not designed to facilitate object polymorphism among different OSIDs. A language binder may elect to alter the interface hierarchy presented in this specification and a provider need not parallel these interfaces in their implementations.

The flow of control through any OSID can be described in terms of these definitions. An OsidManager or OsidProxyManager is retrieved from the OsidRuntimeManager for a given service. Both types of managers share an interface for describing what they support in the OsidProfile.

OsidSessions are created from the OsidManager. OsidSessions tend to be organized along clusters of like-functionality. Lookup- oriented sessions retrieve OsidObjects. Return of multiple OsidObjects is done via the OsidList. Search-oriented sessions retrieve OsidObjects through searches provided through the OsidQuery and OsidSearch interfaces.

Administrative-oriented sessions create and update OsidObjects using the OsidForm interface. The OsidForm makes available Metadata to help define its rules for setting and changing various data elements.

OsidObjects can be organized within OsidCatalogs. An OsidCatalog is hierarchical and can be traversed through an OsidNode. An OsidQuery or an OsidSearchOrder may be mapped to a dynamic OsidCatalog. Such a query may be examined using an OsidQueryInspector.

A notification session provides a means for subscribing to events, “a new object has been created”, for example, and these events are received from an OsidReceiver.

Meta OSID Specification

The OSID Specification framework defines the interace and method structures as well as the language primitives and errors used throughout the OSIDs. The OSID Specifications are defined completely in terms of interfaces and the elements specified in the meta specification.

Language Primitives

Ths meta OSID Specification enumerates the allowable language primitives that can be used in OSID method signatures. Parameters and returns in OSID methods may be specified in terms of other OSID interfaces or using one of these primitives. An OSID Binder translates these language primitives into an appropriate language primitive counterpart.

An OSID Primitive differs from a language primitive. An OSID Primitive is an interface used to describe a more complex structure than a simple language primitive can support. Both OSID Primitives and language primitives have the same behavior in the OSIDs in that an there is no service encapsulation present allowing OSID Primitives to be consructed by an OSID Consumer.

Errors

OSID methods are required to return a value, if specified, or return one of the errors specified in the method signature. The meta package defines the set of errors that a method signtaure may use.

Errors should result when the contract of the interface as been violated or cannot be fulfilled and it is necessary to disrupt the flow of control for a consumer. Different errors are specified where it is forseen that a consumer may wish to execute a different action without violating the encapsulation of internal provider operations. Such actions do not include debugging or other detailed information which is the responsibility of the provider to manage. As such, the number of errors defined across all the interfaces is kept to a minimum and the context of the error may vary from method to method in accordance with the spceification.

Errors are categorized to convey the audience to which the error pertains.

User Errors: Errors which may be the result of a user operation intended for the user.

Operational Errors: Errors which may be the result of a system or some other problem intended for the user.

Consumer Contract Errors: Software errors resulting in the use of the OSIDs by an OSID Consumer intended for the application programmer. These also include integration problems where the OSID Consumer bypassed a method to test for support of a service or type.

Provider Contract Errors: Software errors in the use of an OSID by an OSID Provider intended for an implementation programmer.

Compliance

OSID methods include a compliance statement indicating whether a method is required or optional to implement. An optional OSID method is one that defines an UNIMPLEMENTED error and there is a corresponding method to test for the existence of an implementation.

OSID 3K Acknowledgements

Tom Coppeto (Editor & Architect)

Scott Thorne (Architect)

The authors gratefully acknowledge the following individuals for their time, wisdom, and contributions in shaping these specifications.

Adam Franco, Middlebury College

Jeffrey Merriman, Massachusetts Institute of Technology

Charles Shubert, Massachusetts Insitute of Technology

Prof. Marc Alier, Universitat Politècnica de Catalyuna

Joshua Aresty, Massachusetts Institute of Technology

Fabrizio Cardinali, Giunti Labs

Pablo Casado, Universitat Politècnica de Catalyuna

Alex Chapin, Middlebury College

Craig Counterman, Massachusetts Institute of Technology

Francesc Santanach Delisau, Universitat Oberta de Catalyuna

Prof. Llorenç Valverde Garcia, Universitat Oberta de Catalyuna

Catherine Iannuzzo, Massachusetts Institute of Technology

Jeffrey Kahn, Verbena Consulting

Michael Korcynski, Tufts University

Anoop Kumar, Tufts University

Eva de Lera, Universitat Oberta de Catalyuna

Roberto García Marrodán, Universitat Oberta de Catalyuna

Andrew McKinney, Massachusetts Institute of Technology

Scott Morris, Apple

Mark Norton, Nolaria Consulting

Mark O’Neill, Dartmouth College

Prof. Charles Severance, University of Michigan

Stuart Sim, Sun Microsystems/Common Need

Colin Smythe, IMS Global Learning Consortium

George Ward, California State University

Peter Wilkins, Massachusetts Institute of Technology

Norman Wright, Massachusetts Institute of Technology

O.K.I. Acknowledgements

OSID 3K is based on the O.K.I. OSIDs developed as part of the MIT Open Knowledge Initiative (O.K.I) project 2001-2004.

Vijay Kumar, O.K.I. Principal Investigator, Massachusetts Insitute of Technology

Jeffrey Merriman, O.K.I. Project Director, Massachusetts Insitute of Technology

Scott Thorne, O.K.I. Chief Architect, Massachusetts Institute of Technology

Charles Shubert, O.K.I. Architect, Massachusetts Institute of Technology

Lois Brooks, Project Coordinator, Stanford University

Mark Brown, O.K.I. Project Manager, Massachusetts Institute of Technology

Bill Fitzgerald, O.K.I. Finance Manager, Massachusetts Institute of Technology

Judson Harward, Educational Systems Architect, Massachusetts Institute of Technology

Charles Kerns, Educational Systems Architect, Stanford University

Jeffrey Kahn, O.K.I. Partner, Verbena Consulting

Judith Leonard, O.K.I. Project Administrator, Massachusetts Institute of Technology

Phil Long, O.K.I. Outreach Coordinator, Massachusetts Institute of Technology

Cambridge University, O.K.I. Core Collaborator

Dartmouth College, O.K.I. Core Collaborator

Massachusetts Institute of Technology, O.K.I. Core Collaborator

North Carolina State University, O.K.I. Core Collaborator

Stanford University, O.K.I. Core Collaborator

University of Michigan, O.K.I. Core Collaborator

University of Pennsylvania, O.K.I. Core Collaborator

University of Wisconsin, Madison, O.K.I. Core Collaborator

Service Managers¶

Osid Manager¶

class dlkit.services.osid.OsidManager¶

Bases: dlkit.services.osid.OsidProfile

The OsidManager is the top level interface for all OSID managers.

An OSID manager is instantiated through the OsidRuntimeManager and represents an instance of a service. An OSID manager is responsible for implementing a profile for a service and creating sessions that, in general, correspond to the profile. An application need only create a single OsidManager per service and implementors must ensure the OsidManager is thread-safe ``. The ``OsidSessions spawned from an OSID manager are dedicated to single processing threads. The OsidManager defines methods in common throughout all OSID managers which implement this interface.

initialize(runtime)¶

Initializes this manager.

A manager is initialized once at the time of creation.

Parameters:	runtime (`osid.OsidRuntimeManager`) – the runtime environment
Raise:	`ConfigurationError` – an error with implementation configuration
Raise:	`IllegalState` – this manager has already been initialized by the `OsidRuntime`
Raise:	`NullArgument` – `runtime` is `null`
Raise:	`OperationFailed` – unable to complete request

compliance: mandatory – This method must be implemented. implementation notes: In addition to loading its runtime configuration an implementation may create shared resources such as connection pools to be shared among all sessions of this service and released when this manager is closed. Providers must thread-protect any data stored in the manager. To maximize interoperability, providers should not honor a second call to initialize() and must set an IllegalState error.

rollback_service(rollback_time)¶

Rolls back this service to a point in time.

Parameters:	rollback_time (`timestamp`) – the requested time
Returns:	the journal entry corresponding to the actual state of this service
Return type:	`osid.journaling.JournalEntry`
Raise:	`OperationFailed` – unable to complete request
Raise:	`PermissionDenied` – authorization failure occurred
Raise:	`Unimplemented` – `supports_journal_rollback()` is `false`

compliance: mandatory – This method must be implemented.

change_branch(branch_id)¶

Changes the service branch.

Parameters:	branch_id (`osid.id.Id`) – the new service branch
Raise:	`NotFound` – `branch_id` not found
Raise:	`NullArgument` – `branch_id` is `null`
Raise:	`OperationFailed` – unable to complete request
Raise:	`PermissionDenied` – authorization failure occurred
Raise:	`Unimplemented` – `supports_journal_branching()` is `false`

compliance: mandatory – This method must be implemented.

Osid Proxy Manager¶

class dlkit.services.osid.OsidProxyManager¶

Bases: dlkit.services.osid.OsidProfile

The OsidProxyManager is the top level interface for all OSID proxy managers.

A proxy manager accepts parameters to pass through end-user authentication credentials and other necessary request parameters in a server environment. Native applications should use an OsidManager to maintain a higher degree of interoperability by avoiding this coupling.

An OSID proxy manager is instantiated through the OsidRuntimeManager and represents an instance of a service. An OSID manager is responsible for defining clusters of interoperability within a service and creating sessions that generally correspond to these clusters, An application need only create a single OsidProxyManager per service and implementors must ensure the OsidProxyManager is thread-safe ``. The ``OsidSessions spawned from an OSID manager are dedicated to single processing threads. The OsidProxyManager defines methods in common throughout all OSID managers which implement this interface.

initialize(runtime)¶

Initializes this manager.

A manager is initialized once at the time of creation.

Parameters:	runtime (`osid.OsidRuntimeManager`) – the runtime environment
Raise:	`ConfigurationError` – an error with implementation configuration
Raise:	`IllegalState` – this manager has already been initialized by the `OsidRuntime`
Raise:	`NullArgument` – `runtime` is `null`
Raise:	`OperationFailed` – unable to complete request

compliance: mandatory – This method must be implemented. implementation notes: In addition to loading its runtime configuration an implementation may create shared resources such as connection pools to be shared among all sessions of this service and released when this manager is closed. Providers must thread-protect any data stored in the manager. To maximize interoperability, providers should not honor a second call to initialize() and must set an IllegalState error.

rollback_service(rollback_time, proxy)¶

Rolls back this service to a point in time.

Parameters:	rollback_time (`timestamp`) – the requested time proxy (`osid.proxy.Proxy`) – a proxy
Returns:	the journal entry corresponding to the actual state of this service
Return type:	`osid.journaling.JournalEntry`
Raise:	`NullArgument` – `proxy` is `null`
Raise:	`OperationFailed` – unable to complete request
Raise:	`PermissionDenied` – authorization failure occurred
Raise:	`Unimplemented` – `supports_journal_rollback()` is `false`

compliance: mandatory – This method must be implemented.

change_branch(branch_id, proxy)¶

Changes the service branch.

Parameters:	branch_id (`osid.id.Id`) – the new service branch proxy (`osid.proxy.Proxy`) – a proxy
Raise:	`NotFound` – `branch_id` not found
Raise:	`NullArgument` – `branch_id` or `proxy` is `null`
Raise:	`OperationFailed` – unable to complete request
Raise:	`PermissionDenied` – authorization failure occurred
Raise:	`Unimplemented` – `supports_journal_branching()` is `false`

compliance: mandatory – This method must be implemented.

Osid Runtime Profile¶

class dlkit.services.osid.OsidRuntimeProfile¶

Bases: dlkit.services.osid.OsidProfile

The OsidRuntimeProfile defines the service aspects of the OSID runtime service.

supports_configuration()¶

Tests if a configuration service is provided within this runtime environment.

Returns:	`true` if a configuration service is available, `false` otherwise
Return type:	`boolean`

compliance: mandatory – This method must be implemented.

Osid Runtime Manager¶

class dlkit.services.osid.OsidRuntimeManager¶

Bases: dlkit.services.osid.OsidManager, dlkit.services.osid.OsidRuntimeProfile

The OsidRuntimeManager represents and OSID platform and contains the information required for running OSID implementations such as search paths and configurations.

get_manager(osid, impl_class_name, version)¶

Finds, loads and instantiates providers of OSID managers.

Providers must conform to an OsidManager interface. The interfaces are defined in the OSID enumeration. For all OSID requests, an instance of OsidManager that implements the OsidManager interface is returned. In bindings where permitted, this can be safely cast into the requested manager.

Parameters:	osid (`osid.OSID`) – represents the OSID impl_class_name (`string`) – the name of the implementation version (`osid.installation.Version`) – the minimum required OSID specification version
Returns:	the manager of the service
Return type:	`osid.OsidManager`
Raise:	`ConfigurationError` – an error in configuring the implementation
Raise:	`NotFound` – the implementation class was not found
Raise:	`NullArgument` – `impl_class_name` or `version` is `null`
Raise:	`OperationFailed` – unable to complete request
Raise:	`Unsupported` – `impl_class_name` does not support the requested OSID

compliance: mandatory – This method must be implemented. implementation notes: After finding and instantiating the requested OsidManager, providers must invoke OsidManager.initialize(OsidRuntimeManager) where the environment is an instance of the current environment that includes the configuration for the service being initialized. The OsidRuntimeManager passed may include information useful for the configuration such as the identity of the service being instantiated.

get_proxy_manager(osid, implementation, version)¶

Finds, loads and instantiates providers of OSID managers.

Providers must conform to an OsidManager interface. The interfaces are defined in the OSID enumeration. For all OSID requests, an instance of OsidManager that implements the OsidManager interface is returned. In bindings where permitted, this can be safely cast into the requested manager.

Parameters:	osid (`osid.OSID`) – represents the OSID implementation (`string`) – the name of the implementation version (`osid.installation.Version`) – the minimum required OSID specification version
Returns:	the manager of the service
Return type:	`osid.OsidProxyManager`
Raise:	`ConfigurationError` – an error in configuring the implementation
Raise:	`NotFound` – the implementation class was not found
Raise:	`NullArgument` – `implementation` or `version` is `null`
Raise:	`OperationFailed` – unable to complete request
Raise:	`Unsupported` – `implementation` does not support the requested OSID

compliance: mandatory – This method must be implemented. implementation notes: After finding and instantiating the requested OsidManager, providers must invoke OsidManager.initialize(OsidRuntimeManager) where the environment is an instance of the current environment that includes the configuration for the service being initialized. The OsidRuntimeManager passed may include information useful for the configuration such as the identity of the service being instantiated.

configuration¶

Gets the current configuration in the runtime environment.

Returns:	a configuration
Return type:	`osid.configuration.ValueLookupSession`
Raise:	`OperationFailed` – unable to complete request
Raise:	`PermissionDenied` – an authorization failure occured
Raise:	`Unimplemented` – a configuration service is not supported

compliance: optional – This method must be implemented if ``supports_configuration()`` is ``true``.