ServiceProvider - OSLC Primer - Open Services for Lifecycle Collaboration

Almost all existing lifecycle tools - whether they manage defects, test cases, requirements or whatever - have organizing concepts that partition the overall space of artifacts in the tool into smaller containers. Examples of common partitioning concepts offered by tools include “projects”, “modules”, “user databases” and so on. Each artifact created in the tool is created within one of these container-like entities, and users can list the existing artifacts within one. These container-like concepts are very important to the usage of tools – which container you put artifacts into and find artifacts in is essential to the way you work and may reflect which project you are working on, or which product the artifacts pertain to. There is no agreement across tools of the lifecycle, even within a particular domain, on what these partitioning concepts should be called, but there is almost universal agreement that they exist and are fundamentally important. These concepts are also fundamentally important in the integration scenarios supported by OSLC. OSLC defines the concept of ServiceProvider to allow products to expose these containers or partitions for integration scenarios. ServiceProviders answer two basic questions, which are:

To which URLs should I POST to create new resources?
Where can I GET a list of existing resources?

Tip! A common misconception of people who have read the OSLC specification is that a ServiceProvider is intended to represent a tool or tool instance. A ServiceProvider is intended to represent a “container” of resources that is hosted by a tool, not the tool itself. A single instance of a tool will typically host multiple ServiceProviders, for example one for each “project” or “product”.

Tip! OSLC references another standard – OAuth – for security. OAuth also has a concept called ServiceProvider, although OAuth appears to moving away from this term in favor of “Server”. The OAuth concept of ServiceProvider corresponds to the concept of a server, not a “resource container”. Multiple OSLC ServiceProviders would be expected to be hosted by the same OAuth ServiceProvider. OSLC has a different concept – ServiceProviderCatalog (explained later) - that is more closely analogous to OAuth’s ServiceProvider concept. Be careful not to confuse the OAuth concept of ServiceProvider and the OSLC concept of ServiceProvider.

ServiceProvider is the central organizing concept of OSLC, enabling tools to expose resources and allowing consumers to navigate to all of the resources, and create new ones. Here are some characteristics of ServiceProviders:

All OSLC resources live in some ServiceProvider. There is an optional property of each OSLC resource (oslc:serviceProvider) that says which ServiceProvider it is “in”.
Clients can retrieve the list of existing resources in a ServiceProvider
The only way that is defined in OSLC to create any new OSLC resources is to create them in a ServiceProvider (either directly through an HTTP POST, or via a dialog).
A ServiceProvider is itself an OSLC resource with an HTTP URL.

Tools often have “softer” or more dynamic partitions of artifacts based on data-values like “category” or “release” or “component” that can be further used to partition the space of artifacts in a container. When adopting OSLC for a new or existing tool, deciding which container-like concept in the tool to map to an OSLC ServiceProvider is a bit of an art – you need to think about what partitions should be viewed as fundamental from the point of view of an external client, and which partitions are more dynamic and ephemeral, changing as property values of resources change. The fundamental ones are the ones that should be represented as OSLC ServiceProviders.

What does a ServiceProvider resource actually look like?

If you do an HTTP GET on a ServiceProvider resource, you will not retrieve a list of the resources it contains; you will retrieve general properties of the ServiceProvider – its “metadata” if you like that term – including the URLs you can use to find or create resources. If you do a POST to the URL of a ServiceProvider, you will likely just get an HTTP Error. Two fundamental properties of a ServiceProvider are:

oslc:creation: the URL of a resource to which you can POST representations to create new resources.
oslc:queryBase: the URL of a resource that you can GET to obtain a list of existing resources in the ServiceProvider. This URL is called the “queryBase URL” and the resource identified by this URL is called the queryBase.

In the simplest case, the creation URI and the queryBase URI will in fact be the same URL.

ServiceProviders have a third important property – dialog – that is the foundation of the second major OSLC integration technique based on invocation of HTML web user interface dialogs of one tool by another. Dialogs are discussed in a separate section of this primer.

You might think from the preceding description that the simplest ServiceProvider example might look something like the following, in Turtle notation.


@prefix oslc: <http://open-service.net/ns/core#>.
<http://acme.com/toolA/container1>
    a oslc:ServiceProvider;
    oslc:creation <http://acme.com/toolA/container1/contents>;
    oslc:queryBase <http://acme.com/toolA/container1/contents>.

The example above is true to the spirit of OSLC, and captures the essential meaning of ServiceProvider accurately, which is why it is listed here, but the real OSLC syntax is more complex, and this example is not legal.

OSLC Core supports more complex options for ServiceProviders, including the ability to have more than one creation URI and more than one queryBase URI, the ability to attach properties to each creation URI and each queryBase URI and to give hints about their intended usage and the ability to group creation URIs and queryBase URIs by the OSLC domain they are intended to support.

In order to satisfy these requirements, OSLC introduces three additional concepts – Service, CreationFactory and QueryCapability. These are not primary concepts in OSLC and their instances are never independent HTTP resources with their own URLs. These three concepts are more like “structured data types” whose instances are used as property values in the state of a ServiceProvider - you should think of Service, CreationFactory and QueryCapability as technical details of the way the state of a ServiceProvider is organized rather than central OSLC concepts. QueryCapability allows properties to be associated with a queryBase URI, CreationFactory allows properties to be associated with a creation URI and Service allows (actually, requires) creation URIs and queryBase URIs to be grouped by OSLC domain.

Because of these additional concepts, our simplest ServiceProvider actually looks like this:

Example 1:


@prefix oslc: <http://open-service.net/ns/core#>.
<http://acme.com/toolA/container1> a oslc:ServiceProvider;
    oslc:service
        [a oslc:Service;
            oslc:domain <http://open-services.net/ns/cm#>;
            oslc:creationFactory
                [a oslc:CreationFactory;
                    oslc:creation <http://acme.com/toolA/container1/contents>];
            oslc:queryCapability
                [a oslc:QueryCapability;
                    oslc:queryBase <http://acme.com/toolA/container1/contents>]
        ].

Guidance – Define simple ServiceProviders

We recommend that implementers of OSLC adopt the following simplified pattern of usage unless they have compelling reasons to do otherwise:

Focus first on identifying the basic containers implemented by the tool and expose each of these containers as a single ServiceProvider. Don’t attempt to create individual ServiceProviders for each type of resource. For example, if the data partitioning concept in your tool is project, create a single ServiceProvider for each project, even if the project can contain Defects, Risks, Issues, Comments, and Approvals.
Identify a single URL for each ServiceProvider that will be used both as the URL to which new resources can be POSTed (the creation URI) and the URL of the RDF container resource that lists the existing resources of the container (the queryBase URI).
Within each ServiceProvider’s representation, create a single Service with a single CreationFactory and a single QueryCapability each referencing the single URL established in step 2. Example 1 above shows exactly this pattern.

What does a queryBase resource look like?

The queryBase resource identified by a queryBase URI of a ServiceProvider is an RDF Container resource that lists resources in the ServiceProvider.

If a ServiceProvider has multiple queryBases, it is undefined which queryBases a resource will show up in after being POSTed to a creation URI.

The representation of the queryBase is a standard RDF Container representation using the rdfs:member predicate. (http://www.w3.org/TR/rdf-schema/#ch_member ) For example, if I have an OSLC container with the URL http://acme.com/oslc/container/1) it might have the following representation:


@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
<http://acme.com/oslc/container/1>
    <rdfs:member> <http://acme.com/oslc/resource/000000000>;
    # … 999999998 more triples here …
    <rdfs:member> <http://acme.com/oslc/resource/999999999>.

OSLC does not recognize or recommend the use of other forms of RDF Container such as Bag and Seq because they are not friendly to SPARQL query. This follows standard linked data guidance for RDF usage (e.g. http://linkeddatabook.com/editions/1.0/#htoc16).

Learn more about ServiceProvider Resources in the OSLC Core specification

Ask a question on the forums or email the site administrator. If you have questions specifically about Eclipse Lyo, ask the lyo-dev mailing list.

What does a ServiceProvider resource actually look like?

Guidance – Define simple ServiceProviders

What does a queryBase resource look like?

Any problems?