This wiki is locked. Future workgroup activity and specification development must take place at our new wiki. For more information, see this blog post about the new governance model and this post about changes to the website.
TWiki> Main Web>OslcPrimer (07 Jan 2011, DaveJohnson)
OSLC_logo.png

Open Services for Lifecycle Collaboration
Primer (Incomplete and very rough draft)

This Version

Latest Version Authors
  • Jim Conallen
Contributors

Table of Contents

License

88x31.png
This work is licensed under a Creative Commons Attribution License.

What should an OSLC Primer be?

REMINDER: this is a very ROUGH DRAFT

We are still planning what this document should be. Below is the group consensus on this topic from a recent OSLC Core workgroup meeting (OslcCoreMeeting20101215).

  • A Primer that explains by example
    • We need an OSLC Primer that explains in detail how OSLC works by showing examples, starting with simple examples and progressively revealing more of OSLC as we build upon those examples.
  • Focus on consumer / client-side
    • Most people implementing consumers, not providers. We should focus on the need of client-side consumer developers first.
  • Use realistic scenario(s)
    • Need realistic end-to-end scenario to give context to our examples. Pick something development related, e.g. not blogging. Pick a scenario complex enough to allow us to progressively reveal more about OSLC as we add more features.
  • Scenario ideas:
    • Impact analysis
    • Linking defect to test case
  • Don't go beyond simple web UI
    • Any UI involved should be bare bones and web-based, as we have in the OSLC RI now. Developing an Eclipse client or an elaborate web UI would be a distraction.
  • Use, but do not depend on RI
    • The Primer should not depend on the RI, but it would be nice if you could "follow along" by experimenting with the RI. We will have a OSLC provider RI, one that supports OSLC-CM and other specs. We can use it to illustrate the Primer, but we should not require people to install the RI. The Primer should stand on its own.
  • Cover authentication, if possible
    • It would be nice to cover authentication, of course, but we don't want to get too product specific.
    • Perhaps we can refer folks to separate HTTP Basic and OAuth primers?

Introduction

The main goal of the OSLC is to facilitate collaboration among life cycle application tools by defining resources and interfaces. The OSLC Core 2.0 specification has conceptually adopted an RDF resource model for resource representation. Interfaces are implemented with HTTP REST.

This primer will follow the following scenario:

  • Get and investigate the catalog and service provider documents.
  • Using a creation factory referenced in a service provider document, create a new instance of a resource. We verify the creation of the resource by getting it back from the server and examine its server defined properties. We complete the resource life cycle interface by changing it and eventually deleting it.
  • Using a query capability URL from the service provider document, we execute various queries for resources in the server.
  • Finally, invoke the delegated UI selector and creator.

The narrative of this primer uses the Simple OSLC Reference Implementation for Architecture Management (SORI-AM) as a service provider example, and the Firefox web browser with the Poster Addon to invoke and examine the service provider.

All the example resources are formatted in RDF/XML since this is the only machine readable resource format that the Core 2.0 specification states SHOULD be supported by all implementing providers. HTML responses are recommended for human readable representations of resources, and most service providers are likely to provide alternate machine readable representations such as JSON and Turtle.

One aspect that is not addressed directly in this primer is authentication and security. Implementations may support BASIC, Form or OAuth authentication mechanisms. It is assumed that before clients can interact with the service provider’s services have authenticated themselves with the server. The default behavior of the SORI-AM reference implementation is to not require authentication.

Catalog and Service Provider Documents

OSLC clients obtain the concrete URLs of a service provide through the discovery documents. There are two types of discovery documents; catalog and service. The catalog document contains references to service provider documents. Service provider documents contain concrete URLs of services in a specific context. The catalog document contains these contexts and may contain other catalog documents (thereby nesting contexts).

All interaction with an OSLC provider must begin with a reference to one of its catalog URLs or service provider URLs. We begin our scenario with a reference to a catalog URL: http://acme.com:8080/oslc-am/catalog. The client does an HTTP GET passing in an Accept header value of application/rdf+xml, and the special OSLC-Core-Version header with a value of 2.0. This header is used by service providers that also support older version 1.0 specifications. The SORI-AM provider does not require them (nor does it require the accept header), however a well behaved client should pass them in.

Request: 

GET http://acme.com:8080/oslc-am/catalog   OSLC-Core-Version: 2.0
Accept: application/rdf+xml

Response Headers: 

200 OK OSLC-Core-Version: 2.0
Content-Type: application/rdf+xml
Content-Length: 2159

Response Body : 

<?xml version="1.0" encoding="UTF-8"?>   <rdf:RDF 
   xml:dcterms="http://purl.org/dc/terms/"       xml:oslc="http://open-services.net/ns/core#"       xml:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"       xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
       <oslc:ServiceProviderCatalog rdf:about="http://acme.com:8080/oslc-am/services">
    <dcterms:title xmlns:dcterms="http://purl.org/dc/terms/">SORI Service Provider Catalog</dcterms:title>
    <dcterms:description xmlns:dcterms="http://purl.org/dc/terms/">         Simple OSLC Reference Implementation (SORI) for Architecture Management Catalog Document</dcterms:description>
       <dcterms:publisher xmlns:dcterms="http://purl.org/dc/terms/">
      <oslc:Publisher>
        <dcterms:title>Open Services for Lifecycle Collaboration in Architecture Management</dcterms:title>
        <dcterms:identifier>open-services.net/ri/am</dcterms:identifier>
        <oslc:icon rdf:resource="http://acme.com:8080/oslc-am/sori-am.png"/>
      </oslc:Publisher>
    </dcterms:publisher>
       <oslc:prefixDefinition>
      <oslc:PrefixDefinition>
        <oslc:prefix>dcterms</oslc:prefix>
        <oslc:prefixBase>http://purl.org/dc/terms/</oslc:prefixBase>
      </oslc:PrefixDefinition>
    </oslc:prefixDefinition>
    <oslc:prefixDefinition>
      <oslc:PrefixDefinition>
        <oslc:prefix>rdf</oslc:prefix>
        <oslc:prefixBase>http://www.w3.org/1999/02/22-rdf-syntax-ns#</oslc:prefixBase>
      </oslc:PrefixDefinition>
    </oslc:prefixDefinition>
    <oslc:prefixDefinition>
      <oslc:PrefixDefinition>
        <oslc:prefix>oslc</oslc:prefix>
        <oslc:prefixBase>http://open-services.net/ns/core#</oslc:prefixBase>
      </oslc:PrefixDefinition>
    </oslc:prefixDefinition>
    <oslc:prefixDefinition>
      <oslc:PrefixDefinition>
        <oslc:prefix>oslc_am</oslc:prefix>
        <oslc:prefixBase>http://open-services.net/ns/am#</oslc:prefixBase>
      </oslc:PrefixDefinition>
    </oslc:prefixDefinition>
       <oslc:ServiceProvider rdf:resource="http://acme.com:8080/oslc-am/services"/>
     </oslc:ServiceProviderCatalog>
</rdf:RDF>

The catalog document provide three basic pieces of information; general information about itself as a provider, a set of pre-defined namespace prefixes (use by the query interface), and a list of service provider document URLs. Some service implementations may not provide a catalog document and all interaction is expected to begin with the service provider URL.

Service Document

In the example above, only one service provider URL is included in the response. With this URL we perform another GET to discover the service providers REST endpoints.

Request: 

GET http://acme.com:8080/oslc-am/services   OSLC-Core-Version: 2.0
Accept: application/rdf+xml

Response Headers: 

200 OK   OSLC-Core-Version: 2.0
Content-Type: application/rdf+xml
Content-Length: 6881

Response Body : 

<?xml version="1.0" encoding="UTF-8"?>   <rdf:RDF      xml:dcterms="http://purl.org/dc/terms/"      xml:oslc="http://open-services.net/ns/core#"      xml:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"      xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">   
  <oslc:ServiceProvider rdf:about="http://acme.com:8080/oslc-am/services" >
    <dcterms:title>SORI Service Provider Catalog</dcterms:title>
    <dcterms:description>         Simple OSLC Reference Implementation (SORI) for Architecture Management Service Document       </dcterms:description>
    <dcterms:publisher>
      <oslc:Publisher>
        <dcterms:title>Open Services for Lifecycle Collaboration in Architecture Management</dcterms:title>
        <dcterms:identifier>open-services.net/ri/am</dcterms:identifier>
        <oslc:icon rdf:resource="http://acme.com:8080/oslc-am/sori-am.png"/>
      </oslc:Publisher>
    </dcterms:publisher>
    <oslc:prefixDefinition>
      <oslc:PrefixDefinition>
        <oslc:prefix>dcterms</oslc:prefix>
        <oslc:prefixBase>http://purl.org/dc/terms/</oslc:prefixBase>
      </oslc:PrefixDefinition>
    </oslc:prefixDefinition>
    <oslc:prefixDefinition>
      <oslc:PrefixDefinition>
        <oslc:prefix>rdf</oslc:prefix>
        <oslc:prefixBase>http://www.w3.org/1999/02/22-rdf-syntax-ns#</oslc:prefixBase>
      </oslc:PrefixDefinition>
    </oslc:prefixDefinition>
    <oslc:prefixDefinition>
      <oslc:PrefixDefinition>
        <oslc:prefix>oslc</oslc:prefix>
        <oslc:prefixBase>http://open-services.net/ns/core#</oslc:prefixBase>
      </oslc:PrefixDefinition>
    </oslc:prefixDefinition>
    <oslc:prefixDefinition>
      <oslc:PrefixDefinition>
        <oslc:prefix>oslc_am</oslc:prefix>
        <oslc:prefixBase>http://open-services.net/ns/am#</oslc:prefixBase>
      </oslc:PrefixDefinition>
    </oslc:prefixDefinition>
    <oslc:service>
      <oslc:Service>
        <oslc:domain rdf:resource="http://open-services.net/ns/am#"/>
        <oslc:creationFactory>
          <oslc:CreationFactory>
            <dcterms:title>AM Resource Factory</dcterms:title>
            <oslc:label>AM Factory</oslc:label>
            <oslc:creation rdf:resource="http://acme.com:8080/oslc-am/factory/resource"/>
            <oslc:resourceType rdf:resource="http://open-services.net/ns/am#Resource"/>
            <oslc:resourceShape rdf:resource="http://acme.com:8080/oslc-am/shapes?type=Resource"/>
            <oslc:usage rdf:resource="http://open-services.net/ns/core#default"/>
          </oslc:CreationFactory>
        </oslc:creationFactory>
        <oslc:queryCapability>
          <oslc:QueryCapability>
            <dcterms:title>AM Resource Query</dcterms:title>
            <oslc:label>AM Query</oslc:label>
            <oslc:queryBase rdf:resource="http://acme.com:8080/oslc-am/query/resource"/>
            <oslc:resourceShape rdf:resource="http://acme.com:8080/oslc-am/shapes?type=Resource"/>
            <oslc:usage rdf:resource="http://open-services.net/ns/core#default"/>
          </oslc:QueryCapability>
        </oslc:queryCapability>
        <oslc:selectionDialog>
          <oslc:Dialog>
            <dcterms:title>AM Resource Selector</dcterms:title>
            <oslc:label>Picker</oslc:label>
            <oslc:dialog rdf:resource="http://acme.com:8080/oslc-am/selector/resource"/>
            <oslc:hintHeight>300px</oslc:hintHeight>
            <oslc:hintWidth>300px</oslc:hintWidth>
            <oslc:resourceType rdf:resource="http://open-services.net/ns/am#Resource"/>
            <oslc:usage rdf:resource="http://open-services.net/ns/core#default"/>
          </oslc:Dialog>
        </oslc:selectionDialog>
        <oslc:creationDialog>
          <oslc:Dialog>
            <dcterms:title>AM Resource Creator</dcterms:title>
            <oslc:label>Creator</oslc:label>
            <oslc:dialog rdf:resource="http://acme.com:8080/oslc-am/creator/resource"/>
            <oslc:hintHeight>300px</oslc:hintHeight>
            <oslc:hintWidth>300px</oslc:hintWidth>
            <oslc:resourceType rdf:resource="http://open-services.net/ns/am#Resource"/>
            <oslc:usage rdf:resource="http://open-services.net/ns/core#default"/>
          </oslc:Dialog>
        </oslc:creationDialog>
        <oslc:creationFactory>
          <oslc:CreationFactory>
            <dcterms:title>Link Type Factory</dcterms:title>
            <oslc:label>Link Type Factory</oslc:label>
            <oslc:creation rdf:resource="http://acme.com:8080/oslc-am/factory/linktype"/>
            <oslc:resourceType rdf:resource="http://open-services.net/ns/am#LinkType"/>
            <oslc:resourceShape rdf:resource="http://acme.com:8080/oslc-am/shapes?type=LinkType"/>
          </oslc:CreationFactory>
        </oslc:creationFactory>
        <oslc:queryCapability>
          <oslc:QueryCapability>
            <dcterms:title>Link Type Query</dcterms:title>
            <oslc:label>Link Type Query</oslc:label>
            <oslc:queryBase rdf:resource="http://acme.com:8080/oslc-am/query/linktype"/>
            <oslc:resourceShape rdf:resource="http://acme.com:8080/oslc-am/shapes?type=LinkType"/>
          </oslc:QueryCapability>
        </oslc:queryCapability>
        <oslc:selectionDialog>
          <oslc:Dialog>
            <dcterms:title>Link Type Selector</dcterms:title>
            <oslc:label>Link Type Picker</oslc:label>
            <oslc:dialog rdf:resource="http://acme.com:8080/oslc-am/selector/linktype"/>
            <oslc:hintHeight>300px</oslc:hintHeight>
            <oslc:hintWidth>300px</oslc:hintWidth>
            <oslc:resourceType rdf:resource="http://open-services.net/ns/am#LinkType"/>
          </oslc:Dialog>
        </oslc:selectionDialog>
        <oslc:creationDialog>
          <oslc:Dialog>
            <dcterms:title>Link Type Resource Creator</dcterms:title>
            <oslc:label>Link Type Creator</oslc:label>
            <oslc:dialog rdf:resource="http://acme.com:8080/oslc-am/creator/linktype"/>
            <oslc:hintHeight>300px</oslc:hintHeight>
            <oslc:hintWidth>300px</oslc:hintWidth>
            <oslc:resourceType rdf:resource="http://open-services.net/ns/am#LinkType"/>
          </oslc:Dialog>
        </oslc:creationDialog>
      </oslc:Service>
    </oslc:service>

  </oslc:ServiceProvider>
</rdf:RDF>

In addition to a duplication of the service provider information and the pre-defined namespace prefixes, this document gives us service endpoints for resource creation factories, query, and delegated UI selectors and creators.

Resource Creation

The OSLC AM specification defines two types of resources; Resource and Link Type. We will begin with the former and create a new instance of an AM Resource with the creation factory for resources of type: http://open-services.net/ns/am#Resource. In the document is a oslc:CreationFactory resource with a oslc:resourceType property has a value of http://open-services.net/ns/am#Resource. This resource defines a property for the actual service URL: http://acme.com:8080/oslc-am/factory/resource, and a URL for a resource shape http://acme.com:8080/oslc-am/shapes?type=Resource. 

          <oslc:CreationFactory>
            <dcterms:title>AM Resource Factory</dcterms:title>
            <oslc:label>AM Factory</oslc:label>
            <oslc:creation rdf:resource="http://acme.com:8080/oslc-am/factory/resource"/>
            <oslc:resourceType rdf:resource="http://open-services.net/ns/am#Resource"/>
            <oslc:resourceShape rdf:resource="http://acme.com:8080/oslc-am/shapes?type=Resource"/>
            <oslc:usage rdf:resource="http://open-services.net/ns/core#default"/>
          </oslc:CreationFactory>

The shape URL references a document that a client can use to determine what properties are required and can be included as a property when creating new resource instances.

Doing a GET on this resource URL returns the shape resource: 

<rdf:RDF 
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"    
   xmlns:dcterms="http://purl.org/dc/terms/"    
   xmlns:foaf="http://http://xmlns.com/foaf/0.1/"    
   xmlns:oslc="http://open-services.net/ns/core#">

<oslc:Shape rdf:about="http://acme.com:8080/oslc-am/shapes?type=Resource">

     <dcterms:title>AM Resource Shape</dcterms:title>
     <oslc:describes rdf:resource="http://open-services.net/ns/am#Resource" />

     <oslc:property>
         <oslc:Property>
             <oslc:name>title</oslc:name>
             <oslc:occurs rdf:resource="http://open-service.net/ns/core#Exactly-one" />
             <oslc:propertyDefinition rdf:resource="http://purl.org/dc/terms/title" />
             <oslc:valueType rdf:resource="http://www.w3.org/1999/02/22-rdf-syntax-ns#XMLLiteral" />
            <oslc:readOnly rdf:datatype="http://www.w3.org/2001/XMLSchema#boolean">false</oslc:readOnly>
         </oslc:Property>
     </oslc:property>

   <oslc:property>
      <oslc:Property>
         <oslc:name>type</oslc:name>
         <oslc:occurs rdf:resource="http://open-service.net/ns/core#One-or-many" />
         <oslc:propertyDefinition rdf:resource="http://www.w3.org/1999/02/22-rdf-syntax-ns#type" />
         <oslc:valueType rdf:resource="http://open-services.net/ns/core#Resource" />
         <oslc:representation rdf:resource="http://open-services.net/ns/core#Reference" />
         <oslc:readOnly rdf:datatype="http://www.w3.org/2001/XMLSchema#boolean">false</oslc:readOnly>
      </oslc:Property>
   </oslc:property>

     <oslc:property>
         <oslc:Property>
             <oslc:name>identifier</oslc:name>
             <oslc:occurs rdf:resource="http://open-service.net/ns/core#Exactly-one" />
             <oslc:propertyDefinition rdf:resource="http://purl.org/dc/terms/identifier" />
             <oslc:valueType rdf:resource="http://www.w3.org/2001/XMLSchema#string" />
             <oslc:readOnly rdf:datatype="http://www.w3.org/2001/XMLSchema#boolean">true</oslc:readOnly>
         </oslc:Property>
     </oslc:property>

     <oslc:property>
         <oslc:Property>
             <oslc:name>description</oslc:name>
             <oslc:occurs rdf:resource="http://open-service.net/ns/core#Zero-or-one" />
             <oslc:propertyDefinition rdf:resource="http://purl.org/dc/terms/description" />
             <oslc:valueType rdf:resource="http://www.w3.org/1999/02/22-rdf-syntax-ns#XMLLiteral" />
             <oslc:readOnly rdf:datatype="http://www.w3.org/2001/XMLSchema#boolean">false</oslc:readOnly>
         </oslc:Property>
     </oslc:property>

   <oslc:property>
      <oslc:Property>
         <oslc:name>source</oslc:name>
         <oslc:occurs rdf:resource="http://open-service.net/ns/core#Zero-or-one" />
         <oslc:propertyDefinition rdf:resource="http://purl.org/dc/terms/source" />
         <oslc:valueType rdf:resource="http://open-services.net/ns/core#Resource" />
         <oslc:representation rdf:resource="http://open-services.net/ns/core#Reference" />
         <oslc:readOnly rdf:datatype="http://www.w3.org/2001/XMLSchema#boolean">true</oslc:readOnly>
      </oslc:Property>
   </oslc:property>

   <oslc:property>
      <oslc:Property>
         <oslc:name>creator</oslc:name>
         <oslc:propertyDefinition rdf:resource="http://purl.org/dc/terms/creator" />
         <oslc:valueType rdf:resource="http://open-services.net/ns/core#Resource" />
         <oslc:representation rdf:resource="http://open-services.net/ns/core#Reference" />
         <oslc:occurs rdf:resource="http://open-service.net/ns/core#Zero-or-many" />
         <oslc:readOnly rdf:datatype="http://www.w3.org/2001/XMLSchema#boolean">true</oslc:readOnly>
      </oslc:Property>
   </oslc:property>

   <oslc:property>
      <oslc:Property>
         <oslc:name>contributor</oslc:name>
         <oslc:propertyDefinition rdf:resource="http://purl.org/dc/terms/contributor" />
         <oslc:valueType rdf:resource="http://open-services.net/ns/core#Resource" />
         <oslc:representation rdf:resource="http://open-services.net/ns/core#Reference" />
         <oslc:occurs rdf:resource="http://open-service.net/ns/core#Zero-or-many" />
         <oslc:readOnly rdf:datatype="http://www.w3.org/2001/XMLSchema#boolean">true</oslc:readOnly>
      </oslc:Property>
   </oslc:property>

     <oslc:property>
         <oslc:Property>
             <oslc:name>created</oslc:name>
             <oslc:occurs rdf:resource="http://open-service.net/ns/core#Zero-or-one" />
             <oslc:propertyDefinition rdf:resource="http://purl.org/dc/terms/created" />
             <oslc:valueType rdf:resource="http://www.w3.org/2001/XMLSchema#dateTime" />
             <oslc:readOnly rdf:datatype="http://www.w3.org/2001/XMLSchema#boolean">true</oslc:readOnly>
         </oslc:Property>
     </oslc:property>

     <oslc:property>
         <oslc:Property>
             <oslc:name>modified</oslc:name>
             <oslc:occurs rdf:resource="http://open-service.net/ns/core#Zero-or-one" />
             <oslc:propertyDefinition rdf:resource="http://purl.org/dc/terms/modified" />
             <oslc:valueType rdf:resource="http://www.w3.org/2001/XMLSchema#dateTime" />
             <oslc:readOnly rdf:datatype="http://www.w3.org/2001/XMLSchema#boolean">true</oslc:readOnly>
         </oslc:Property>
     </oslc:property>

     <oslc:property>
         <oslc:Property>
             <oslc:name>type description</oslc:name>
             <oslc:occurs rdf:resource="http://open-service.net/ns/core#Zero-or-many" />
             <oslc:propertyDefinition rdf:resource="http://purl.org/dc/terms/type" />
             <oslc:valueType rdf:resource="http://www.w3.org/2001/XMLSchema#string" />
             <oslc:readOnly rdf:datatype="http://www.w3.org/2001/XMLSchema#boolean">false</oslc:readOnly>
         </oslc:Property>
     </oslc:property>

     <oslc:property>
         <oslc:Property>
            <oslc:name>serviceProvider</oslc:name>
            <oslc:propertyDefinition rdf:resource="http://open-services.net/ns/core#serviceProvider" />
            <oslc:occurs rdf:resource="http://open-service.net/ns/core#Zero-or-many" />
            <oslc:valueType rdf:resource="http://open-services.net/ns/core#Resource" />
            <oslc:representation rdf:resource="http://open-services.net/ns/core#Reference" />
            <oslc:readOnly rdf:datatype="http://www.w3.org/2001/XMLSchema#boolean">true</oslc:readOnly>
         </oslc:Property>
     </oslc:property>

     <oslc:property>
         <oslc:Property>
            <oslc:name>related to</oslc:name>
            <oslc:propertyDefinition rdf:resource="http://purl.org/dc.terms/relation" />
            <oslc:occurs rdf:resource="http://open-service.net/ns/core#Zero-or-many" />
            <oslc:valueType rdf:resource="http://open-services.net/ns/core#Resource" />
            <oslc:representation rdf:resource="http://open-services.net/ns/core#Reference" />
            <oslc:readOnly rdf:datatype="http://www.w3.org/2001/XMLSchema#boolean">false</oslc:readOnly>
         </oslc:Property>
     </oslc:property>      </oslc:Shape>

</rdf:RDF>

From this document we can see that resources created with this factory are required to have a title (dcterms:title) and an type (rdf:type) property. New resources may also include an optional description (dcterms:description), one or more type descriptions (dcterms:type) and one or more Related To references (dcterms:relation). The type descriptions are simple human readable type names that are relevant in the domain. A Related To reference is a general purpose relationship to some other resource (possibly managed by a different service provider and in a different domain).

The server will provide exactly one identifier (dcterms:identifier) property, and optionally a source reference (dcterms:source), creator reference (dcterms:creator) , created date (dcterms:created), contributor reference (dcterms:contributor), modified date (dcterms:modified), and a service provider reference (oslc:serviceProvider).

We construct a new resource with the following RDF content: 

<?xml version="1.0" encoding="UTF-8"?>   
<rdf:RDF
      xmlns:dcterms="http://purl.org/dc/terms/"
      xmlns:oslc-am="http://open-services.net/ns/am#"
      xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
       <oslc-am:Resource rdf:about="">
    <dcterms:title>Logging Component</dcterms:title>
    <dcterms:description>A component for logging application activity.</dcterms:description>
  </oslc-am:Resource>   
</rdf:RDF>

An alternate form for the same resource is: 

<?xml version="1.0" encoding="UTF-8"?>
   <rdf:RDF
      xmlns:dcterms="http://purl.org/dc/terms/"
      xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
       <rdf:Description rdf:about="">
    <rdf:type rdf:resource="http://open-services.net/ns/am#Resource"/>
    <dcterms:title>Logging Component</dcterms:title>
    <dcterms:description>A component for logging application activity.</dcterms:description>
  </rdf:Description>   
</rdf:RDF>

The advantage of this second form is that it supports multiple types for the resource more consistently than the former form. Posting either of these documents to the factory URL with the appropriate OSLC Core and content type header will result in the creation of a new resource.

Request: 

POST http://acme.com:8080/oslc-am/factory/resource   OSLC-Core-Version: 2.0
Content-Type: application/rdf+xml

Response: 

201 Created
OSLC-Core-Version: 2.0
Location: http://acme.com:8080/oslc-am/resource/1
Etag: 5a3d31ee7379caab6e92ee271170bfc5
Last-Modified: Mon, 06 Dec 2010 16:19:58 -0500

The 201 Created response indicates a successful creation. The newly created resource URI is returned in the Location response header. The Etag and Last-Modified headers are used for subsequent modifications of this resource. We can get the OSLC representation of any resource by doing a GET on the resource, and specifying the format we are willing to receive with the Accept header. Minimally all OSLC service providers support RDF/XML as an acceptable representation format to request. We GET the newly created resource with the following:

Request: 

GET http://acme.com:8080/oslc-am/resource/1   OSLC-Core-Version: 2.0
Accept: application/rdf+xml

Response Headers: 

200 OK
OSLC-Core-Version: 2.0
Etag: dc26eca83ff84a0c90ef99c339e14ead
Last-Modified: Mon, 06 Dec 2010 16:13:48 -0500
Content-Type: application/rdf+xml
Content-Length: 1103

Response Body: 

<?xml version="1.0" encoding="UTF-8"?>
   <rdf:RDF
      xml:base="http://acme.com:8080/oslc-am/resource/1"
      xmlns:dcterms="http://purl.org/dc/terms/"
      xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">   
  <rdf:Description rdf:about="http://acme.com:8080/oslc-am/resource/1">
    <rdf:type rdf:resource="http://open-services.net/ns/am#Resource"/>
    <dcterms:title>Logging Component</dcterms:title>
    <dcterms:description>A component for logging application activity.</dcterms:description>
    <dcterms:identifier>1</dcterms:identifier>
    <dcterms:modified
            rdf:datatype="http://www.w3.org/2001/XMLSchema#datetime">Mon, 06 Dec 2010 16:13:48 -0500</dcterms:modified>
    <dcterms:created
            rdf:datatype="http://www.w3.org/2001/XMLSchema#datetime">Mon, 06 Dec 2010 16:13:48 -0500</dcterms:created>
    <dcterms:creator rdf:resource="http://acme.com:8080/oslc-am/user/_UNKNOWN_USER_"/>
    <dcterms:contributor rdf:resource="http://acme.com:8080/oslc-am/user/_UNKNOWN_USER_"/>
  </rdf:Description>
   </rdf:RDF>

The response headers should match those returned during the POST (assuming another concurrent user has not already modified the resource). The response document includes the original properties of the resource that were posted (title and description) plus the server generated identifier, creator, created, modified, contributor.

In this particular example the created and contributor properties are simple resource URIs, and in particular the default user is a special unknown user. This is a convention of this particular instance of an OSLC service provider, and is not driven by part of the official specification.

Other service provider’s implementations may provide richer information about users using a Person resource as defined by the Friend of a Friend (foaf) vocabulary. For example the previous GET of a resource might have returned this from another service implementation: 

<?xml version="1.0" encoding="UTF-8"?>
   <rdf:RDF
      xml:base="http://acme.com:8080/oslc-am/resource/1"
      xmlns:dcterms="http://purl.org/dc/terms/"
      xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">   
  <rdf:Description rdf:about="http://acme.com:8080/oslc-am/resource/1">
    <rdf:type rdf:resource="http://open-services.net/ns/am#Resource"/>
    <dcterms:title>Logging Component</dcterms:title>
    <dcterms:description>A component for logging application activity.</dcterms:description>
    <dcterms:identifier>1</dcterms:identifier>
    <dcterms:modified
            rdf:datatype="http://www.w3.org/2001/XMLSchema#datetime">Mon, 06 Dec 2010 16:13:48 -0500</dcterms:modified>
    <dcterms:created
            rdf:datatype="http://www.w3.org/2001/XMLSchema#datetime">Mon, 06 Dec 2010 16:13:48 -0500</dcterms:created>
    <dcterms:creator>
        <foaf:Person>
            <foaf:name>Oscar T. Grouch</foaf:name>
            <foaf:mbox rdf:resource="mailto:oscar@acme.com"/>
        </foaf:Person>
    </dcterms:creator>
    <dcterms:contributor>
        <foaf:Person>
            <foaf:name>Oscar T. Grouch</foaf:name>
            <foaf:mbox rdf:resource="mailto:oscar@acme.com"/>
        </foaf:Person>
     </dcterms:contributor>
  </rdf:Description>
   </rdf:RDF>

Of course if the service provider was to provide this extended user information it should be described in the shape resource. The corresponding shape resource would look something like: 

<oslc:property>
  <oslc:Property>
    <oslc:name>creator</oslc:name>
    <oslc:occurs rdf:resource="http://open-service.net/ns/core#Exactly-one" />
    <oslc:propertyDefinition rdf:resource="http://purl.org/dc/terms/creator" />
    <oslc:valueType rdf:resource="http://open-service.net/ns/core#LocalResource" />
    <oslc:representation rdf:resource="http://open-service.net/ns/core#Either" />
    <oslc:shape rdf:resource="http://acme.com:8080/oslc-am/shapes?type=Person" />
  </oslc:Property>
</oslc:property>

Where de-referencing the shape value for the property (http://acme.com:8080/oslc-am/shapes?type=Person) would provide the shape information about the Person resource like the following: 

<rdf:RDF 
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"    
   xmlns:dcterms="http://purl.org/dc/terms/"    
   xmlns:oslc="http://open-services.net/ns/core#" >

<oslc:ResourceShape rdf:about="http://xmlns.com/foaf/0.1/Person">
     <dcterms:title>Person Shape</dcterms:title>
     <oslc:name>Person</oslc:name>
     <oslc:describes rdf:resource="http://xmlns.com/foaf/0.1/Person" />

     <oslc:property>
         <oslc:Property>
             <oslc:name>full name</oslc:name>
             <oslc:occurs rdf:resource="http://open-service.net/ns/core#Exactly-one" />
             <oslc:propertyDefinition rdf:resource="http://xmlns.com/foaf/0.1/name" />
             <oslc:valueType rdf:resource="http://www.w3.org/2001/XMLSchema#string" />
             <oslc:readOnly rdf:datatype="http://www.w3.org/2001/XMLSchema#boolean">true</oslc:readOnly>
         </oslc:Property>
     </oslc:property>

     <oslc:property>
         <oslc:Property>
            <oslc:name>email address</oslc:name>
            <oslc:occurs rdf:resource="http://open-service.net/ns/core#Exactly-one" />
            <oslc:propertyDefinition rdf:resource="http://xmlns.com/foaf/0.1/mbox" />
            <oslc:valueType rdf:resource="http://open-services.net/ns/core#Resource" />
            <oslc:representation rdf:resource="http://open-services.net/ns/core#Reference" />
            <oslc:readOnly rdf:datatype="http://www.w3.org/2001/XMLSchema#boolean">true</oslc:readOnly>
         </oslc:Property>
     </oslc:property>

</oslc:ResourceShape>

</rdf:RDF>

Resource Modification

We can update the resource we just created with a new title and/or description by PUTing the document back to the server with the modified values. The PUT method is invoked on the resource URI (not a factory). We include the If-Match header with the Etag value for the resource with the PUT to make sure the server knows exactly which version of the resource we are attempting to update.

Request: 

PUT http://acme.com:8080/oslc-am/resource/1   OSLC-Core-Version: 2.0
Content-Type: application/rdf+xml
If-Match: dc26eca83ff84a0c90ef99c339e14ead

Request Body: 

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF 
  xmlns:dcterms="http://purl.org/dc/terms/" 
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">

  <rdf:Description rdf:about="http://acme.com:8080/oslc-am/resource/1">
    <rdf:type rdf:resource="http://open-services.net/ns/am#Resource"/>
    <dcterms:title>Logging Component Revised</dcterms:title>
    <dcterms:description>A component for logging application activity and debugging.</dcterms:description>
  </rdf:Description>

</rdf:RDF>

Response Headers: 

200 OK   OSLC-Core-Version: 2.0   Etag: 8cc812dd3f8d745303e34083b4c60353   Last-Modified: Mon, 06 Dec 2010 17:41:32 -0500

The successful response (200 OK) includes new Etag and Last-Modified header values.

Adding Resource Links

Linking resources in the OSLC is for the most part simply a matter of adding an additional property to the resource that references the URI of the resource being linked to. In this example the creation factory resource shape indicates that it is willing to accept new resources with dcterms:relation properties. Each of which has a URI value that points to the resource being linked to. Suppose we want to make a “Related To” link to a resource given by the URI http://example.com/requirements/42. We PUT back the resource with a the new property added.

Request: 

PUT http://acme.com:8080/oslc-am/resource/1   OSLC-Core-Version: 2.0
Content-Type: application/rdf+xml
If-Match: 8cc812dd3f8d745303e34083b4c60353

Request Body: 

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF 
  xmlns:dcterms="http://purl.org/dc/terms/" 
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">

  <rdf:Description rdf:about="http://acme.com:8080/oslc-am/resource/1">
    <rdf:type rdf:resource="http://open-services.net/ns/am#Resource"/>
    <dcterms:title>Logging Component Revised</dcterms:title>
    <dcterms:description>A component for logging application activity and debugging.</dcterms:description>
    <dcterms:relation rdf:resource="http://example.com/requirements/42"/>
  </rdf:Description>

</rdf:RDF>

Response Headers:

200 OK OSLC-Core-Version: 2.0 Etag: 04bc4d7e1ec504b19ff50319ed9378df Last-Modified: Mon, 06 Dec 2010 21:11:00 -0500 If the service provider supports link properties, it is possible to associate properties on the link itself. Using an RDF technique called statement reification it is possible in the RDF model to augment the resource definition with statements that associate any RDF property to the link property.

In the following example we update the same resource further by adding a description to the link.

Request: 

PUT http://acme.com:8080/oslc-am/resource/1   OSLC-Core-Version: 2.0
Content-Type: application/rdf+xml
If-Match: 04bc4d7e1ec504b19ff50319ed9378df

Request Body: 

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF 
  xmlns:dcterms="http://purl.org/dc/terms/" 
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">

  <rdf:Description rdf:about="http://acme.com:8080/oslc-am/resource/1">
    <rdf:type rdf:resource="http://open-services.net/ns/am#Resource"/>
    <dcterms:title>Logging Component Revised</dcterms:title>
    <dcterms:description>A component for logging application activity and debugging.</dcterms:description>
    <dcterms:relation rdf:ID="link1" rdf:resource="http://example.com/requirements/42"/>
  </rdf:Description>
     <rdf:Description rdf:about="#link1">
    <dcterms:description>The original design of the component in version 1.</dcterms:description>
  </rdf:Description>
</rdf:RDF>

Response Headers:

200 OK OSLC-Core-Version: 2.0 Etag: 2c5ec303460408373411e1bf764cd85e Last-Modified: Mon, 06 Dec 2010 21:19:28 -0500 In this example a separate rdf :Description node captures the properties of link. Its rdf:about value references an rdf:ID attribute of an element in the main description.

Deleting Resources

Deleting a resource is a simple matter of invoking the HTTP DELETE method on a resource URI with an appropriate conditional header (If-Match, If-Modified-Since, If-None-Match and If-Unmodified-Since).

Deleting the resource created (and modified above) is accomplished with:

Request: 

DELETE http://acme.com:8080/oslc-am/resource/1   OSLC-Core-Version: 2.0
Content-Type: application/rdf+xml
If-Match: 2c5ec303460408373411e1bf764cd85e

Response Headers: 

200 OK   OSLC-Core-Version: 2.0

A successful deletion of the resource returns a 200 OK response.

HTML Representation

The specification states that service implementations SHOULD provide HTML representations for resources. Specifying a request for HTML response is done with the Accept header on the resource GET. For example suppose we GET another resource from the server requesting an HTML response.

Request: 

GET http://acme.com:8080/oslc-am/resource/2   OSLC-Core-Version: 2.0
Accept: text/html

Response Headers: 

200 OK   OSLC-Core-Version: 2.0   Content-Type: text/html;charset=ISO-8859-1
Content-Length: 2798
Date: Tue, 07 Dec 2010 13:42:55 GMT

Response Body: 

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--
   Copyright 2010 IBM 

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
 -->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>SORI AM Resource View (http://acme.com:8080/oslc-am/resource/2)</title>
<link rel="SHORTCUT ICON" href="oslc.png">
</head>
<body>
<p><a href="/oslc-am/index.jsp">Home</a></p>
<h1>OSLC AM Resource: Logging Component</h1>
<table>
<tr><td>URI:</td><td><b>http://acme.com:8080/oslc-am/resource/2</b></td></tr>
<tr><td>Title:</td><td><b>Logging Component</b></td></tr>
<tr><td>Created:</td><td><b>Mon Dec 06 16:14:26 EST 2010</b></td></tr>
<tr><td>Modified:</td><td><b>Mon Dec 06 16:14:26 EST 2010</b></td></tr>
<tr><td>ETag:</td><td><b>f4f09f25fd6268e7555bd2e6fd3b2dfb</b></td></tr>
</table>   ...

UI Preview

Sometimes a client (or another service provider) may not be interested in the full details of resource and just want a human readable summary of the resource. This happens frequently in web applications that provide popup help on a link or reference. In the OSLC this is called UI Preview. A client requests a resource’s UI Preview by first getting a special XML document with the media type: application/x-oslc-compact+xml. This document

Request: 

GET http://acme.com:8080/oslc-am/resource/2   OSLC-Core-Version: 2.0
Accept: application/x-oslc-compact+xml
Response Headers:
200 OK   OSLC-Core-Version: 2.0   Content-Type: text/html;charset=ISO-8859-1
Content-Length: 2798
Date: Tue, 07 Dec 2010 13:42:55 GMT

Response Body: 

<?xml version="1.0" encoding="UTF-8"?> 
<rdf:RDF 
   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
   xmlns:dcterms="http://purl.org/dc/terms/" 
   xmlns:oslc="http://open-services.net/ns/core#"> 
 <oslc:Compact 
   rdf:about="http://acme.com:8080/oslc-am/resource/2"> 
   <dcterms:title>Logging Component</dcterms:title> 
   <oslc:shortTitle>Resource 2</oslc:shortTitle> 
   <oslc:icon rdf:resource="http://acme.com:8080/oslc-am/oslc.png" /> 
   <oslc:smallPreview> 
      <oslc:Preview> 
         <oslc:document rdf:resource="http://acme.com:8080/oslc-am/compact/resource?uri=http%3A%2F%2Facme.com%3A8080%2Foslc-am%2Fresource%2F2&amp;type=small" /> 
         <oslc:hintWidth>500px</oslc:hintWidth> 
         <oslc:hintHeight>120px</oslc:hintHeight> 
      </oslc:Preview> 
   </oslc:smallPreview> 
   <oslc:largePreview> 
      <oslc:Preview> 
         <oslc:document rdf:resource="http://acme.com:8080/oslc-am/compact/resource?uri=http%3A%2F%2Facme.com%3A8080%2Foslc-am%2Fresource%2F2&amp;type=large" /> 
         <oslc:hintWidth>500px</oslc:hintWidth> 
         <oslc:hintHeight>500px</oslc:hintHeight> 
      </oslc:Preview> 
   </oslc:largePreview> 
 </oslc:Compact> 
</rdf:RDF>

The returned document (which is also valid RDF), specifies two previews, a large and small one. With each is a width and height hint. The oslc:document property specifies a URL that a client can perform a GET on and request an HTML document that will be a compact HTML representation of the resource, suitable for pop up or hover helps.

Request: 

GET http://acme.com:8080/oslc-am/compact/resource?uri=http%3A%2F%2Facme.com%3A8080%2Foslc-    am%2Fresource%2F2&amp;type=small   OSLC-Core-Version: 2.0
Accept: text/html

Response Headers: 

200 OK   OSLC-Core-Version: 2.0   Content-Type: text/html
Content-Length: 920
Date: Tue, 07 Dec 2010 15:16:36 GMT

Response Body: 

<!--
   Copyright 2010 IBM 

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
 -->
<html>
<head>
<title>OSLC AM Resource: Logging Component (2)</title>
<link rel="SHORTCUT ICON" href="oslc.png">
</head>
<body>
<i>Compact Preview (Small)</i><br/>
URI: http://acme.com:8080/oslc-am/resource/2<br/>
Title: Logging Component<br/>
Identifier: 2<br/>
Created: 12/6/10 4:14 PM
</body>
</html>

Query Capability (INCOMPLETE)

The next service interface in the service provider document is the Query interface. This URI, also associated with a resource shape, is the same shape URL as was associated with the resource factory. This means that we are able to query across the all he properties that we could define and read from the server.

Conceptually this URI represents a single resource that acts as the starting resource that must be ‘filtered’ to get a manageable set of other resources that are the ones that are of interest to the client.

The specification requires that all service providers at least provide responses in RDF/XML. TBD

Request: 

GET http://acme.com:8080/oslc-am/query/resource?oslc.where=dcterms:identifier=%225%22   OSLC-Core-Version: 2.0
Accept: application/rdf+xml
Response Headers:
200 OK
OSLC-Core-Version: 2.0
Content-Type: application/rdf+xml
Content-Length: 591
Date: Tue, 07 Dec 2010 15:23:38 GMT

Response Body: 

<?xml version="1.0" encoding="UTF-8"?>   <rdf:RDF      xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"      xmlns:dcterms="http://purl.org/dc/terms/"     xmlns:oslc="http://open-services.net/ns/core#"      xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#">   
  <oslc:responseInfo rdf:about="http://acme.com:8080/oslc-am/query/resource">
    <dcterms:title>Resource Query Results</dcterms:title>
  </oslc:responseInfo>
     <rdf:Description rdf:about="http://acme.com:8080/oslc-am/query/resource">
    <rdfs:member rdf:resource="http://acme.com:8080/oslc-am/resource/5"/>
  </rdf:Description>
   </rdf:RDF>

Delegated UI

The OSLC Core specification defines a means for a client (or sister application) to leverage parts of a user interface from another OSLC service provider. Typically this is used when one service provider’s web interface wants to allow its users to select (or create) a resource that is managed by another separate OSLC service provider.

The specification uses the terms: UI Consumer - a web application that is embedding a Delegated UI Dialog from an OSLC Service Provider. This consumer could be a web page, with the Delegated UI Dialog loaded into an iframe or a native application, e.g. an IDE like Eclipse, that is embedding a web browser component. UI Provider - an OSLC Service provider that offers one or more Delegated UI Dialogs. These dialogs will be specified in the provider's Service Provider resource.

UI Providers include in their service document a reference to one or more oslc:selectionDialog resources. Each of these properties has an inlined Dialog resource, whose properties include a width and height hint, the RDF type of the resources being selected (or created), and the URL of the dialog itself. 

<oslc:selectionDialog>
  <oslc:Dialog>
    <dcterms:title>AM Resource Selector</dcterms:title>
    <oslc:label>Picker</oslc:label>
    <oslc:dialog rdf:resource="http://acme.com:8080/oslc-am/selector/resource"/>
    <oslc:hintHeight>300px</oslc:hintHeight>
    <oslc:hintWidth>300px</oslc:hintWidth>
    <oslc:resourceType rdf:resource="http://open-services.net/ns/am#Resource"/>
    <oslc:usage rdf:resource="http://open-services.net/ns/core#default"/>
  </oslc:Dialog>
</oslc:selectionDialog>

A client performs a GET on the dialog URL. The returned HTML document includes JavaScript? that interacts with the host server to select (or create) a resource. Not all browsers provide the exact same level of JavaScript? support. To support the widest range of web browsers, the specification defines two different protocols for communicating the information about the user's action from the UI Provider and back to the UI Consumer. These are the Post Message and Window Name protocols.

The UI Consumer decides which protocol to request by. The UI Provider should be able to accommodate either. The The SORI-AM provider includes a delegated UI for both selection and creation of AM Resources. Another hosting application

Edit | Attach | Print version | History: r12 < r11 < r10 < r9 < r8 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r12 - 07 Jan 2011 - 15:11:40 - DaveJohnson
 
This site is powered by the TWiki collaboration platform Copyright � by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use
Ideas, requests, problems regarding this site? Send feedback