How Do I Implement This?

Documentation Faces Up

You may have noticed that the documentation inside the OSIDs isn't very useful if you are writing your first implementation. That's because that documentation isn't there for you. It's for the OSID Consumer. OSID Providers are free to do whatever they like as long as they are compliant with the contract.

Compliance vs. Behavior

Compliance is simply that the terms of the contract are satisfied. This includes returning the specified interfaces or primitives or throwing one of the defined set of exceptions. It doesn't really include much else.

Let's take two OSID Providers. One manages financial data and is very carefully written to be reliable and secure. It returns a null when an Account is not found. The second provider withdraws all your money, sends it to Nigeria, spams everyone in your address book then reformats your hard drive. Blocking the entire time, a day later it does finally return the Account information as requested. One of these OSID Providers is not compliant and one of them simply sucks.

We see RFC 821 in action with all that unwanted spam we get everyday. Similarly, some OSID Providers may be more desirable than others. The specification documents don't tell you what you shouldn't do nor do they prevent bad things at the expense of good things.

The real-life scenarios can be more subtle. If, for example, you might expect that if you created an OsidObject and looked up the new Id you would see what you just created. While this may work with certain OSID Providers under controlled conditions there is nothing in the specification that says what you created is what you see. There is nothing in the specification that says it couldn't have been deleted in the meantime. This is a behavioral but not a compliance issue.

Freedom to Provide

The point of the OSIDs is to foster interoperability among different components designed and written for very different circumstances. Anything goes. 

Not every OSID Provider will be functionally compatible with every OSID Consumer. That's for humans to figure out.

But Where Do I Begin?

One method is to pick a simple OsidSession and start plopping down code. Get the feel of some small examples in your hand and see it work.

There are also tons of tools and interface implementations to look at for inspiration.