Id Implementations
- Tom Coppeto
Summary
This section describes the Primordium implementations of org.osid.id.Id.
Id Implementations?
Id communicates the three identification components. Implementations of it don't do much and maybe that's why there are so many of them. They are a handy tool to encapsulate the parsing and formatting of different serialized formats.
Serialization
User-facing applications have no need to display an Id. It is opaque to most OSID Consumers. The format of an Id is important in the following circumstances:
- persisting an Id
- transmitting an Id
- logging an Id
- configuring an Id
- documenting well-known Ids
It's desirable to have something concise and readable than Java's Serializable methods provide. We use toString() for the output and valueOf(String) for the input. There are many possible formats to choose from.
Schemes
It's tempting to use another identification scheme such as a URI. The hitch is that it depends on whether the identification scheme is the output format for any OSID Id or any identifier in the identification scheme is to be cast into an OSID Id. OSID Ids have three components while Identification schemes have varying different delimiters and reserved characters. It's important to know which way you are going.
Standard Ids
Standard Id implementations take any OSID Id and serialize it to a scheme. Example:
URLId urlId = new URLId("mit.edu", "providers", "authentication/Kerberos");
urlId.toString ==> "http://mit.edu/identifiers/providers/authentication/Kerberos"
BasicId basicId = new BasicId("mit.edu", "providers", "authentication/Kerberos");
basicId.toString ==> providers:authentication/Kerberos@mit.edu
basicId.equals(urlId) ==> true
URLId.valueOf("http://apple.com/itunes") ==> ERROR
The standard Ids only care about the authority, namespace, and identifier. Implementations of each scheme will format it to make it look like that scheme. However, any identifier in that scheme cannot be understood by the implementation. The format is designed to preserve the distinction among the three Id components.
Global Ids
Global Id implementations take any identifier in a scheme and deserialize it to an OSID Id.
GlobalURLId urlId = URLId.valueOf("http://nytimes.com/articles/108282");
urlId.toString ==> "http://nytimes.com/articles/108282"
BasicId basicId = new BasicId("nytimes.com", "articles", "108282");
basicId.toString ==> articles:108282@nytimes.com
basicId.equals(urlId) ==> false
Id Namespaces
In the above example, the equality fails on the Id namespace. In the URLId implementation, the namespace is set to something relevant in the OSID world. In this case, Ids for service providers. The output is rigged so that it can be parsed back into its identification components. In the GloablURLId implementation, the namespace is set to "url" and does not interpret the url path. The two implementations create distinct and unequal OSID Ids.
Which Way?
That depends on where you are coming from. If you have a bunch of Ids and each assigned with an authority, namespace, and identifier, use the standard Ids. You can serialize it into a variety of formats and not lose any information.
If you want to simply wrap an OSID Id around an external identifier you did not assign in an OSID context, then use the Global Ids.
But you can't do this:
URL1Id -> url string -> GlobalURLId -> URL2Id
and expect URL1Id and URL2Id to be equal. However, you can do this:
URL1Id -> url string -> GlobalURLId -> url string -> URL2Id
and URL1Id and URL2Id will be equal.
Patterns
These Id implementations implement equals() comparing the Id authority, namespace, and identifier.
They also support one or more valueOf() static factories where the string-based static factory supports the format output in toString().
See Also