Terminology
- Tom Coppeto
Summary
Interfaces, contracts, methods, operations, entities, objects, and tables, oh my! The OSID Specification defines its own language solely in reference to itself. The vocabulary is defined and built upon without importing words from outside the OSIDs.
However, developers will look at it from the OSID Language Binding perspective. Many will import concepts from what they have worked with in databases, web services, or MVC-based platforms. The result can be a mash of terms that gets in the way of understanding the OSIDs and how they can be applied.
Perspectives
The OSID Perspective
The OSID Specification schema (S-OSID) defines:
- osid: a bunch of interfaces an enumerations
- enumeration: a list of values
- interface: a bunch of method definitions
- method: something that is invoked with parameters, returns a value or an error
- parameter: defines what may be supplied to a method as an argument, can be an interface, enumeration, or a language primitive
- return: defines what may be returned from a method, if anything, can be an interface, enumeration, or a language primitive
- language primitive: boolean, byte, cardinal. decimal integer, object. string, timestamp
- error: an error from a method such as OPERATION_FAILED or ILLEGAL_STATE
- compliance: a compliance statement for a method - mandatory or optional
The Java Perspective
- package: a bunch of interfaces, classes, enums, annotations, and other sub-packages
- enums: constants and methods
- interface: a bunch of method definitions
- class: a pile of attributes that include methods and may implement one or more interfaces
- object: an instance of a single class
- method: something that is invoked with parameters, returns a value or throws an exception
- parameter: defines the type supplied to a method as an argument, can be a class, interface, enum, or a primitive
- return: defines the type of return value, can be a class, interface, enum, primitive, or void
- primitive: boolean, byte, char, double, float, int, long, short
- exception: an event that occurs during the execution of a program that disrupts the normal flow of instructions such as SecurityException or NullPointerException
The OSID Java Binding Perspective
The OSID Specification is transformed into the OSID Java Binding. The resulting merge creates the following OSID terminology in Java:
- osid: a Java packages and its sub-packages
- package: a bunch of interfaces and enums
- enums: constants and methods
- interface: a bunch of method definitions
- method: something that is invoked with parameters, returns a value or throws an exception
- parameter: defines the type supplied to a method as an argument, can be an interface, enum, or a primitive
- return: defines the type of return value, can be an interface, enum, primitive, or void
- primitive: boolean, byte, or long
- exception: an error from a method such as such as OperationFailedException or IllegalStateException
Concepts like classes and objects disappear. Others like parameter and primitive have a narrower connotation than what a Java developer would be accustomed. An OSID Language Binding can hide certain aspects of the OSID Specification that are conceptually relevant because it is an interpretation. The Java is pretty close, but can cause some head scratching about why something was done one way or the other. The specifications on osid.org display the OSIDs, not the OSID Java Binding.
Terminology Issues
These are a list of terms that often get tossed around. Mixing terminology across frameworks will always result in complacent agreements over different things and heated debates over the same thing. When a term is in direct conflict with the OSID Specification or its few basic concepts, it's a good idea to lose it and adapt. Other terms are kinda similar, but not equal. Level setting can be difficult when trying to learn something by comparing it to something else you already know.
Others terms are more conceptual in nature and we tend to use them informally.
terminology compatible with OSIDs with caveats
terminology incompatible with the OSIDs
API
OSIDs are consumed by OSID Consumers in software. OSIDs are Application Programming Interfaces.
However, OSIDs are designed around integration points and abstracted to promote interoperability in software by moving configuration and control from consumers to providers. Many APIs are to utility libraries that allow their applications to more easily command what the library will do, such as storing data in a HashSet, building a DOM tree, when to send data over the wire. So, not all APIs make good service contracts (in fact few are designed with this intent).
Attributes & Data Fields
Service entities, such as OsidObjects, are expressed using interfaces. What is presented to an OSID Consumer is the means for accessing information at that point in time. OSID Providers can provide real time information through its methods.
An OSID Provider may likely employ data objects to satisfy the contract of an OsidObject. An OSID Consumer sees this through the window of the interface. The OSID Consumer may do whatever it likes with this information, including referring to them as simple data elements. However it can be an impediment when trying to understand the nature and applications of these interfaces whose implementation may require an underlying OSID Provider rather than a pull from a database table, for example.
Boundary (Service Boundary)
Boundary can be a cool word but is a bit slippery. In the OSIDs, it may also refer the line between an OSID Consumer and an OSID Provider, i.e. "The details of the Asset are opaque through the OSID boundary."
Many listeners will assume it means the scope of a service, i.e. "There's a service boundary between authentication and authorization." However, jumping laterally between two OSIDs also implies a movement between OSID Providers. This interpretation would not be wrong but it may fail to clarify exactly what is meant.
Contract (Service Contract)
The term contract is often used in service designs to distinguish an interface from a message structure or DTO. The message structure and DTO are considered data while the contract defines the operations on that data. OSIDs define the agreement between service consumers and service providers. In the OSID world, most everything in the specification can be considered a contract, i.e. "The AgentList is a contract."
DTO (DAO, Bean, Domain Object)
A Data Transfer Object is used to transfer bags of data values. However, OSIDs are interfaces into OSID Providers. OSID Providers may be dynamic and DTOs are static.
Most DTOs are bi-directional. The same object is often used for retrieval and update with setters and getters. OSIDs define different interfaces for these operations making most interfaces, except for OsidPrimitives, uni-directional.
However, OsidObjects are not domain or business objects. Their interfaces define methods to access information and relations. Actions are defined in OsidSessions. This is much more like a DAO/DTO model than a pure object oriented model as it allows for better defined integration points. The absence of setters in the OsidObject interfaces, the inability to persist an OsidObject, the extensible OsidRecord mechanism, and the non-CRUD based methods in OsidSessions make these analogies ripe for confusion.
Endpoint (Service Endpoint)
In the web service world, an endpoint is essentially a URI that identifies a service provider and to which data will be serialized. In the OSID world, there are no URIs and serialization is handled by an OSID Consumer or OSID Provider.
However, the concept of service endpoints can be brought into the OSIDs. The first identifier is the implementation name of an OSID Provider given to OsidRuntimeManager to get an OsidManager. This can be considered the first service endpoint. Or perhaps an OsidProxyManager was requested instead. This can be considered an alternate service endpoint. In OSIDs, to get a service endpoint means to get an interface.
From there, OsidSessions are requested. Each OsidSession can also be considered endpoints. Then so can OsidLists and OsidObjects.
Because OSIDs abstract away issues of serialization and protocol, we are just left with interface definitions that are utilized directly in software. The SOA concepts of endpoint and contract still apply but without the web services part. SOA - WS = OSIDs
Entity (Service Entity)
In the modeling world, entity is simply a fancy way of saying thing. They are the boxes in an entity model and often correspond to OsidObjects in the OSIDs.
In service design, using phrase service entity can help clarify the difference between a database entity (table) or an application object.
Message Structure
In the web service world, message structures are data entities transmitted to and from service endpoints. In the OSID world, we see live interfaces into OSID Providers that are not necessarily data snapshots and may be orchestrated service operations in their own right. There is no concept of transmission of data through the OSID boundary, even if that's what actually happened below in an OSID Provider.
Operations (Service Operations)
In the SOAP world, service operations are the methods that operate on message structures. They are often CRUDish but don't have to be. In the OSID world, these would certainly include the methods defined in OsidSessions. They may also include the methods in OsidManagers that provide access to the OsidSession endpoints and similarly with OsidLists and the OsidObjects. Using operation to distinguish between a data access method and methods which operate on OsidObjects doesn't hold up. At the very least, all methods in the OSIDs that define an OPERATION_FAILED error can be considered service operations.
However, if an OSID Provider implements a live database call behind the display name and description and falls back to using stale data in case of an error, doesn't this also count as a service operation? The OSIDs go out of their way to blur the line between service operation and data so terminology that tries to distinguish them will be problematic.
Relation (Entity Relations, Relationships)
In the modeling world, a relation is described by the cardinality between two entities. Entity relations are expressed throughout the OSIDs.
OSIDs have a special kind of OsidObject called OsidRelationship. An OsidRelationship is an entity relation between two OsidObjects that exists for a period of time. Not every entity relation between two entities is an OsidRelationship.
Service (OSID, Package)
The term "service" doesn't have any formal definition in the OSID Specification. It's tossed around because this is a Service Design Methodology and OSIDs are specifications for how OSID Providers provide services to OSID Consumers.
However, it doesn't mean anything in particular. 't OSID may define other OSIDs within it and each OSID defines OsidManagers and OsidSessions, each which provide a service. Then, each OsidObject as an interface into an OSID Provider is also a service. Once again, the OSIDs go out of their way to confuse conventional classifications.
The term OSID can also be over-interpreted. OSID is an acronym for Open Service Interface Definition. It is the interface definition, or specification itself, not any implementation of it. Thus the phrase "OSID Provider."
However, OSID is often used to describe an entire package, i.e. "The Authorization OSID" or "The Billing OSID." OSID isn't used for any particular interface but rather a set of interfaces. But some OSIDs contain other OSIDs, and it tends to mean just the top level, i.e. "The Course OSID" vs. "The Course Registration OSID."
OSIDs do not formally define the term package. Packages seem to be implied by the naming of the interfaces (osid.mapping.Location) and the OSID Java Binding takes that literally into the Java world. However, not all Java packages are OSIDs as can be seen with the OsidRecord interfaces, i.e. osid.personnel.records.PersonRecord is part of the Personnel OSID.
The ERD below captures the difficulty in moving among all of these terms as there are no direct 1:1 mappings anywhere. Using the more specific OSID terminology is helpful when precision is needed.
Standard (Specification)
OSIDs have historically been referred to as specifications. The difference between a standard and a specification is confusing at best. Typically, one incorporates standards into specifications while others refer to specifications as a type of standard. Some believe a standard has accreditation associated with it, as in meets the standard while others perform quality assurance based on a specification. Some believe that a standard is based on a consensus process but a specification is not. However, most use these terms interchangeably today and more often they get strung together. Who knows.