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.

Architecture Management Service Description

Introduction

This document describes how clients can discover services that the service provider offers. It leverages the common service provider catalog specification. This document specifies the actual AM service document, which the catalog document points to.

This specification leverages the common OSLC specification for service description. This document defines the structure of the catalog of of services. A service provider catalog contains references to a number of services, often organized by project hosted on the service provider (but not necessarily). Each of these service providers specifies a details URL and a services URL. The details URL can be navigated to by a browser to view general information about this services provider (i.e. the default home page for the project that these services are being provided for). The services URL returns a service document that includes the factory or creation URLs and resource picker URLs.

Sevice Discovery

Starting with a single entry point to a service provider {base-url}, clients will discover the (typically hierarchical) arrangement of contexts (which may be development projects) managed by the application. To support the wide range of application and project configurations, OSLC is not specifying a predetermined arrangement of these contexts. Instead, clients will be able to iterate through a group of collections (Service Provider Catalogs) until identifying a context of interest, where the client will find an AM Service Description Document.

The dicovery model flow is as follows:

  1. Request information from an OSLC AM service provider: GET {url}
  2. If Response is a Service Provider Catalog:
    1. An entry is selected from the Service Provider Catalog
    2. With this entry's {url}, repeat to step #1
  3. If Response is a Service Description Document, then continue to next step
  4. Configuration has completed

The number of iterations over the configuration choices should be set by the client application. Typical configurations should not need more than 2 levels of configuration context, so a limit of 5 is recommended.

Termination of the discover occurs when a the client application receives an HTTP response with a Content-Type of application/x-oslc-service-description+xml and the service description document as the response's content body.

XML namespace abbreviations used in this resource document:

  • rdf - RDF XML namespace - http://www.w3.org/1999/02/22-rdf-syntax-ns#
  • dc - The Dublin Core Metadata Terms namespace - http://purl.org/dc/terms/
  • oslc_disc - The Open Services for Lifecycle Collaboration Discovery namespace - http://open-services.net/xmlns/discovery/1.0/

Example

A Service Provider Catalog Resource located at http://am.acme.com/AMCatalog. The document lists 2 service providers.

<?xml version="1.0"?>
<oslc_disc:ServiceProviderCatalog
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:dc="http://purl.org/dc/terms/"  
  xmlns:oslc_disc="http://open-services.net/xmlns/discovery/1.0/"
  rdf:about="http://am.acme.com/AMCatalog" >

  <dc:title>Architecture Management Service Provider Catalog</dc:title>

  <oslc_disc:entry>
     <oslc_disc:ServiceProvider>
        <dc:title>Project X</dc:title>
        <oslc_disc:details rdf:resource="http://am.acme.com/projects/_CGwYgAnrEd6_yLxvteIpZw" />
        <oslc_disc:services
             rdf:resource="http://am.acme.com/projects/_CGwYgAnrEd6_yLxvteIpZw/services.xml" />
     </oslc_disc:ServiceProvider>
  </oslc_disc:entry>

  <oslc_disc:entry>
     <oslc_disc:ServiceProvider>
        <dc:title>Project Y</dc:title>
        <oslc_disc:details rdf:resource="http://am.acme.com/projects/_sajkASDo92asDAsjd" />
        <oslc_disc:services
             rdf:resource="http://am.acme.com/projects/_sajkASDo92asDAsjd/services.xml" />
     </oslc_disc:ServiceProvider>
  </oslc_disc:entry>

</oslc_disc:ServiceProviderCatalog>

AM Service Description Resource

A Service Description Resource is an informational resource describing a the contextual configuration needs of a service provider. It provides configuration definitions needed by consumers of an AM service provider.

The Service Description Document MUST be indentified using the media type of application/x-oslc-service-description+xml.

XML namespace abbreviations used in this resource document:

  • rdf - RDF XML namespace - http://www.w3.org/1999/02/22-rdf-syntax-ns#
  • dc - The Dublin Core Metadata Terms namespace - http://purl.org/dc/terms/
  • oslc_am - The Open Services for Lifecycle Collaboration Architecture Management namespace - http://open-services.net/xmlns/am/1.0/

The Service Descriptor element provides human readable information about the context for which the services are for. A human readable label for the context that these services are for is specified in the text content of a child dc:title element. A longer description is specified in the optional text content of a child dc:description element.

A Service Descriptor element includes many oslc_am:SelectionDialog and oslc_am:ResourceFactory child elements.

Selection Dialog elements MUST specify the URL of the service with a rdf:resource attribute. This is the URL which clients GET the HTML based UI for the selection (and if supported, creation) of AM Resources in this context. The REST services provided at this URL are defined in AM Delegated Resource Selection and Creation REST API . The required dc:title child element provides a human readable label for this service. Two optional child elements; oslc_am:hintWidth and oslc_am:hintHeight specify the suggested size of the dialog or frame to render the HTML content in. Expected for the size values are defined by CSS length units.

Resource Factory elements MUST specify the URL of the service with a rdf:resource attribute. This is the URL that clients POST new AM Resources to. The optional dc:title provides a human readable label of this factory service.The REST services provided at this URL are defined in AM Resource Factory REST API.

Example

In this example the service description is for a context called "Project X". The services provided are a Resource Picker and an AMR Factory.

<oslc_am:ServiceDescriptor xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   xmlns:dc="http://purl.org/dc/terms/" xmlns:oslc_am="http://open-services.net/xmlns/am/1.0/"
   rdf:about="http://am.acme.com/service-descriptor.xml">

   <dc:title>Project X</dc:title>
   <dc:description>My description of Project X.</dc:description>

   <oslc_am:ResourceFactory
      rdf:resource="https://am.acme.com/resourceFactory?projectId=Project%20X">
      <dc:title>Factory for creating AM Resources from an OSLC AM resource format in Project X</dc:title>
   </oslc_am:ResourceFactory>

   <oslc_am:ResourceSourceFactory
      rdf:resource="https://am.acme.com/resourceFactory?projectId=Project%20X">
      <dc:title>Factory for creating AM Resources from non-OSLC AM resource formats in Project X</dc:title>
   </oslc_am:ResourceSourceFactory>

   <oslc_am:SimpleQuery
      rdf:resource="https://am.acme.com/simplequery/project1/">
      <dc:title>Simple Query end point</dc:title>
   </oslc_am:SimpleQuery>

   <oslc_am:LinkTypeFactory
      rdf:resource="https://am.acme.com/linkTypeFactory?projectId=Project%20X">
      <dc:title>Factory for getting creating (POST) Link Type URIs for use in Project X</dc:title>
   </oslc_am:LinkTypeFactory>

   <oslc_am:LinkTypeQuery
      rdf:resource="https://am.acme.com/linkTypeFactory?projectId=Project%20X">
      <dc:title>Factory for getting Link Type URIs for use in Project X</dc:title>
   </oslc_am:LinkTypeQuery>

   <oslc_am:SelectionDialog
      rdf:resource="https://am.acme.com/resourcePicker?projectId=Project%20X">
      <dc:title>Web UI for finding and selecting AM resources in Project X</dc:title>
      <oslc_am:hintWidth>400px</oslc_am:hintWidth>
      <oslc_am:hintHeight>500px</oslc_am:hintHeight>
   </oslc_am:SelectionDialog>

</oslc_am:ServiceDescriptor> 

Providers of this Service Description Document MAY provide additional properties in a non-OSLC namespace.

Edit | Attach | Print version | History: r15 < r14 < r13 < r12 < r11 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r12 - 16 Jun 2010 - 15:40:01 - JimConallen
 
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