OA Service Specifications S

FP6-511678 ORCHESTRA Open Architecture and Spatial Data Infrastructure for Risk Management Integrated Project

Priority 2.3.2.9 Improving Risk Management

WP3.4 – OA Service Specifications

Specification of the Annotation Service

Revision

1/42

[1.0 / 2.0.6]

Specification of the Annotation Service – Document Control Page

Document Control Page Title

Specification of the Annotation Service

Creator

Ulrich Bügel, Fraunhofer IITB

Subject

WP3.4 – Core Service Specifications

Description

This document defines an abstract and platform independent formal interface specification of the Annotation Service.

Publisher

ORCHESTRA consortium

Contributor

Alina Kopp, Fraunhofer IITB

Date

2007-03-27

Type

Text

Format

application/msword

Identifier

http://portal.opengeospatial.org/files/?artifact_id=12994

Source

Not applicable

Language

en-GB.

Relation

none

Coverage

ORCHESTRA Consortium and restricted audience

Rights Deliverable number

D3.4.3

Work-Package contributing to the Deliverable

WP3.4

Contractual Date of Delivery

2006-xx-xx

Actual Date of Delivery

2006-xx-xx

Audience

public restricted internal

Version number

1.0 / 2.0.6

Date

2007-03-21

Modified by

Ulrich Bügel, Fraunhofer IITB

Comments Status

Draft WP leader accepted SP leader accepted Technical supervisor accepted Quality checked

2/42

Specification of the Annotation Service – Document Control Page

Project coordinator accepted Action requested

to be revised by partners involved in the preparation of the deliverable for approval of the WP leader for approval of the SP leader for approval of the Technical Supervisor for approval of the Quality Manager for approval of the Project Coordinator Deadline for action: 2006-xx-xx

3/42

Specification of the Annotation Service – Revision History

Revision History Revision

Date

Sections changed

Description st

0.1 / 1.2

2005-11-08

1 draft

0.2 / 1.6

2005-12-07

all

Adapted to template 1.6

0.3 / 1.6

2006-01-13

all

Incorporated annotation of databases and applications

0.4 / 1.7

2006-03-22

all

Adapted to template 1.7 Incorporated Atos and BRGM comments

1.0 / 2.06

2007-03-21

all

Adapted to template 2.06 Modifications in UML and Text

4/42

Specification of the Annotation Service – Table of Contents

Table of Contents 1

Foreword..................................................................................................................................................... 8

2

Overview and Architecture Outline ............................................................................................................. 8 2.1

2.1.1

Annotation of unstructured sources ............................................................................................. 8

2.1.2

Annotation of structured sources ................................................................................................. 8

2.2 3

5

3.1

Relations to Standards ...................................................................................................................... 11

3.2

Relations to other ORCHESTRA Service Specifications .................................................................. 11

3.3

Relations to ORCHESTRA Application Schemas ............................................................................. 15

3.4

Relations to ongoing Initiatives and related Projects ........................................................................ 15

3.4.1

GATE (General Architecture for Text Engineering) ................................................................... 15

3.4.2

Amilcare ..................................................................................................................................... 15

3.4.3

KIM (Knowledge & Information Management) ........................................................................... 16

3.4.4

CREAM (CREAting Metadata for the Semantic Web) ............................................................... 16

Relations to ORCHESTRA User and System Requirements............................................................ 16

3.5.1

Fulfilment of ORCHESTRA User Requirements ........................................................................ 16

3.5.2

Fulfilment of the Requirements for the OSN and the OA........................................................... 16

3.5.3

Contribution to the ORCHESTRA Development Dimensions .................................................... 17

Requirements ........................................................................................................................................... 18 4.1

Security Requirements ...................................................................................................................... 18

4.2

Reliability Requirements.................................................................................................................... 18

Conventions .............................................................................................................................................. 19 5.1

Abbreviations ..................................................................................................................................... 19

5.2

Terms and definitions ........................................................................................................................ 19

5.3

UML Notation..................................................................................................................................... 19

5.4

Conformance ..................................................................................................................................... 19

5.4.1

Conformance to the OMM .......................................................................................................... 19

5.4.2

Conformance of Implementation Specifications......................................................................... 19

5.5 6

Service Interface Specification Summary............................................................................................ 8

Context of the Annotation Service ............................................................................................................ 11

3.5

4

Role and Scope of the Annotation Service.......................................................................................... 8

Used parts of other documents ......................................................................................................... 19

Service Interface Specification ................................................................................................................. 20 6.1

Specification of an OAS Profile of Parameter Types used by the Annotation Service ..................... 20

5/42

Specification of the Annotation Service – Table of Contents 6.2

Specification of the Service Interface Operations ............................................................................. 26

6.2.1

Specification of the createSemanticDocument Operation ......................................................... 26

6.2.2

Specification of the annotateDocument Operation .................................................................... 28

6.2.3

Specification of the annotateText Operation .............................................................................. 29

6.2.4

Specification of the annotateDataOntology Operation............................................................... 29

6.3

Specification of extended Service Capabilities.................................................................................. 31

6.4

Specification of additional Types ....................................................................................................... 32

6.4.1

OA_SemanticDocument............................................................................................................. 32

6.4.2

OA_AnnotationStrategy ............................................................................................................. 33

6.4.3

OA_ AnnotationSet..................................................................................................................... 34

6.4.4

OA_ Annotation .......................................................................................................................... 35

6.4.5

OA_ Mapping ............................................................................................................................. 35

6.4.6

OA_ MappingArgument.............................................................................................................. 36

6.4.7

OA_ MappingArgumentType...................................................................................................... 36

6.4.8

OA_ MAConcept ........................................................................................................................ 36

6.4.9

OA_ MAInstance ........................................................................................................................ 37

6.4.10

OA_ MAProperty ........................................................................................................................ 37

6.4.11

OA_ MappingValue .................................................................................................................... 37

6.4.12

OA_ MappingValueType ............................................................................................................ 38

6.4.13

OA_ MVPassage........................................................................................................................ 38

6.4.14

OA_ MVDocument ..................................................................................................................... 39

6.4.15

OA_ MVDataOntology................................................................................................................ 39

6.4.16

OA_ Node................................................................................................................................... 40

6.4.17

OA_ OntologyParseFailed ......................................................................................................... 40

6.4.18

OA_ UnknownDocumentFormat ................................................................................................ 40

6.4.19

OA_ UnknownDocumentFormat ................................................................................................ 40

6.4.20

OA_ DocumentNotFound ........................................................................................................... 40

6.5

Known Issues and Limitations ........................................................................................................... 40

7

Appendix A: Abstract Test Suite (normative)............................................................................................ 41

8

Appendix B: UML Models (normative) ...................................................................................................... 42 8.1

Static Model ....................................................................................................................................... 42

8.2

Dynamic Model .................................................................................................................................. 42

6/42

Specification of the Annotation Service – Tables and Diagrams

Tables Table 1: Summary of inherited Service Operations ........................................................................................... 9 Table 2: Summary of additional Service Operations ....................................................................................... 10 Table 3: Interaction between related services ................................................................................................. 15 Table 4: Referenced OA Types ....................................................................................................................... 26 Table 5: Specification of the createSemanticDocument Operation ................................................................. 27 Table 6: Specification of the annotateDocument operation ............................................................................. 29 Table 7: Specification of the annotateText operation ...................................................................................... 29 Table 8: Specification of annotateDataOntology operation ............................................................................. 30 Table 9: Sections of the service specific capabilities....................................................................................... 31 Table 10: Attributes of the service specific capabilities of section Annotation Service Capabilities................ 32 Table 11: Annotation Strategies....................................................................................................................... 34

Diagrams Diagram 1: Class Diagram of the Annotation Interface ..................................................................................... 9 Diagram 2: User diagram of related services ................................................................................................. 13 Diagram 3: Interface and classes of the Annotation Service.......................................................................... 24 Diagram 4: Class diagram of Service Capabilites ........................................................................................... 31

7/42

Specification of the Annotation Service – Foreword

1

Foreword This document is an abstract specification of the Annotation service and is based on the Template for the abstract Specification of ORCHESTRA Services version 2.06. It updates the specification version 1.7. An update of the UML diagrams and the text was required due to slight optimizations of the UML diagrams. This document includes two annexes: Appendix A: Abstract Test Suite (normative) is mandatory and Appendix B: UML Models (normative) is optional.

2

Overview and Architecture Outline

2.1

Role and Scope of the Annotation Service The Annotation Service automatically generates specific meta-information from various sources and relates them to their semantic descriptions. The semantic descriptions here are assumed to be specified as elements of an ontology (e.g. concepts, properties, instances). Sources to be annotated can contain unstructured information (e.g. documents, texts) or structured information (e.g. databases, applications).

2.1.1

Annotation of unstructured sources The Annotation Service automatically generates meta-information for unstructured sources such as documents and/or texts. The generation of annotations is based on automatic Information Extraction (IE), by means of which entities occurring in documents and texts can be identified and assigned to ontological elements. The process of Information Extraction can additionally be based on background knowledge held in a repository, e.g. a knowledge base with pre-populated instances . Entities in the text can be assigned to ontological elements defined in the ontology. Optionally, the Annotation Service can discover and suggest new elements by processing the documents and texts, and populate them to a knowledge repository. The semantic annotation of documents and texts enables applications such as highlighting, document viewing supported by automatically generated links to semantic descriptions, or semantic indexing and retrieval (as described in the Document Index Service).

2.1.2

Annotation of structured sources The Annotation Service automatically generates meta-information for structured sources such as databases, applications etc. As a pre-requisite of the Annotation Service, the structure and content of such a resource is to be transformed into a data ontology which is compliant to the ontology containing the semantic descriptions. An annotation is a mapping of an element of this ontology to an element of the data ontology. Moreover, the annotation process can comprise the population of the knowledge base with content of the database described in the data ontology. The semantic annotation of databases and applications enables applications such as exploration of the database structure and content by means of ontology query languages, or interpretation of query results by means of domain knowledge.

2.2

Service Interface Specification Summary This interface specification of the Annotation Service extends the following interfaces: •

The Service Capabilities Interface of the RM-OA Service Specification

The Annotation Service - in its current design stage - provides operations for annotating a document or a data ontology which has been established from a database or an application. Sources to be anno-

8/42

Specification of the Annotation Service – Overview and Architecture Outline tated are identified by a document descriptor, which contains a reference to a resource location identifier. For each source to be annotated, an additional document - called a "semantic document" - is established which contains the annotations. An additional operation foresees the annotation of texts; here, the annotations are delivered directly in the operation result, a semantic document is not generated. Annotations for documents or texts are established automatically by means for Information Extraction (IE) technology. An annotation strategy can be selected, which performs extractions according to a specific method. An annotation is established for each named entity identified in the text, which can refer to a concept, an instance or a relation of the ontology. Annotations for structured sources are established automatically by assigning elements of the domain ontology to the data ontology. An annotation strategy can be selected, which performs these mappings according to a specific method. The strategy expresses facilities for mapping e.g. concepts to database tables, object properties to relations, datatype properties to attributes or ontology queries to database queries.

cd Annotation Serv ice Ov erv iew «interface» OA Basic Service::ServiceCapabilities +

getCapabilities(OA_GetCapabilitiesRequest) : OA_CapabilitiesDocument

«interface» AnnotationService + + + + + + +

createSemanticDocument(OA_DocumentDescriptor) : OA_SemanticDocument annotateDocument(OA_SemanticDocument, OA_Ontology) : OA_SemanticDocument annotateDocument(OA_SemanticDocument, OA_Ontology, OA_AnnotationStrategy) : OA_SemanticDocument annotateText(OA_String, OA_Ontology) : OA_AnnotationSet annotateText(OA_String, OA_Ontology, OA_AnnotationStrategy) : OA_AnnotationSet annotateDataOntology(OA_SemanticDocument, OA_Ontology) : OA_SemanticDocument annotateDataOntology(OA_SemanticDocument, OA_Ontology, OA_AnnotationStrategy) : OA_SemanticDocument

Diagram 1: Class Diagram of the Annotation Interface

The Annotation Service interface defines or uses the following operations of inherited interfaces:

Interface Name Service Capabilities

Operation Name GetCapabilities

Specialisation No

Table 1: Summary of inherited Service Operations Table 1 does not list optional operations that are not used by this service.

9/42

Specification of the Annotation Service – Overview and Architecture Outline The Annotation Service interface defines the following additional operations:

Operation

Description

getCapabilities

Delivers information about the capabilities of an Annotation Service.

createSemanticDocument

Create the content of a semantic document from a base document identified by a resource description.

annotateDocument

Execute the Annotation Service over a given semantic document, applying the given annotation strategy and input ontology.

annotateText

Execute the Annotation Service over the given string content, applying the given annotation strategy and input ontology.

annotateDataOntology

Execute the Annotation Service over the given data ontology, which has been generated from a structured source (e.g. a database), applying the given annotation strategy and input ontology. Table 2: Summary of additional Service Operations

10/42

Specification of the Annotation Service – Context of the Annotation Service

3

Context of the Annotation Service In this chapter, the relations of this service to international standards, other ORCHESTRA Services, ORCHESTRA Application Schemas and ongoing initiatives shall be explicated.

3.1

Relations to Standards The standards listed below are recommended to be used in implementations - because they are widely adopted in Semantic Web community – but they are not mandatory. The Annotation Service is defined independent of these standards on the abstract level.

Annotations refer to the concepts of an ontology, which is specified in an ontology language such as OWL and RDFS (a subset of OWL): W3C-Ontology Web Language (OWL) http://www.w3.org/TR/owl-features/ RDF-Schema http://www.w3.org/TR/rdf-schema/ The Annotation Service supports the discovery of new knowledge (concepts, instances, relations etc.), which can be populated into the knowledge base. The knowledge base itself is assumed to have a query interface according to a standard for query languages: RDF Query Language (SPARQL) http://www.w3.org/TR/rdf-sparql-query/ W3C-Ontology Web Language – Query Language (OWL-QL) http://ksl.stanford.edu/projects/owl-ql/ The content of an annotation can be stored as a simple string. In order to provide reference to concepts, instances and relation types stored in a knowledge repository or to a data ontology, RDF syntax can be used: W3C-Resource Description Language http://www.w3.org/RDF/ TIPSTER provides an alternative syntax which can be used for annotations of texts: http://www.itl.nist.gov/iaui/894.02/related_projects/tipster/

3.2

Relations to other ORCHESTRA Service Specifications The Annotation Service is not designed to act as a stand-alone service; the overall purpose is to provide semantic annotation, indexing and retrieval. Therefore, the Annotation Service interacts with a number of other services as outlined in Diagram 2. Note that some of these services are specified as ORCHESTRA services, some could become ORCHESTRA services and some are outside the scope of ORCHESTRA. The utilization of semantic information that is automatically extracted from data sources (and services, what is not yet regarded in this version of the document), is designed according to an architecture for semantic annotation: Annotation Service: The Annotation Service automatically generates specific meta-information from structured information (e.g. in documents, texts) or unstructured information (e.g. databases, applications). When annotating unstructured information, the task of the annotation process is to automatically identify named entities and the relation to their semantic descriptions in an ontology and/or a knowledge base.

11/42

Specification of the Annotation Service – Context of the Annotation Service A named entity (this is a terminus from the field of Natural Language Processing and particularly Information Extraction) is something that can be referred to by a name, e.g. people, organisations, locations, dates, addresses, rivers, mountains etc. Named entities constitute an important part of the semantics of the documents they are mentioned in. The coupling of the named entity to its descriptive context (ontology, knowledge base) is termed an annotation. Structured information is assumed to be stored in a data ontology which has been established prior to the running of the annotation process. The data ontology is to be made accessible through the Ontology Access and Mapping Service. The data ontology describes the structure, the content, queries (inclusive their result structure) of the source in an ontology language. The annotation service maps these elements to the input ontology such that the structure, content and queries of the structured source can be interpreted through the input ontology. For instance, database tables could be mapped to concepts, database relations to object properties, attributes to datatype properties, database queries to ontology queries., e.g. The data ontology and the input ontology ideally should use the same ontology language (e.g. RDF for the data ontology and OWL for the input ontology). The mapping process runs automatically; it can be based on various strategies providing diverse quality of the mappings, e.g. methods of Statistical Natural Language Processing (SNLP) could support the automatic finding of the mappings. Another functionality (that is not present in traditional IE systems) is a to add descriptions of newly discovered entities to the knowledge base, i.e. it can populate the knowledge base with new instances. The service interface provides operations to establish annotations for a single document, a text string or a data ontology. The service establishes a “semantic document” for each document to be annotated; this is an additional document containing the base document (i.e. the text, data ontology etc.) wrapped as a string and the annotations as well. A sub-component of the Annotation Service handles the Information Extraction. Methods for automatic Information Extraction are implemented in components available as open source and commercial products, which are usually not based on ontologies. In order to enable a design based on available sources, the extraction itself is performed by a separate service. The IE module can provide a variety of methods based on Natural Language Processing techniques. The IE module is to be configured with the concepts of the ontology and retrieves background knowledge needed to assign text passages in the documents to concepts and instances from the knowledge base and/or configuration information. Document Indexing Service: The Document Indexing Service is an ORCHESTRA service which – similar to the Annotation Service performs automatic information extraction from unstructured base documents, in order to build inverted lists (the index) used for efficient Boolean Retrieval (this is further described in the specification of Indexing Service). An advanced version generates an index for smaller and more precise hit lists based on semantic information generated by the Annotation Service. Such an index can be used not only to display the search hits but to embed them into their semantic context (identify search hits as resources which can be related to concepts specified in the ontology and display relationships to other resources as well). Similar to the Annotation Service, the Indexing Service establishes a semantic document; moreover, a semantic document can contain both annotation and index information. Crawler Service: A service is required which maintains the set of sources to be annotated and indexed. Annotation and indexing can be performed as a background job which could be triggered at any time (e.g. at times of low load), which checks the set of sources to be annotated and indexed for changes that have been performed since the last run. Documents which have been changed are annotated and indexed again, and the old annotations and index information is deleted. Duplicate annotations and existing semantic annotations of the sources should be recognized. The Crawler Service detects sources to be annotated and/or indexed by means of configuration information, instructs the Annotation and the Index Service to perform their service operations and keeps all information about base documents, annotations and index information consistent within a document store. Note: The Crawler Service is not (yet) an ORCHESTRA service.

12/42

Specification of the Annotation Service – Context of the Annotation Service ud Ov erall Structure

Annotation Serv ice User Display in a graphical user interface annotated texts and links to their sem antic descriptions, ontology based database browsers etc.

KB User

AS User Interface

Know ledge Base Serv ice

annotateT ext Autom atically generate specific m etai nform ation for - docum ents, texts: Identification of nam ed entities and the relation to their sem antic descripti ons i n the ontology and the knowl edge base. - databases, applications: Identi fication of m appings between dom ain and data ontol ogy.

(Pre-populated) KB hol ding instances and relations between i nstances. In a sem i-autom ati c process, trusted knowledge identified by the Annotation Service Kernel is populated to the KB.

populate

Annotation Serv ice Sub-task Inform ati on Extraction: Identify nam ed entities in texts based on m ethodes of Natural Language Processing (NLP)

get/set docum ent

(from Interface) annotateDocum ent

parseOntology

Craw lerServ ice

Document Access Serv ice

Ontology Access Serv ice

get/set docum ent

(from Interface)

(from Interface)

(from Interface) get/set docum ent

Supports access to a docum ent of any type (text docum ents, data ontologies in a textual representation etc.) A docum ent can be stored l ocal ly in the Docum ent Access Servi ce's docum ent store. T he Crawler generates and stores sem antic docum ent, the Index- and the Annotation Service add generated m eta inform ati on to sem antic docum ents.

generateIndex

Document Indexing Serv ice

M aintai n a set of docum ents to be annotated and indexed.

T he Ontology Access Service provides provides program m ed access to parts of an ontology, i.e. an ontol ogy can be queried. It is assum ed that the m aintenance of ontologies itself is perform ed by dedicated tools.

(from Interface)

IS User Interface + Index Service User

(from Indexing Service)

Autom atically generate i ndex inform ation for docum ents in order to enable Boolean Retrieval. An advanced version generates an index for sm aller and m ore precise hit lists based on sem antic inform ation generated by the Annotation Service. Such an index can be used not onl y to displ ay the search hits but to em bed them into their sem antic context (identify search hits as resources whi ch can be rel ated to concepts specifi ed in the ontology and display relationships to other resources as wel l).

Index Serv ice User (from IS User Interface)

Diagram 2: User diagram of related services

13/42

Specification of the Annotation Service – Context of the Annotation Service Document Access Service: The Document Access Service supports access to documents of any type. A document can be stored locally in the Document Access Service's document store, or it can be retrieved on the fly from a source system. The Crawler Service uses the Document Access Service as its document store. The Crawler stores semantic documents generated by the Index- and/or the Annotation Service here. The semantic documents contain references to their base documents. Ontology Access and Mapping Service: The Annotation / Indexing Services generate meta-information which references definitions of concepts specified in an ontology. Therefore, these services need access to an ontology store via a dedicated service interface. The Ontology Access Service provides provides programmed access to parts of an ontology, i.e. an ontology can be queried. The building of ontologies is performed by dedicated tools outside the scope of ORCHESTRA. Knowledge base: The ontology (as can be accessed through the Ontology Access Service) builds the schema (or T-Box, Terminological Box) for the knowledge base, which is a body of formal knowledge about entities or instances (the A-Box or Assertions Box). The ontology and the knowledge base together build a system for formal knowledge reasoning and management, a semantic store. Entity knowledge in the knowledge base consists of named entity definitions (e.g. mountains, rivers, …) and relationships between them. The knowledge base can host two sorts of entity knowledge: - Pre-populated – imported or acquired otherwise from trusted sources - Automatically extracted – discovered in the process of semantic annotation or using other knowledge discovery and acquisition methods. Pre-populated entities could help the Information Extraction part of the Annotation Service to provide automatic semantic annotations. State of the art Information Extraction tools additionally allow the recognition of new (previously unknown) entities and also relations between them, such techniques can be used for the enrichment of the knowledge base. Because of the innate impreciseness of these methods, the population of the knowledge accumulated through them should be grounded on additional procedures of semi-automatic validation. As an alternative to this, the knowledge base could contain a part of trusted knowledge and a part of accumulated knowledge available only for indexing, browsing, navigation etc. T-Box and A-Box can be implemented by means of integrated service or by means of separate services. For instance, in an implementation scenario the Ontology Access and Mapping Service could implement the needed T-Box and A-Box functionality; here, a Knowledge Base Service would not be needed. User Interfaces The architecture allows for building of different front-end user interfaces which are to be seen as ORCHESTRA services but needed in order to utilize the functionality offered by the service architecture.

The Annotation Service UI allows to display by means of a graphical user interface annotated texts and links to their semantic descriptions, ontology based database browsers etc. The Knowledge Base UI has a query interface according to a standard for query languages, where prepopulated and newly discovered knowledge can be queried. The Index Service UI has a “Google-like” search interface where complete documents can be retrieved based on the index information established by the service. An enhanced version of the service offers an interface where the found documents are embedded into their semantic context.

14/42

Specification of the Annotation Service – Context of the Annotation Service Table 3 summarizes the interactions between the services described in Diagram 2:

Name

Service Type

Service Operation

Ontology Access Service

OA Info-Structure

getOntology getTBoxVocabulary getABoxVocabulary

Crawler Service

Not (yet) an ORCHESTRA Service

 annotateDocument  annotateDataOntology

Knowledge Base

Not (yet) an ORCHESTRA Service

updateModel  queryModel

Document Access Service

OA Info-Structure

setDocument  getDocument

Document Indexing Service

OA Support

Indirect relation: Common management of semantic documents via the Crawler Service

Annotation Service UI

Not an ORCHESTRA service

 annotateText

Table 3: Interaction between related services

3.3

Relations to ORCHESTRA Application Schemas The Annotation Service specification uses Basic and OA Types that are defined in the package OAS/Basic Types and OAS/OA Types of the Information Viewpoint. The Annotation Service specification defines new parameter types. These parameter types are defined the in the package OAS/OA Types/Annotation Service Types and OAS/OA Types/Annotation Exception Types of the Information Viewpoint.

3.4 3.4.1

Relations to ongoing Initiatives and related Projects GATE (General Architecture for Text Engineering) Reference: http://gate.ac.uk/ Gate is an open source toolkit for Natural Language Engineering, Information Extraction and text mining. It has been for all sorts of language processing tasks, including Information Extraction (IE) in many languages.

3.4.2

Amilcare Reference: http://nlp.shef.ac.uk/amilcare/ Amilcare is an adaptive Information Extraction (IE) system intended as support to document annotation in the Semantic Web framework. It can be used as a stand alone IE system or attached to another program via an API. Amilcare is distributed free of charge for research or educational use. A number of systems have integrated Amilcare via API, e.g. Melita (http://nlp.shef.ac.uk/melita/) or MnM (http://kmi.open.ac.uk/projects/akt/MnM/).

15/42

Specification of the Annotation Service – Context of the Annotation Service 3.4.3

KIM (Knowledge & Information Management) Reference: http://www.ontotext.com/kim/ KIM is a software platform for semantic annotation of text. It provides an IE-enhanced search technology based on the GATE platform and for query and exploration of formal knowledge. KIM is neither open-source nor free for commercial usage. However, Ontotext provides it free of charge to registered users for research and evaluation purposes. The concepts of KIM are described in http://www.ontotext.com/publications/SemAIR_ISWC169.pdf.

3.4.4

CREAM (CREAting Metadata for the Semantic Web) Reference: http://www.aifb.uni-karlsruhe.de/WBS/sha/papers/kcap2001-annotate-sub.pdf CREAM is a framework for an annotation environment that allows to construct metadata that comprises class instances and relationship instances based on an ontology. The pdf document of the above link discusses the integration of metadata crawler, inference services, document management and information extraction and describes the implementation with Ont-O-Mat, a component based, ontology-driven annotation tool.

3.5 3.5.1

Relations to ORCHESTRA User and System Requirements Fulfilment of ORCHESTRA User Requirements SP2 does not explicitly require an Annotation Service. However, SP2 and the Document of Work both require a cross-border approach, where borders could be of different nature (e.g. organisational, political, risk domain specific borders). This implicitly requires services which are handling cross-border obstacles occurring in various scenarios such as discovery and interpretation of documents, interoperability of services etc. The Annotation Service helps with the interpretation of structured and unstructured sources. It assigns textual passages in documents to definitions in domain ontologies (as defined in SP2) and thus helps with the interpretation of documents. Moreover, in conjunction with the Indexing Service, the Annotation Service helps with the discovery of features and services across borders, i.,e. a semantic retrieval based on meta-information collected by these services can be performed. The Annotation Service provides the basic means to create unique query interfaces for heterogeneous sources with structured information, e.g. databases or applications. In addition to that, the Annotation and Index Service supply meta-information to catalogues acting in a cross-border scenario. The Annotation Service mainly contributes to usability, i.e. to the end user: It should be easy for users to switch between different “information worlds”, while maintaining the semantic context at each switch. The Annotation Services helps with this task by relating these “information worlds” to semantic descriptions which are valid to all these worlds, thus facilitating common interpretation.

3.5.2

Fulfilment of the Requirements for the OSN and the OA The Annotation Service fulfils the requirements for the OSN and the OA (RM-OA Annex A.2) by adhering to the following Architectural Principles: •

Rigorous Definition and Use of Concepts and Standards: Annotations can be based on any ontology standard. The service definition abstracts from these standards.

•

Loosely Coupled Components The Annotation Service can be coupled with other semantic services in order to implement re-

16/42

Specification of the Annotation Service – Context of the Annotation Service quired application scenarios.

3.5.3

•

Technology Independence Implementation of the Annotation Service does not require any specific technologies.

•

Evolutionary Development - Design for Change: The Annotation Service generates formal meta-information which can be used for various purposes.

•

Generic Infrastructure: The Annotation Service is an OA-Service.

•

Self-describing Components: The Annotation Service offers service specific capabilities at the user interface.

Contribution to the ORCHESTRA Development Dimensions The Annotation Service contributes the following research dimensions (RM-OA Annex A.1): •

Semantic interoperability: The Annotation Service provides basic functionality for achieving semantic interoperability: it supports integrated semantic querying on data and texts in different domains and languages by construction of formal knowledge from these resources.

•

Interpretation: For the correct and integrated interpretation of structured and unstructured information located in different domains and across borders, meta-information describing this information is needed. The Annotation Service helps with the (semi-) automatic collection of this meta-information.

•

Navigation / Search Paradigms: A challenge for ORCHESTRA is to integrate navigation and search across information worlds on both the technical and on the semantic level as much as possible. The Annotation Service helps with this as – in conjunction with the Indexing Service – it provides basic functionality for semantic search.

17/42

Specification of the Annotation Service – Requirements

4 4.1

Requirements Security Requirements Currently, there are no special requirements known that go beyond the scope of the authorisation and authentication service. The Crawler Service, which maintains a set of sources to be annotated and indexed, must have proper access rights to documents it adds to the set. This could be implemented as a matter of configuration of the crawler or a matter of proper access right handling.

4.2

Reliability Requirements Automatic tools acting as background or batch jobs on a regular basis and operating on a variable amount of base documents (e.g. the Crawler Service) can produce meta-information (annotations, indices) of arbitrary size and generate enormous work load. However, the execution of these jobs must not cause impact on other resources. The “normal” operation of applications must be ensured, e.g. by running the Crawler Service and the document store on dedicated nodes within an OSN. If the Annotation Service provides strategies for population of the knowledge base, this knowledge might not be trusted as it has been generated automatically. The population process therefore has to be carefully considered; it could be necessary to make the population process semi-automatic, i.e. a human user would look at instances and relations proposed by the Annotation Service to be inserted as new knowledge into the knowledge base. The population process is highly influenced by requirements caused from the knowledge base, e.g. whether it must contain only trusted knowledge. A mechanism, that provides information about annotations to be manually reviewed before inserting them into the knowledge base can be realised in various ways, e.g. - as a functionality of the knowledge base, - as a user-defined annotation strategy - as a separate service which receives the population requests from the Annotation Service.

18/42

Specification of the Annotation Service – Conventions

5

Conventions

5.1

Abbreviations The abbreviations used in this document are defined in chapter 3.1 of the RM-OA, except for the following abbreviated terms:

5.2

•

IE

Information Extraction

•

NLP

Natural Language Processing

Terms and definitions Terms and definitions necessary for understanding this document are defined in chapter 3.2 of the RMOA Glossary, except for the following terms:

5.3

•

Information Extraction Recognition and extraction of pieces of information in large volumes of text and their representation in a structured format.

•

Natural Language Processing A range of computation methods and techniques, aiming at human-like performance of processing of oral or written texts occurring in any language, mode or genre at one or more levels of linguistic analysis.

UML Notation All diagrams that appear in this specification are presented using the Unified Modelling Language (UML) version 2.0 as the conceptual schema language.

5.4 5.4.1

Conformance Conformance to the OMM This abstract service interface specification is specified according to the rules of the ORCHESTRA Reference Model and follows the Rules for ORCHESTRA Services as described in chapter 9.2 of the RMOA. The extended service capabilities are be modelled according to the rules provided by D3.3.2.

5.4.2

Conformance of Implementation Specifications Conformance of Implementation Specifications to this Abstract Specification shall be checked using all the relevant tests and rules specified or referenced in Appendix A: Abstract Test Suite (normative).

5.5

Used parts of other documents No significant parts of other documents have been copied into this document.

19/42

Specification of the Annotation Service – Service Interface Specification

6 6.1

Service Interface Specification Specification of an OAS Profile of Parameter Types used by the Annotation Service The following diagrams give an overview about the interface and the classes of the Annotation Service.

20/42

Specification of the Annotation Service – Service Interface Specification cd Annotation Serv ice

T he Annotation Service - in its current design stage - provides operations for autom atical annotation of an unstructured source (e.g. docum ent or a text) or a data ontology which has been established from a structured source (e.g. a database). Annotations of unstructured sources are m appings of nam ed entities in the text to concepts, relations and instances of an input ontology; they are established by m eans of an Inform ation Extraction (IE). Annotations of structured sources are m appings of the input ontology to the data ontology. Sources to be annotated are identified by a docum ent descriptor. For each docum ent to be annotated, an additional docum ent - called a "sem antic docum ent" - is established which contains the annotations. T he im plem entation of the functions annotateDataOntology(...) is currently not foreseen.

A sem antic docum ent contains the content of the base docum ent, the annotations and links to the base docum ent and the input ontology. T he content of an unstructured base docum ent is wrapped as a string consisting of a set of tokens; annotations refer to a sequence of tokens (the text passage which is annotated). T he content of a structured base docum ent contains the data ontology specified textually in an ontology language.

«interface» OA Basic Service::ServiceCapabilities +


«interface» AnnotationService + + + + + + +

createSemanticDocument(OA_DocumentDescriptor) : OA_SemanticDocument annotateDocument(OA_SemanticDocument, OA_Ontology) : OA_SemanticDocument annotateDocument(OA_SemanticDocument, OA_Ontology, OA_AnnotationStrategy) : OA_SemanticDocument annotateText(OA_String, OA_Ontology) : OA_AnnotationSet annotateText(OA_String, OA_Ontology, OA_AnnotationStrategy) : OA_AnnotationSet annotateDataOntology(OA_SemanticDocument, OA_Ontology) : OA_SemanticDocument annotateDataOntology(OA_SemanticDocument, OA_Ontology, OA_AnnotationStrategy) : OA_SemanticDocument 0..1 handles

«type» Annotation Serv ice Types::OA_SemanticDocument -

nam e: OA_String annotatedResource: OA_ResourceLocator annotatedResourceContent: OA_String annotations: OA_AnnotationSet ontology: OA_Ontology

+ + + + + + + + +

getNam e() : OA_String setNam e(OA_String) : void getAnnotatedResource() : OA_ResourceLocator setAnnotatedResource(OA_ResourceLocator) : void getAnnotatedResourceContent() : OA_String setAnnotatedResourceContent(OA_String) : void getAnnotations() : OA_AnnotationSet setAnnotations(OA_AnnotationSet) : void getOntology() : OA_Ontology

«enum eration» Annotation Serv ice Types:: OA_AnnotationStrategy + + + + + + + + + +

identifyEverything: identifyConcepts: identifyInstances: identifyRelations: populateInstances: populateRelations: m apStructure: m apQueries: m apContent: defaultAnnotationStrategy:

contains 0..1

An annotation set contains the set of annotations of a docum ent which have been established through the last run of the annotateT ext, annotateDocum ent or annotateDataOntology operations.

«type» Annotation Serv ice Types::OA_AnnotationSet + + + +

addAnnotation(OA_Annotation) : void getAnnotation(Integer) : OA_Annotation rem oveAnnotation(Integer) : void toRDF() : OA_String

is com posed of 0..*

An annotation contains, am ong its ID and type, a m apping from an entity within the annotated source, which m ay be either structured or unstructured, to som e elem ent of the input ontology.

«type» Annotation Serv ice Types::OA_Annotation -

id: Integer m apping: OA_M apping

+ + + +

getId() : Integer setId(Integer) : void getM apping() : OA_M apping setM apping(OA_M apping) : void

contains

1 «type» Annotation Serv ice Types::OA_M apping A m apping consists of a m apping argum ent, which corresponds to an entity within the annotated source, and a m apping value, which represents an elem ent of the input ontology.

21/42

-

m appingArgum ent: OA_M appingArgum ent m appingValue: OA_M appingValue

+ + + +

getM appingArgum ent() : OA_M appingArgum ent setM appingArgum ent(OA_M appingArgum ent) : void getM appingValue() : OA_M appingValue setM appingValue(OA_M appingValue) : void

Specification of the Annotation Service – Service Interface Specification cd M apping «type» OA_M apping

contains

-


+ + + +


contains

1 «type» OA_M appingArgument -

type: OA_M appingArgum entT ype nam e: OA_String ontologyUrl: OA_String

+ + + + + + +

getT ype() : OA_M appingArgum entT ype setT ype(OA_M appingArgum entT ype) : void getNam e() : OA_String setNam e(OA_String) : void getOntologyUrl() : OA_String setOntologyUrl(OA_String) : void toRDF() : OA_String

1 M apping argum ent represents an elem ent of the input ontology (a concept, an instance or a property) which is being m apped to an entity within the annotated source.

M apping value represents an entity within the annotated source (text passage, docum ent or data ontology), to which an elem ent of the input ontology is being m apped.

-

type: OA_M appingArgum entT ype

+ +

getT ype() : OA_M appingArgum entT ype setT ype(OA_M appingArgum entT ype) : void

«enum eration» OA_M appingValueType + + +

«enum eration» OA_M appingArgumentType + + +

«type» OA_M appingValue

CONCEPT : INST ANCE: PROPERT Y:

22/42

DOCUM ENT : PASSAGE: DAT A_ONT OLOGY:

Specification of the Annotation Service – Service Interface Specification cd M apping Argument «type» OA_M appingArgument -

type: OA_M appingArgum entT ype nam e: OA_Stri ng ontol ogyUrl: OA_Stri ng

+ + + + + + +

getT ype() : OA_M appi ngArgum entT ype setT ype(OA_M appingArgum entT ype) : voi d getNam e() : OA_Stri ng setNam e(OA_String) : void getOntologyUrl() : OA_String setOntol ogyUrl(OA_String) : void toRDF() : OA_String

«type» OA_M AConcept

M appi ng argum ent, representing a concept of the input ontol ogy.

«type» OA_M AInstance -

ontoClass: OA_String

+ +

getOntoClass() : OA_String setOntoClass(OA_Stri ng) : voi d

M appi ng argum ent, representi ng an i nstance of the i nput ontol ogy.

«type» OA_M AProperty -

dom ain: Union range: Union

+ + + +

getDom ain() : Union setDom ai n(Uni on) : void setRange(Union) : void getRange() : Union

M appi ng argum ent, representing a property of the i nput ontology. Data type Uni on is a set of strings. T o be used to descri be dom ai n and range of a property i n case if they are represented i n the ontol ogy as uni ons of concepts. Further detai ls i n the i m pl em entati on speci fi cati on.

23/42

Specification of the Annotation Service – Service Interface Specification cd M apping Value «type» OA_M appingValue -

type: OA_M appingArgum entT ype

+ +

getT ype() : OA_M appingArgum entT ype setT ype(OA_M appingArgum entT ype) : void

«type» OA_M VPassage

«type» OA_M VDocument

-

start: OA_Node end: OA_Node text: OA_String

+ + + + + +

getStart() : OA_Node setStart(OA_Node) : void getEnd() : OA_Node setEnd(OA_Node) : void getT ext() : OA_String setT ext(OA_String) : void

«type» OA_M VDataOntology

-

url: OA_URI

-

dataOntologyExpression: OA_String

+ +

getURI() : OA_URI setURI(OA_URI) : void

+ +

getDataOntologyExpression() : OA_String setDataOntologyExpression(OA_String) : void

M apping value, representing a docum ent to be annotated (classified).

An annotation of a structured source is a reference to a nam ed elem ent within the data ontology, e.g. an RDF statem ent describing a database table, relation or attribute. T he im plem entation of this type is currently not foreseen.

2

M apping value, representing a text passsage in the input source to be annotated.

«type» OA_Node -

id: Integer offset: Long

+ + + +

getId() : Integer setId(Integer) : void getOffset() : Long setOffset(Long) : void

Node represents a text sym bol, characterized by its ID and offset. T hus, a text passage can be characterized by its start and end nodes, along with its content, called text in this context.

Diagram 3: Interface and classes of the Annotation Service

The following non basic types are used within this specification:

Name

Usage

from OAS

New

OA_MI_CapabilitiesDocument

O

OA MI Types

No

OA_GetCapabilitiesRequest

I

OA Types

No

OA_OperationRequest

I

OA Types

No

OA_NotificationCallback

I

OA Types

No

OA_OperationResponse

O

OA Types

No

24/42


OA_Notification

I

OA Types

No

OA_OperationResult

O

OA Types

No

OA_InvokeID

O

OA Types

No

OA_DocumentDescriptor

I

OA Types

No

OA_Ontology

I

OA Types

No

OA_VersionNegotiationFailed

E

OA Types/Exception Types

No

OA_UnsupportedSchema

E


No

OA_InvalidParameterValue

E


No

OA_MissingParameterValue

E


No

OA_NoApplicableCode

E


No

OA_InternalError

E


No


E


No


E


No

OA_SyncOperationUnsupported

E


No

OA_OperationFailure

E


No

OA_AsyncOperationUnsupported

E


No

OA_AbortNotPossible

E


No

OAS_InvalidStat

E


No

OA_Annotation_Capabilities

O

OA Types/Annotation Service Types

Yes

OA_SemanticDocument

I, O


Yes

OA_AnnotationStrategy

I


Yes

OA_AnnotationSet

I, O


Yes

OA_Annotation

I, O


Yes

OA_Mapping

I, O


Yes

25/42


OA_MappingArgument

I, O


Yes

OA_MappingArgumentType

I, O


Yes

OA_MAConcept

I, O


Yes

OA_MAInstance

I, O


Yes

OA_MAProperty

I, O


Yes

OA_MappingValue

I, O


Yes

OA_MappingValueType

I, O


Yes

OA_MVDataOntology

I, O


Yes

OA_MVDocument

I, O


Yes

OA_MVPassage

I, O


Yes

OA_Node

I, O


Yes

OA_OntologyParseFailed

E

OA Types/Annotation Service Exceptions

Yes

OA_UnknownDocumentFormat

E

OA Types/ Annotation Service Exceptions

Yes

OA_DocumentNotFound

E


Yes

OA_UnknownStrategy

E


Yes

Table 4: Referenced OA Types

6.2

Specification of the Service Interface Operations Operations which have been inherited from other interfaces and which do not provide extended or limited functionality to original specification are omitted in this specification. This applies to all operations that are not marked as a specialisation in Table 1. If neither the syntax nor the semantics of an inherited operation has changed, it shall not be described in this document.

6.2.1

Specification of the createSemanticDocument Operation Create the content of a semantic document from a base document identified by a document descriptor. Base documents are expected to be kept in the store of the Document Access Service. This store can be managed e.g. by a Crawler Service, who keeps track on document updates and checks for the necessity to annotate the document. In a first step prior to annotation, the Annotation Service is instructed to create a “semantic document”

26/42

Specification of the Annotation Service – Specification of the createSemanticDocument Operation associated to the base document. Semantic documents can be utilized by any service concerned with ontology based generation of meta information automatically from the base document. Semantic documents contain the content of the base document, the annotations and links to the base document and the input ontology. After creation, a semantic documents is “empty”, i.e. it does not contain any annotations and no input ontology; these are set with an annotateDocument rsp. annotateDataOntology operation. The format of the content of the base document - as stored in a semantic document - differs dependent on whether the base document is structured or unstructured: -

An unstructured base document is wrapped as a string consisting of a set of nodes; annotations refer to a sequence of nodes (the text passage which is annotated).

-

A structured base document contains the data ontology in an ontology language specification; this ontology is stored in the semantic document.

Once a semantic document has been created, it is kept in the store of the Document Access Service. When the content of the base document changes, this causes the need for a new creation of its associated semantic document. This is recognized outside the Annotation Service, e.g. by the Crawler Service. When the createSemanticDocument operation is invoked on a base document for which a semantic document already exists, the wrapped content of the base document is newly generated (the old content is deleted) and the annotations are deleted (the structure for the annotation set is initialized).

Overrides

not applicable

Preconditions

The base document has been inserted into the document store handled by the Document Access Service (this is done e.g. by the Crawler Service).

Postconditions

A semantic document attached to the base document exists and can be used to store generated annotation and index information.

Use

optional Name baseDocument

Type

Use

Description


mandatory

Identification of a document to be annotated

Receives Type

Description Contains wrapped base document rsp. a data ontology. The annotation set and the domain ontology fields are empty.

OA_SemanticDocument Returns Type

Cause

OA_UnknownDocumentFormat

The (unstructured) base document is in a format for which the wrapping of the content cannot be performed.

OA_DocumentNotFound

The source specified by the OA_DocumentDescriptor does not exist.

Throws

Table 5: Specification of the createSemanticDocument Operation

27/42

Specification of the Annotation Service – Specification of the annotateDocument Operation

6.2.2

Specification of the annotateDocument Operation The annotateDocument operation generates annotations for a given semantic document for an unstructured source, applying the given annotation strategy. The semantic document has previously been generated from a base document by means of a createSemanticDocument operation. The generated annotations are inserted into the semantic document. If the semantic document contained a non-empty annotationSet, it is completely replaced by the generated annotationSet. This makes sense e.g. in the case that the ontology has changed, but not the base document.

Overrides

Preconditions

not applicable A semantic document has been generated which contains the content of the base document wrapped as a set of nodes. A domain ontology must have been established and made accessible through the Ontology Access Service.

Postconditions

The semantic document contains the annotations generated with this operation. If the semantic document contained an annotationSet before invocation of the annotateDocument operation, this set is replaced.

Use

optional Name document

Receives

Type OA_SemanticDocument

Use

Description

required

The semantic document where the annotations should be stored.

domainOntology

OA_Ontology

required

Reference to an ontology which can be accessed by the Ontology Access Service

strategy


optional

The annotation strategy to be used.

Type

Description The semantic document with the generated annotations and the domainOntology.


Cause

OA_UnknownStrategy

The annotation strategy (specified as input) is not offered by the service.


A parse request for an ontology to the Ontology Access Service could not be accomplished.

OA_DocumentNotFound

The semantic document (specified as input) does not exist.

Throws

28/42

Specification of the Annotation Service – Specification of the annotateText Operation Table 6: Specification of the annotateDocument operation 6.2.3

Specification of the annotateText Operation The annotateText operation generates annotations for a given string content (unstructured source), applying the given annotation strategy. As opposed to the annotateDocument and annotateDataOntology operations, this operation does not utilize a semantic document. The annotationSet is delivered directly as a result parameter.

Overrides

not applicable

Preconditions

A domain ontology must have been established and made accessible through the Ontology Access Service.

Postconditions

The generated annotation set is delivered, containing annotations with references to positions in the input text.

Use

mandatory Name text

Receives

Type OA_String

Use

Description

required

The text to be annotated.

domainOntology

OA_Ontology

required


strategy


optional


Type Returns

Description The set with the generated annotations.

OA_AnnotationSet Type

Cause

OA_UnknownStrategy




Throws

Table 7: Specification of the annotateText operation 6.2.4

Specification of the annotateDataOntology Operation The annotateDataOntology operation generates annotations for a given semantic document for a structured source, applying the given annotation strategy. The semantic document has previously been generated from a base document (i.e. a data ontology which has been generated from the structured source) by means of a createSemanticDocument operation. The generated annotations are inserted into the semantic document. If the semantic document con-

29/42

Specification of the Annotation Service – Specification of the annotateDataOntology Operation tained a non-empty annotationSet, it is completely replaced by the generated annotationSet. This makes sense e.g. in the case that the ontology has changed, but not the base document.

Overrides

Preconditions

not applicable A semantic document has been generated which contains the content of the base document, i.e. a data ontology expressed in an ontology language. A domain ontology must have been established and made accessible through the Ontology Access Service.

Postconditions

The semantic document contains the annotations generated with this operation. If the semantic document contained an annotationSet before invocation of the annotateDocument operation, this set is replaced.

Use

optional Name document

Receives

Type

Use

Description

OA_SemanticDocument

required

The semantic document where the annotations should be stored.

domainOntology

OA_Ontology

required


strategy


optional


Type

Description The semantic document with the annotations and the domainOntology.


Cause

OA_UnknownStrategy




OA_DocumentNotFound

The semantic document (specified as input) does not exist.

Throws

Table 8: Specification of annotateDataOntology operation

30/42

Specification of the Annotation Service – Specification of extended Service Capabilities

6.3

Specification of extended Service Capabilities As part of ORCHESTRA D3.3.2 a meta-information schema for services is defined acting as a default OAS-MI for service capabilities. OA_MI_CapabilitiesDocument includes both the common capabilities and the service specific capabilities. While the common capabilities are further refined in D3.3.2 the specific capabilities have to be specialized in each service specification. cd Capabilities OA_MI_Property

«interface»

«type» OA_M I_Serv ice_Capabilities

ServiceCapabilities +

getCapabili ties(OA_GetCapabil itiesRequest) : OA_Capabili tiesDocument

1 0..1 «type» OA_M I_Serv ice_SpecificCapabilities «enum eration» OA_AnnotationStrategy + + + + + + + + + +

«type» OA_Annotation_Capabilites + + + +

supportedStrategi es: OA_Annotati onStrategy [0..*] supportedDocum entT ypes: OA_UnstructuredSourceT ypes [0..*] supportedDataOntologyForm ats: OA_OntologyForm at [0..*] supportedDom ainOntologyForm ats: OA_Ontol ogyForm at [1..*]

i denti fyEverything: i denti fyConcepts: i denti fyInstances: i denti fyRel ati ons: popul ateInstances: popul ateRelations: m apStructure: m apQueri es: m apContent: defaultAnnotationStrategy:

Diagram 4: Class diagram of Service Capabilites The schema for service specific capabilities defined here is explicitly divided into the following schema sections:

Section Name Annotation Service Capabilities

Section Contents The capabilities of the Annotation Service

Table 9: Sections of the service specific capabilities

Name

Definition

Data Type

Multiplicity and Use

supportedStrategies

List of supported annotation strategies

OA_annotationStrategy

[0..*]

supportedDocumentTypes

List of Mime Types which

OA_unstructuredSourceTypes

[0..*]

31/42

Specification of the Annotation Service – Specification of additional Types can be annotated supportedDataOntologyFormats

List of supported data ontology formats

OA_unstructuredSourceTypes

[0..*]

supportedDomainOntologyFormats

List of supported domain ontology formats

OA_OntologyFormat

[1..*]

Table 10: Attributes of the service specific capabilities of section Annotation Service Capabilities

6.4

Specification of additional Types This service specification defines new OA Types (see subchapters). These new OA Types will become part of the OAS “OA Types” (/subchapter Annotation Service Types) This service specification does not define any new OT Types. This service specification does not introduce any new non-orchestra Types.

6.4.1

OA_SemanticDocument A semantic document contains the content of the base document, the annotations and links to the base document and the input ontology. The content of an unstructured base document is wrapped as a string consisting of a set of tokens; annotations refer to a sequence of tokens (the text passage which is annotated). The content of a structured base document contains the data ontology specified textually in an ontology language.

32/42

Specification of the Annotation Service – Specification of additional Types cd Annotation Serv ice «type» Annotation Serv ice Types::OA_SemanticDocument -

nam e: OA_String annotatedResource: OA_ResourceLocator annotatedResourceContent: OA_String annotations: OA_AnnotationSet ontology: OA_Ontology

+ + + + + + + + +

getNam e() : OA_String setNam e(OA_String) : void getAnnotatedResource() : OA_ResourceLocator setAnnotatedResource(OA_ResourceLocator) : void getAnnotatedResourceContent() : OA_String setAnnotatedResourceContent(OA_String) : void getAnnotations() : OA_AnnotationSet setAnnotations(OA_AnnotationSet) : void getOntology() : OA_Ontology

contains 0..1 «type» Annotation Serv ice Types::OA_AnnotationSet

6.4.2

OA_AnnotationStrategy The following strategies are predefined:

Strategy name

Description

identifyConcepts

Relate - if possible - annotations to concepts of the input ontology

identifyInstances

Relate - if possible - annotations to concepts and/or instances of the input ontology

identifyRelations

Relate - if possible - annotations to relations of the input ontology

populateInstances

Identify new instances of ontology concepts in the document/text or data ontology to be annotated and populate them into the knowledge base

populateRelations

Identify new relations between instances of ontology concepts in the document/text or data ontology to be annotated and populate them into the knowledge base

mapStructure

Map structural concepts of a structured source to concepts of the input ontology

mapContent

Map instances found in a structured source to instances contained in the knowledge base.

mapQueries

Map queries specified for a structured source to queries expressed in the

33/42

Specification of the Annotation Service – Specification of additional Types (input) ontology query language. defaultAnnotationStrategy

Default strategy offered by the service. Table 11: Annotation Strategies

An implementation of the Annotation Service may implement a subset of these strategies or any other strategies. The getCapabilities operation of the Annotation Service informs clients about which strategies offers. cd Annotation Serv ice «enum eration» Annotation Serv ice Types:: OA_AnnotationStrategy + + + + + + + + + +

6.4.3

identifyEverything: identifyConcepts: identifyInstances: identifyRelations: populateInstances: populateRelations: m apStructure: m apQueries: m apContent: defaultAnnotationStrategy:

OA_ AnnotationSet An annotationSet contains the set of annotations of a document which have been established through the last run of the annotateDocument operation. cd Annotation Serv ice «type» Annotation Serv ice Types::OA_AnnotationSet + + + +

addAnnotation(OA_Annotation) : void getAnnotation(Integer) : OA_Annotation rem oveAnnotation(Integer) : void toRDF() : OA_String

is com posed of 0..* «type» Annotation Serv ice Types::OA_Annotation

34/42

Specification of the Annotation Service – Specification of additional Types 6.4.4

OA_ Annotation An annotation contains, among its ID and type, a mapping from an entity within the annotated source, which may be either structured or unstructured, to some element of the input ontology. cd Annotation Serv ice «type» Annotation Serv ice Types::OA_Annotation -

id: Integer m apping: OA_M apping

+ + + +

getId() : Integer setId(Integer) : void getM apping() : OA_M apping setM apping(OA_M apping) : void

contains

1 «type» Annotation Serv ice Types::OA_M apping

6.4.5

OA_ Mapping A mapping consists of a mapping argument, which corresponds to an entity within the annotated source, and a mapping value, which represents an element of the input ontology. cd M apping «type» OA_M apping

contains

-


+ + + +


1

contains

1

«type» OA_M appingArgument


35/42


OA_ MappingArgument Mapping argument represents an element of the input ontology (a concept, an instance or a property) which is being mapped to an entity within the annotated source. cd M apping Argument «type» OA_M appingArgument -

type: OA_M appingArgum entT ype nam e: OA_String ontologyUrl: OA_String

+ + + + + + +

getT ype() : OA_M appingArgum entT ype setT ype(OA_M appingArgum entT ype) : void getNam e() : OA_String setNam e(OA_String) : void getOntologyUrl() : OA_String setOntologyUrl(OA_String) : void toRDF() : OA_String

«type» OA_M AConcept

6.4.7

«type» OA_M AInstance

«type» OA_M AProperty

OA_ MappingArgumentType OA_MappingArgumentType is an enumeration of the subclasses of OA_MappingArgument and describes possible mapping arguments. cd M apping «enum eration» OA_M appingArgumentType + + +

6.4.8

CONCEPT : INST ANCE: PROPERT Y:

OA_ MAConcept Mapping argument, representing a concept of the input ontology. cd M apping Argument «type» OA_M AConcept

36/42


OA_ MAInstance Mapping argument, representing an instance of the input ontology. cd M apping Argument «type» OA_M AInstance -

ontoClass: OA_String

+ +

getOntoClass() : OA_String setOntoClass(OA_String) : void

6.4.10 OA_ MAProperty Mapping argument, representing a property of the input ontology. cd M apping Argument «type» OA_M AProperty -

dom ain: Union range: Union

+ + + +

getDom ain() : Union setDom ain(Union) : void setRange(Union) : void getRange() : Union

6.4.11 OA_ MappingValue Mapping value represents an entity within the annotated source (text passage, document or data ontology), to which an element of the input ontology is being mapped.

37/42

Specification of the Annotation Service – Specification of additional Types cd M apping «type» OA_M apping

contains

-


+ + + +


contains

1

1

«type» OA_M appingArgument


6.4.12 OA_ MappingValueType OA_MappingValueType is an enumeration of the subclasses of OA_MappingArgument and describes possible mapping arguments. cd M apping «enum eration» OA_M appingValueType + + +

DOCUM ENT : PASSAGE: DAT A_ONT OLOGY:

6.4.13 OA_ MVPassage Mapping value, representing a text passsage in the input source to be annotated.

38/42

Specification of the Annotation Service – Specification of additional Types cd M apping Value «type» OA_M VPassage -

start: OA_Node end: OA_Node text: OA_String

+ + + + + +

getStart() : OA_Node setStart(OA_Node) : void getEnd() : OA_Node setEnd(OA_Node) : void getT ext() : OA_String setT ext(OA_String) : void

2 «type» OA_Node

6.4.14 OA_ MVDocument Mapping value, representing a document to be annotated (classified). cd M apping Value «type» OA_M VDocument -

url: OA_URI

+ +

getURI() : OA_URI setURI(OA_URI) : void

6.4.15 OA_ MVDataOntology An annotation of a structured source is a reference to a named element within the data ontology, e.g. an RDF statement describing a database table, relation or attribute. The implementation of this type is currently not foreseen.

39/42

Specification of the Annotation Service – Known Issues and Limitations cd M apping Value «type» OA_M VDataOntology -

dataOntologyExpression: OA_String

+ +

getDataOntologyExpression() : OA_String setDataOntologyExpression(OA_String) : void

6.4.16 OA_ Node Node represents a text symbol, characterized by its ID and offset. Thus, a text passage can be characterized by its start and end nodes, along with its content, called text in this context. cd M apping Value «type» OA_Node -

id: Integer offset: Long

+ + + +

getId() : Integer setId(Integer) : void getOffset() : Long setOffset(Long) : void

6.4.17 OA_ OntologyParseFailed A parse request for an ontology to the Ontology Access Service could not be accomplished. 6.4.18 OA_ UnknownDocumentFormat The base document is in a format for which the wrapping of the content cannot be performed. 6.4.19 OA_ UnknownDocumentFormat The document specified by the OAS_DocumentDescriptor does not exist. 6.4.20 OA_ DocumentNotFound The annotation strategy (specified as input) is not offered by the service.

6.5

Known Issues and Limitations It is to be clarified whether the task of making available a structured source in a data ontology is to be performed by another Orchestra Service yet to be defined, by one of the yet specified services (e.g. Schema Mapping Service) or whether the provider of the structured source should utilize a tool that provides this functionality.

40/42

Specification of the Annotation Service – Appendix A: Abstract Test Suite (normative)

7

Appendix A: Abstract Test Suite (normative) When creating an implementation specification of the Annotation Service, the “Rules for Implementation Specifications of ORCHESTRA Services” defined in chapter 9.2.2.3 and the “Rules for the Service Mapping to a given Platform” of the RM-OA shall be obeyed. In addition, the following tests shall be performed to ensure conformance of an implementation specification to the platform-independent specification of the Annotation Service: 1. Syntactical Conformance •

Are all mandatory operations present?

•

Are all mandatory parameters present?

•

Are the operation signatures correct?

•

Are there any new operations or parameters?

2. Semantical Conformance •

Is the behaviour of the operation still the same?

Additional conformance checks that are specifically to the Annotation Service are not required.

41/42

Specification of the Annotation Service – Appendix B: UML Models (normative)

8

Appendix B: UML Models (normative) All UML models of OAS and interfaces are described in the body of this specification.

8.1

Static Model A detailed class diagram visualizing all interfaces, operations and parameters is contained in chapter 6.

8.2

Dynamic Model Prior to the first invocation of annotateDocument or annotateDataOntology, operation createSemanticDocument is to be invoked which then contains the content of the base document, an empty annotationSet and links to the base document and the input ontology. Collaboration of the Annotation Service with other ORCHESTRA and non-ORCHESTRA services is described in detail in chapter 3.2.

42/42




Specification of the Authentication Service

Revision

1/37

[1.3 / 2.2.2]

Specification of the Authentication Service – Document Control Page


Specification of the Authentication Service

Creator

Fischer, Julian

Subject


Description

This document defines an abstract and platform independent formal specification of the Authentication Service.

Publisher


Contributor

Fischer, Julian

EIG

Ma, Wenjie

EIG

Dihé, Pascal

EIG

Hofmann, Thomas

EIG

Berlinghoff, Thomas

EIG

EIG

Date

2006-01-26

Type

Text

Format

application/msword

Identifier


Source

Not applicable

Language

en-GB.

Relation

none

Coverage



D3.4.3


WP3.4


2006-06-30


2006-08-25

Audience


Version number

1.3 / 2.2.2

Date

2007-10-08

Modified by

Dihé, Pascal

EIG

Ma, Wenjie

EIG

Comments

2/37

Specification of the Authentication Service – Document Control Page

Status

Draft WP leader accepted SP leader accepted Technical supervisor accepted Quality checked Project coordinator accepted

Action requested

to be revised by partners involved in the preparation of the deliverable for approval of the WP leader for approval of the SP leader for approval of the Technical Supervisor for approval of the Quality Manager for approval of the Project Coordinator Deadline for action: 2006-07-30

3/37

Specification of the Authentication Service – Revision History


Date

Sections changed

Description st

0.9 / 2.0.4

2006-06-06

all

1 public draft release.

0.9.2/2.0.4

2006-08-03

all

Review and update of diagrams, renaming of types

0.9.3/2.0.4

2006-08-10

6.3

Capabilities added.

0.9.4/2.0.4

2006-08-11

6.5

Some notes on issues.

0.9.5/2.0.4

2006-08-11

2.2, 6

Added Transaction interface and Authentication mechanism specific types and interfaces, added type OA_Principal.

0.9.6/2.0.4

2006-08-17

all

Incorporated comments from IITB.

0.9.7/2.0.6

2006-08-22

8

Some minor changes on wording and adaptation to template-version 2.0.6.

0,9.8/2.0.6

2006-08-22

some

Edits on comments.

0.9.9/2.0.6

2006-08-25

6.2.10

Description of the verifySessionKey operation changed.

0.9.92/2.0.6

2006-08-25

most

Comments and edits commited; addition to relevant standards.

1.0 / 2.0.6

2006-08-28

none

Resolved changes.

1.1 / 2.0.6

2006-10-18

3.2, 6.1, 6.2.11

GetPrincipal operation added.

1.1.1 / 2.0.6

2006-10-30

All

Minor changes

1.1.2 / 2.0.6

2007-01-12

6.2.3,

Removed permission denied exception from login operation (before login no session information. (6.2.3) Added return type and now throws OA_PrincipalNotFoundException. (6.2.7) Return Type added. (6.2.11)

6.2.7, 6.2.11

1.2 / 2.0.6

2007-01-19

All

comments

and

commited

last

Removed Username/Password Authentication Interface. Removed coupling to Transactional Interface.

1.3 / 2.2.2

2007-10-08

All

Minor changes

4/37

Specification of the Authentication Service – Table of Contents

Table of Contents 1

Foreword..................................................................................................................................................... 8

2

Conventions ................................................................................................................................................ 9

3

4

5

6

2.1

Abbreviations ....................................................................................................................................... 9

2.2

Terms and definitions .......................................................................................................................... 9

2.3

UML Notation....................................................................................................................................... 9

2.4

Conformance ....................................................................................................................................... 9

2.4.1

Conformance to the OMM ............................................................................................................ 9

2.4.2

Conformance of Implementation Specifications........................................................................... 9

Overview and Architecture Outline ........................................................................................................... 10 3.1

Role and Scope of the Authentication Service .................................................................................. 10

3.2

Service Interface Specification Summary.......................................................................................... 10

Context of the Authentication Service ...................................................................................................... 11 4.1


4.2


4.3


4.4


4.4.1

User Management Service......................................................................................................... 12

4.4.2

Authorisation Service ................................................................................................................. 12

Requirements ........................................................................................................................................... 13 5.1


5.2


Specification of the Authentication Interface ............................................................................................ 14 6.1

Specification of an OAS Profile of Parameter Types used by the Authentication Interface.............. 15

6.2

Specification of the Operations ......................................................................................................... 16

6.2.1

Specification of the activatePrincipal Operation......................................................................... 16

6.2.2

Specification of the deactivatePrincipal Operation..................................................................... 17

6.2.3

Specification of the login Operation ........................................................................................... 18

6.2.4

Specification of the createPrincipal Operation ........................................................................... 20

6.2.5

Specification of the removePrincipal Operation ......................................................................... 21

6.2.6

Specification of the updatePrincipal Operation .......................................................................... 22

6.2.7

Specification of the addCredentials Operation........................................................................... 23

6.2.8

Specification of the updateCredentials Operation...................................................................... 24

5/37

Specification of the Authentication Service – Table of Contents 6.2.9

Specification of the removeCredentials Operation..................................................................... 25

6.2.10

Specification of the verifySessionInformation Operation ........................................................... 26

6.2.11

Specification of the getPrincipals Operation .............................................................................. 27

6.3

Specification of Parameter Types ..................................................................................................... 29

6.3.1

OA_Principal .............................................................................................................................. 29

6.3.2

OA_AuthenticatedPrincipal ........................................................................................................ 29

6.3.3

OA_Credentials .......................................................................................................................... 30

6.3.4

OA_AuthenticationSessionInformation ...................................................................................... 30

6.3.5

OA_AuthenticationFailedException............................................................................................ 31

6.3.6

OA_UsernamePrincipal.............................................................................................................. 31

6.3.7

OA_PasswordCredentials .......................................................................................................... 31

7

Specification of extended Service Capabilities......................................................................................... 33

8

Known Issues and Limitations .................................................................................................................. 35

9


10 Appendix B: UML Models (normative) ...................................................................................................... 37 10.1

XMI Model ...................................................................................................................................... 37

6/37

Specification of the Authentication Service – Tables and Diagrams

Tables Table 1: Summary of operations...................................................................................................................... 15 Table 2: Referenced OA Types ....................................................................................................................... 15 Table 3: Specification of the activatePrincipal Operation ................................................................................ 16 Table 4: Specification of the deactivatePrincipal Operation ............................................................................ 17 Table 5: Specification of the login Operation ................................................................................................... 19 Table 6: Specification of the createPrincipal Operation................................................................................... 20 Table 7: Specification of the removePrincipal Operation................................................................................. 21 Table 8: Specification of the updatePrincipal Operation.................................................................................. 22 Table 9: Specification of the addCredentials Operation .................................................................................. 23 Table 10: Specification of the updateCredentials Operation ........................................................................... 24 Table 11: Specification of the removeCredentials Operation .......................................................................... 25 Table 12: Specification of the verifySessionInformation Operation ................................................................. 27 Table 13: Specification of the getPrincipals Operation .................................................................................... 28 Table 14: Sections of the service specific capabilities..................................................................................... 33 Table 15: Attributes of the service specific capabilities of section supportedAuthenticationMechanisms ...... 34

Diagrams Diagram 1: Class Diagram of the Authentication Service................................................................................ 10 Diagram 2: Class Diagram of the Authentication Interface.............................................................................. 14 Diagram 3: Class diagram of OA_Principal ..................................................................................................... 29 Diagram 4: Class diagram of OA_AuthenticatedPrincipal ............................................................................... 30 Diagram 5: Class diagram of OA_Credentials................................................................................................. 30 Diagram 6: Class diagram of OA_AuthenticationSessionInformation ............................................................. 31 Diagram 7: Class diagram of OA_AuthenticationFailedException .................................................................. 31 Diagram 8: Class diagram of OA_UsernamePrincipal..................................................................................... 31 Diagram 9: Class diagram of OA_PasswordCredentials ................................................................................. 32 Diagram 10: Authentication Service specific capabilities ................................................................................ 33 Diagram 11: Class diagram OA_MI_AuthenticationMechanisms.................................................................... 34

7/37

Specification of the Authentication Service – Foreword

1

Foreword This document is an abstract specification of the Authentication Service and is based on the Template for the abstract Specification of ORCHESTRA Service Types version 2.2.2. It updates the specification version 2.0.6. An update was required to accommodate the changes of the new service templates. This document includes two annexes: Appendix A: Abstract Test Suite (normative) is mandatory and Appendix B: UML Models (normative) is optional.

8/37

Specification of the Authentication Service – Conventions

2

Conventions

2.1

Abbreviations The abbreviations used in this document are defined in chapter 3.1 of the Reference Model for the ORCHESTRA Architecture Version 2.0 (RM-OA).

2.2

Terms and definitions Terms and definitions necessary for understanding this document are defined in chapter 3.2 of the RMOA Glossary.

2.3


2.4 2.4.1

Conformance Conformance to the OMM This abstract service specification is specified according to the rules of the ORCHESTRA Service Metamodel (OMM-Service) and follows the rules for ORCHESTRA Services as described in chapter 9.2 of the RM-OA. The extended service capabilities are be modelled according to the RM-OA rules for OAS-MI.

2.4.2


9/37

Specification of the Authentication Service – Overview and Architecture Outline

3 3.1

Overview and Architecture Outline Role and Scope of the Authentication Service The Authentication Service verifies genuineness of principals using a set of given credentials. The authentication mechanism, that means the way of performing authentication, is up to the service implementation. Which credentials an Authentication Service needs as well as the way they are passed is specific to the authentication mechanism used. Session information returned after a successful authentication can be used to invoke services demanding authenticated principals. A service might use this information to perform authorisation requests.

3.2

Service Interface Specification Summary This service type specification of the Authentication Service is comprised of the following interface that is defined in separate interface type specification: •

The Service Capabilities Interface Type

The following interface is specified as integral part of this service in chapter 6: •

The Authentication Interface Type

cd Authentication Serv ice AuthenticationInterface ServiceCapabilities «interface» AuthenticationService + + + + + + + + + + + +

activatePrincipal(OA_Principal) : void addCredentials(OA_Credentials, OA_Principal) : void createPrincipal(OA_Principal) : void deactivatePrincipal(OA_Principal) : void getCapabilities(OA_GetCapabilitiesRequest) : OA_CapabilitiesDocument getPrincipals(OA_Query) : Sequence login(OA_Principal, OA_Credentials, OA_AuthenticationSessionInformation) : OA_AuthenticationSessionInformation removeCredentials(OA_Principal) : void removePrincipal(OA_Principal) : void updateCredentials(OA_Credentials, OA_Principal) : void updatePrincipal(OA_Principal) : void verifySessionInformation(OA_AuthenticatedPrincipal) : Boolean

Diagram 1: Class Diagram of the Authentication Service The Authentication Service is independent from specific authentication mechanisms. Authentication mechanism specific principals and credentials have to be provided by creation corresponding subtypes of OA_Principal and OA_Credentials.

10/37

Specification of the Authentication Service – Context of the Authentication Service

4 4.1

Context of the Authentication Service Relations to Standards No standard could be found that is directly applicable to this abstract specification of the Authentication Service. Nevertheless there are numerous standards in this context relevant especially for the implementation: •

IETF RFC 4120 – The Kerberos Network Authentication Service (V5)

•

IETF RFC 4158: Internet X.509 Public Key Infrastructure: Certification Path Building

•

IETF RFC 4210: Internet X.509 Public Key Infrastructure Certificate Management Protocols

•

IETF RFC 4211: Internet X.509 Public Key Infrastructure Certificate Request Message Format (CRMF)

•

IETF RFC 4325: Internet X.509 Public Key Infrastructure Authority Information Access Certificate Revocation List (CRL) Extension

•

IETF RFC 4386: Internet X.509 Public Key Infrastructure Repository Locator Service

•

IETF RFC 4387: Internet X.509 Public Key Infrastructure Operational Protocols: Certificate Store Access via HTTP

•

Java.sun.com Java Authentication and Authorization Service (JAAS) (part of Java 2 SDK 1.4). http://java.sun.com/products/jaas/

•

OASIS Digital Signature Services (DSS) TC http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dss

•

OASIS Public Key Infrastructure (PKI) TC http://www.oasis-open.org/committees/workgroup.php?wg_abbrev=pki

•

OASIS Web Services Secure Exchange (WS-SX) TC http://www.oasis-open.org/committees/workgroup.php?wg_abbrev=ws-sx

•

OASIS Web Services Security (WSS) TC http://www.oasis-open.org/committees/workgroup.php?wg_abbrev=wss

The Authentication Service currently does not qualify for the contribution to a standard.

4.2

Relations to ongoing Initiatives and related Projects The Authentication Service has no immediate relation to ongoing projects.

4.3

Relations to ORCHESTRA Application Schemas The Authentication Interface Type Specification that is specified as integral part of this Service Type Specification uses Basic and OA Types that are defined in the package OAS/Basic Types, OAS/OA Types and OAS-MI/OA-MI Types of the Information Viewpoint. The Authentication Interface Type Specification that is specified as integral part of this Service Type Specification defines new parameter types. These parameter types are defined the in the package OAS/OA Types/«Application Schema» Authentication Service Exceptions, OAS/OA Types/ «Application Schema» Authentication Service Types of the Information Viewpoint.

11/37

Specification of the Authentication Service – Context of the Authentication Service

4.4 4.4.1

Relations to other ORCHESTRA Service Specifications User Management Service In order to authenticate groups an Authentication Service instance may ask the responsible User Management Service instance whether the given principal is a member of the given group.

4.4.2

Authorisation Service An Authorisation Service uses principals created in Authentication Services to manage permissions. Permissions are bound to principals. Whether these permissions are directly bound to principals or indirectly via additional associations like principal-role and role-permission depends on the implementation of the Authorisation Service. Independent from the way permissions and principals are related, an Authorisation Service is able to retrieve the permissions for a given principal.

12/37

Specification of the Authentication Service – Requirements

5 5.1

Requirements Security Requirements In order to provide a reliable and secure Authentication Service the following requirements beyond the scope of this specification have to be met: •

•

5.2

Session Information needs to be safe. o

A service must be able to check whether some given session information is genuine

o

Session information should have limited lifetime

Authentication Mechanisms needs to be trustworthy. o

Once an authentication mechanism is broken the resulting session information can obviously be misused

o

Especially for username/password authentication the password should not be transmitted in clear text. Encrypted communication channels are strongly recommended.

Reliability Requirements In order to ensure consistency among the Authentication, the Authorisation and the User Management Service, principals should be deleted within transactions. If transactions would not be used, no one could guarantee that not only the principal in the authentication service is deleted, but also each reference (e.g. from subjects or groups) to it too.

13/37

Specification of the Authentication Service – Specification of the Authentication Interface

6

Specification of the Authentication Interface cd Authentication Interface «interface» AuthenticationInterface + + + + + + + + + + +

activatePrincipal(OA_Principal) : void addCredentials(OA_Credentials, OA_Principal) : void createPrincipal(OA_Principal) : void deactivatePrincipal(OA_Principal) : void getPrincipals(OA_Query) : Sequence login(OA_Principal, OA_Credentials, OA_AuthenticationSessionInformation) : OA_AuthenticationSessionInformation removeCredentials(OA_Principal) : void removePrincipal(OA_Principal) : void updateCredentials(OA_Credentials, OA_Principal) : void updatePrincipal(OA_Principal) : void verifySessionInformation(OA_AuthenticatedPrincipal) : Boolean

Diagram 2: Class Diagram of the Authentication Interface The Authentication Interface defines the following operations:

Operation Name login

createPrincipal

Description Initiates the validation of a certain principal for given credentials. Creates a new principal. The principal representation is specific to the authentication mechanism used. For a username/password authentication the principal contains at least a username.

removePrincipal

Deletes an existing principal.

updatePrincipal

Updates an existing principal.

addCredentials

Adds credentials to a certain principals. Credentials are specific to the authentication mechanism used. For a username/password authentication credentials is a password.

updateCredentials

Updates credentials for a certain principal.

removeCredentials

Removes credentials from a certain principal. After credentials are removed it is no longer possible to authenticate this principal.

deactivatePrincipal

Deactivates a principal without removing it.

activatePrincipal

Activates an existing but deactivated principal.

verifySessionInformation

The operation verifySessionInformation determines whether the given session-information is valid.

getPrincipals

Retrieves a list of principals matching the given query.

14/37

Specification of the Authentication Service – Specification of the Authentication Interface Table 1: Summary of operations

6.1

Specification of an OAS Profile of Parameter Types used by the Authentication Interface The following non basic types are used within this specification:

Name

Usage

from OAS

New

OA_Credentials

I

OA Types

Yes

OA_PasswordCredentials

I

OA Types

Yes

OA_Principal

I

OA Types

No

OA_UsernamePrincipal

I

OA Types

Yes

OA_AuthenticationSessionInformation

O

OA Types

Yes

OA_FeatureCollection

O

OA Types

No

OA_CapabilitiesDocument

O

OA MI Types

No


I

OA Types

No

OA_Query

I

OA Types

No


E


No


E


No


E


No


E


No

OA_NoApplicableCode

E


No

OA_InternalError

E


No

OA_NoSuchPrincipalException

E


No

OA_PrincipalNotFoundException

E


No

OA_AuthenticationFailedException

E


Yes

OA_PermissionDeniedException

E


No


15/37


6.2 6.2.1

Specification of the Operations Specification of the activatePrincipal Operation The optional activatePrincipal operation activates an existing principal. Only active principals can be authenticated. The signatures of the operation is void activatePrincipal (OA_Principal) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PrincipalNotFoundException, OA_PermissionDeniedException

Overrides

Not applicable

Preconditions

None

Post conditions

None

Use

optional

Receives

Name

Type

principal Returns

OA_Principal

mandatory

Type Not applicable

Throws

Use

Description Principal to be activated. Description

Not applicable

Type

Cause


Operation request contains an invalid parameter value. Return the name of the parameter with invalid value.


Operation request does not include a parameter value. Return the name of the missing parameter

OA_NoApplicableCode

No other basic or service-specific exception type applies.

OA_InternalError

A problem occurred in the runtime environment (e.g. out of memory)


The principal to act on cannot be found.


The service requestor does not have permissions needed to perform the requested operation.

Table 3: Specification of the activatePrincipal Operation

16/37


6.2.2

Specification of the deactivatePrincipal Operation The optional deactivatePrincipal operation deactivates an existing principal. Only active principals can be authenticated. The signatures of the operation is void deactivatePrincipal ( OA_Principal ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PrincipalNotFoundException, OA_PermissionDeniedException

Overrides

Not applicable

Preconditions

None

Post conditions

None

Use

optional

Receives

Name

Type

principal Returns

OA_Principal

mandatory

Type Not applicable

Throws

Use

Description Principal to be deactivated. Description

Not applicable

Type

Cause





OA_NoApplicableCode


OA_InternalError






Table 4: Specification of the deactivatePrincipal Operation

17/37


6.2.3

Specification of the login Operation The mandatory login operation initiates the validation of a certain principal for given credentials. The mechanism to provide this principal and the corresponding credentials is provided by an authenticationmechanism dependent interface (e.g. the interface UsernamePasswordAuthentication. The signatures of the operation is OA_AuthenticationSessionInformation login ( OA_Principal, OA_Credentials, OA_SessionInformation ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_AuthenticationFailedException

Overrides

Not applicable

Preconditions

None

Post conditions

None

Use

mandatory

Receives

Name principal

crendential

sessionInformation

Returns

Type OA_Principal

OA_Credentials

OA_SessionInformation

Type

Description

mandatory

Principal which is authenticated.

mandatory

Credentials which is to use in order to authenticate the given principal.

optional

The newly authenticated principal is to added to this sessioninformation. Description

OA_AuthenticationSessionInformation Throws

Use

Type

Session Information that can be used to invoke services demanding authenticated principals. Cause





OA_NoApplicableCode


OA_InternalError


18/37


OA_AuthenticationFailedException

Authentication was not successful.

Table 5: Specification of the login Operation There are two alternative scenarios for the login-operation: a) session-information available Session-information is available if the requestor already has an authenticated principal and wants to authenticate another one. b) no session-information available This is the case if the requestor has no authenticated principal and hence no sessioninformation yet. Consequently the session-information is an optional parameter.

19/37


6.2.4

Specification of the createPrincipal Operation The mandatory createPrincipal operation creates a new principal. The parameter is a principal representation that is specific to the used authentication mechanism. For a username/password authentication the principal contains at least a username. The signatures of the operation is void createPrincipal ( OA_Principal ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PermissionDeniedException

Overrides

Not applicable

Preconditions

None

Post conditions

None

Use

mandatory

Receives

Name

Type

principal Returns

OA_Principal

mandatory

Type Not applicable

Throws

Use

Description Principal to be created, e.g. a username for a username/password authentication. Description

Not applicable

Type

Cause





OA_NoApplicableCode


OA_InternalError




Table 6: Specification of the createPrincipal Operation

20/37


6.2.5

Specification of the removePrincipal Operation The mandatory removePrincipal operation deletes an existing principal. The principal representation is specific to the authentication mechanism used. To keep consistency the deletion of a principal should be performed within a transaction. In this transaction all references to the principal should also get deleted (e.g. group memberships, …). The signatures of the operation is void removePrincipal ( OA_Principal ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PrincipalNotFoundException, OA_PermissionDeniedException

Overrides

Not applicable

Preconditions

None

Post conditions

None

Use

mandatory

Receives

Name

Type

principal Returns

OA_Principal

mandatory

Type Not applicable

Throws

Use

Description Principal to be deleted.. Description

Not applicable

Type

Cause





OA_NoApplicableCode


OA_InternalError






Table 7: Specification of the removePrincipal Operation

21/37


6.2.6

Specification of the updatePrincipal Operation The mandatory updatePrincipal operation updates an existing principal. The signatures of the operation is void updatePrincipal ( OA_Principal ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PrincipalNotFoundException, OA_PermissionDeniedException

Overrides

Not applicable

Preconditions

None

Post conditions

None

Use

mandatory

Receives

Name

Type

principal Returns

OA_Principal

Description

mandatory

Principal to be updated including the changed attributes, e.g. new username.

Type Not applicable

Throws

Use

Description Not applicable

Type

Cause





OA_NoApplicableCode


OA_InternalError






Table 8: Specification of the updatePrincipal Operation

22/37


6.2.7

Specification of the addCredentials Operation The mandatory addCredentials operation adds credentials to a certain principals. Credentials are specific to the authentication mechanism used. For a username/password authentication credentials contain at least a password. The signatures of the operation is OA_Credentials addCredentials ( OA_Principal, OA_Credentials ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PrincipalNotFoundException, OA_PermissionDeniedException

Overrides

Not applicable

Preconditions

None

Post conditions

None

Use

mandatory

Receives

Name

Use

Description

principal

OA_Principal

mandatory

Principal to whom credentials should be added.

credentials

OA_Credentials

mandatory

Credentials to be added to the given principal.

Returns

Type credentials

Throws

Type

OA_Credentials

Description mandatory

Type

Credentials to be added to the given principal. Cause





OA_NoApplicableCode


OA_InternalError






Table 9: Specification of the addCredentials Operation

23/37


6.2.8

Specification of the updateCredentials Operation The mandatory updateCredentials operation updates credentials for a certain principal. The signatures of the operation is void updateCredentials ( OA_Principal, OA_Credentials ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PermissionDeniedException

Overrides

Not applicable

Preconditions

None

Post conditions

None

Use

mandatory

Receives

Returns

Name

Type

Description

principal

OA_Principal

mandatory

Principal whose credentials should be updated.

credentials

OA_Credentials

mandatory

Updated credentials.

Type Not applicable

Throws

Use

Description Not applicable

Type

Cause





OA_NoApplicableCode


OA_InternalError




Table 10: Specification of the updateCredentials Operation

24/37


6.2.9

Specification of the removeCredentials Operation The optional removeCredentials operation removes credentials from a given principal. The signatures of the operation is void removeCredentials ( OA_Principal ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PrincipalNotFoundException, OA_PermissionDeniedException

Overrides

Not applicable

Preconditions

None

Post conditions

None

Use

optional

Receives

Name

Type

principal Returns

OA_Principal

mandatory

Type Not applicable

Throws

Use

Description Principal whose credentials should be deleted. Description

Not applicable

Type

Cause





OA_NoApplicableCode


OA_InternalError






Table 11: Specification of the removeCredentials Operation

25/37


6.2.10 Specification of the verifySessionInformation Operation The verifySessionInformation operation is used by a service to verify given session information for validity. An Authentication Service is able to verify authenticated principals who have been authenticated by himself. This might be done by comparing the session id given in the session information with the session id stored by Authentication Service. Per default, an Authentication Service is not responsible for verifying foreign sessions created by other Authentication Services. The signatures of the operation is Boolean verifySessionInformation ( OA_AuthenticatedPrincipal ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PermissionDeniedException

Overrides

Not applicable

Preconditions

None

Post conditions

None

Use

optional

Receives

Name

Type

principal

Returns

OA_AuthenticatedPrincipal

Type

Description

mandatory

This parameter represents the principal for which the authenticationstate is requested.

Description True if the principal is authenticated, else false.

Boolean Throws

Use

Type

Cause





OA_NoApplicableCode

No other basic or servicespecific exception type applies.

26/37


OA_InternalError




Table 12: Specification of the verifySessionInformation Operation

6.2.11 Specification of the getPrincipals Operation The mandatory getPrincipals operation allows the retrieval of a list of principals specified by a given query. The signatures of the operation is Sequence getPrincipals ( OA_Query ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PermissionDeniedException

Overrides

Not applicable

Preconditions

None

Post conditions

None

Use

mandatory

Receives

Name

query

Returns

Type

OA_Query

optional

Type Sequence

Throws

Use

Description Query specifying the principals to be retrieved. If no query is given, all principals of the OSI will be returned. Description

Set of principals matching the specified query.

Type

Cause





OA_NoApplicableCode


27/37


OA_InternalError




Table 13: Specification of the getPrincipals Operation

28/37

Specification of the Authentication Service – Specification of Parameter Types

6.3

Specification of Parameter Types This interface specification defines new OA Types. These new OA Types will become part of the OAS “OA Types”. This interface specification does not define any new OT Types. This interface specification does not introduce any new non-ORCHESTRA Types.

6.3.1

OA_Principal The abstract type OA_Principal defines the attributes each concrete principal has. cd Authorisation Serv ice Types «type» OA_Principal + + + +

active: boolean id: Integer origin: OA_OSI_Identifier refGroups: Sequence refSubject: OA_Subject [0..1]

Diagram 3: Class diagram of OA_Principal The attributes:

6.3.2

•

id – used to identify the principal within this Authentication Service instance.

•

origin – identifies the Authentication Service this principal can be/has been authenticated.

•

refSubject – A principal is assigned to at most one OA_Subject. If the principal gets deleted, the subject must be informed about that deletion or it still refers to a non-existing principal. Therefore this reference is introduced.

•

refGroups – These references to groups are introduced, so that this principal can also be removed from groups in case it is deleted.

OA_AuthenticatedPrincipal The OA_AuthenticatedPrincipal extends OA_Principal to support authentication mechanisms using session ids.

29/37

Specification of the Authentication Service – Specification of Parameter Types cd Authorisation Serv ice Types «type» OA_Principal + + + +

active: boolean id: Integer origin: OA_OSI_Identifier refGroups: Sequence refSubject: OA_Subject [0..1]

«type» OA_AuthenticatedPrincipal + +

sessionId: CharacterString validityEnd: DateTime

Diagram 4: Class diagram of OA_AuthenticatedPrincipal Attributes:

6.3.3

•

sessionId: The session id is given after a principal has been successfully authenticated. A given session id can be used to ask the corresponding Authentication Service whether the session is valid.

•

validityEnd: Indicates when the session expires.

OA_Credentials The OA_Credentials type represents the part of the authentication secret known to the Authentication Service. OA_Credentials is an abstract type and thus not used directly. Instead, concrete credential types need to inherit from OA_Credentials. cd Authentication S... «type» OA_Credentials +

id: Integer

Diagram 5: Class diagram of OA_Credentials 6.3.4

OA_AuthenticationSessionInformation The OA_AuthenticationSessionInformation type represents session information generated by an Authentication Service after a subject has successfully authenticated one or more principals. The authenticatedPrincipals attribute contains a list of successfully authenticated principals represented by OA_Principal.

30/37

Specification of the Authentication Service – Specification of Parameter Types cd Authorisation Serv ice «type» OA_AuthenticationSessionInformation +

authenticatedPrincipals: Sequence

Diagram 6: Class diagram of OA_AuthenticationSessionInformation 6.3.5

OA_AuthenticationFailedException The OA_AuthenticationFailedException is thrown if some errors have occurred during authentication. cd Authentication Serv ice Exceptions «type» OA_AbstractException + +

cause: OA_AbstractException [0..1] message: LocalisedCharacterString

+

getMessage(LanguageCode) : LocalisedCharacterString

«type» OA_AuthenticationFailedException

Diagram 7: Class diagram of OA_AuthenticationFailedException 6.3.6

OA_UsernamePrincipal The OA_UsernamePrincipal type are a principals specialised to be used for username-password authentication. Only the username is added as an attribute.

cd Authentication Serv ice «type» OA_UsernamePrincipal +

usernam e: CharacterString

«type» OA_Principal + + + +

id: Integer origin: OA_OSI_Identifier refSubject: OA_Subject [0..1] refGroups: Sequence

Diagram 8: Class diagram of OA_UsernamePrincipal 6.3.7

OA_PasswordCredentials The OA_PasswordCredentials type represents credentials as needed e.g. for a username/password authentication. The password attribute contains as the name implies the principal’s password. The password should be encrypted.

31/37

Specification of the Authentication Service – Specification of Parameter Types cd Authentication Serv ice «type» OA_Passw ordCredentials

«type» OA_Credentials +

id: Integer

+

password: CharacterString

Diagram 9: Class diagram of OA_PasswordCredentials

32/37


7

Specification of extended Service Capabilities As part of ORCHESTRA D3.3.2 a meta-information schema for services is defined acting as a default OAS-MI for service capabilities. OA_MI_CapabilitiesDocument includes both the common capabilities and the service specific capabilities. While the common capabilities are defined in the specification of the Service Capabilities Interface, the specific capabilities have to be specialized in each service specification.

cd Authentication Serv ice Capabilities «type» OA_M I_Serv ice_SpecificCapabilities

«type» OA_M I_AuthenticationServ iceCapabilities +

supportedAuthenticationM echanism s: OA_M I_AuthenticationM echanism [1..*]

OA_MI_Service_InvocationBasic «type» OA_M I_AuthenticationM echanism +

nam e: CharacterString

Diagram 10: Authentication Service specific capabilities

The schema for service specific capabilities defined here is explicitly divided into the following schema sections:

Section Name supportedAuthenticationMechanisms

Section Contents This section describes the supported authenticationmechanism specific interfaces of this instance of the Authentication Service.

Table 14: Sections of the service specific capabilities Support of an authentication-mechanism means, that there exists an abstract interface specification for that authentication-mechanism, so that it is possible to reference to that specification via the OA_MI_AuthenticationMechanism attribute.

33/37


Name

Definition The name has to be unique among the listed authentication mechanisms.

name


Data Type

CharacterString

0, 1 / mandatory

Further descriptions of authentication-mechanisms may be added when needed. Table 15: Attributes of the service specific capabilities of section supportedAuthenticationMechanisms The type OA_MI_AuthenticationMechanisms is a specialisation of OA_MI_Service_Invocation, the latter is described in detail in D3.3.2. cd Authentication Serv ice Capabilities «type» OA_M I_AuthenticationM echanism +

nam e: CharacterString

Used meta-information «type» OA_M I_Serv ice_Inv ocationBasic

+operations 1..* «type» OA_M I_OperationParameter

«type» OA_M I_Operation + + + + +

accessPoints: OA_M I_AccessPoint [0..n] description: LocalisedCharacterString [0..1] exceptions: OA_M I_OperationException [0..n] nam e: CharacterString param eters: OA_M I_OperationParam eter [0..n] {ordered}

+ + + + + + +

allowedValues: CharacterString [0..n] description: LocalisedCharacterString [0..1] direction: OA_M I_Param eterDirection nam e: CharacterString optionality: Boolean repeatability: Boolean valueT ype: CharacterString

«type» OA_M I_OperationException + +

description: LocalisedCharacterString [0..1] type: CharacterString

Diagram 11: Class diagram OA_MI_AuthenticationMechanisms

34/37


8

Known Issues and Limitations The specification of the Authentication Service is elaborated in a way to provide high independence from technologies. Therefore this specification’s degree of abstraction is rather high, to facilitate the approach towards this specification examples for technology dependent concretisations have been added at some points, e.g. the types: OA_UsernamePrincipal and OA_PasswordCredentials for a usernamepassword authentication-mechanism. Besides of concrete extensions the direct application of this specification is to use it as the foundation/basis for concrete application-schemas and applications.

35/37

Specification of the Authentication Service – Appendix A: Abstract Test Suite (normative)

9

Appendix A: Abstract Test Suite (normative) When creating an implementation specification of the Authentication Service, the “Rules for Implementation Specifications of ORCHESTRA Services” defined in chapter 9.2.2.3 and the “Rules for the Service Mapping to a given Platform” of the RM-OA shall be obeyed. In addition, the following tests shall be performed to ensure conformance of an implementation specification to the platform-independent specification of the Authentication Service: 1. Syntactical Conformance •


•


•


•


2. Semantic Conformance •


Additional conformance checks that are specifically to the Authentication Service are not required.

36/37

Specification of the Authentication Service – Appendix B: UML Models (normative)

10

Appendix B: UML Models (normative)

10.1 XMI Model The XMI Models of this interface specification can be downloaded from the OGC Portal under the following URL: https://portal.opengeospatial.org/index.php?m=projects&a=view&project_id=140&tab=2&artifact_id=222 42 The XMI Model contains all parameters required by this service including those data types and exceptions inherited or reused from other interface and service specifications.

37/37




Specification of the Authorisation Service

Revision

1/40

[1.2 / 2.2.2]

Specification of the Authorisation Service – Document Control Page


Specification of the Authorisation Service

Creator

Fischer, Julian

Subject


Description

This document defines an abstract and platform independent formal specification of the Authorisation Service.

Publisher


Contributor

Julian Fischer

EIG

Thomas Hofmann

EIG

Thomas Berlinghoff

EIG

Wenjie Ma

EIG

EIG

Date

2006-06-13

Type

Text

Format

application/msword

Identifier

The HTTP address in OGC Portal

Source

Not applicable

Language

en-GB.

Relation

none

Coverage



D3.4.3


WP3.4


2006-07-30


2006-07-30

Audience


Version number

1.2 / 2.2.2

Date

2007-10-08

Modified by

Wenjie Ma

EIG

Comments Status

Draft WP leader accepted

2/40

Specification of the Authorisation Service – Document Control Page

SP leader accepted Technical supervisor accepted Quality checked Project coordinator accepted Action requested


3/40

Specification of the Authorisation Service – Revision History


Date

Sections changed

Description st

0.9 / 2.0.4

2006-07-25

All

1 public draft release.

0.9.3/ 2.0.4

2006-08-03

Some

Update of diagrams.

0.9.4 / 2.0.4

2006-08-08

All

Incorporate comments Reordered description of Interfaces

0.9.5 / 2.0.4

2006-08-10

8.3

Added capabilities.

0.9.6 / 2.0.4

2006-08-16

All

Updated diagrams, comments and their resolution

0.9.7 / 2.0.6

2006-08-17

None

Corrected stated template-version

0.9.8 / 2.0.6

2006-08-28

None

Accepted/rejected changes, cleared comments.

0.9.9 / 2.0.6

2006-09-07

8.4.4 OA_AuthorisationContext

Class diagram updated.

1.0 / 2.0.6

2006-10-18

All

getPermissions operation added.

1.0.1 / 2.0.6

2006-10-31

All

Minor changes

1.0.2 / 2.0.6

2007-01-10

All

Minor changes

1.0.3 / 2.0.6

2007-01-15

All

Incorporated comments from T. Berlinghoff.

1.1 / 2.0.6

2006-01-22

All

Updated return types of operations return arrays.

1.2 / 2.2.2

2007-10-08

all

Update of new service template

4/40

Specification of the Authorisation Service – Table of Contents

Table of Contents 1

Foreword..................................................................................................................................................... 8

2

Conventions ................................................................................................................................................ 9

3

4

2.1

Abbreviations ....................................................................................................................................... 9

2.2


2.3

UML Notation....................................................................................................................................... 9

2.4

Conformance ....................................................................................................................................... 9

2.4.1


2.4.2



Role and Scope of the Authorisation Service.................................................................................... 10

3.2


Context of the Authorisation Service ........................................................................................................ 12 4.1


4.2


4.3


4.4


4.4.1 5

6

Authentication Service................................................................................................................ 12

Requirements ........................................................................................................................................... 13 5.1


5.2


Specification of the Authorisation Interface .............................................................................................. 14 6.1

Specification of an OAS Profile of Parameter Types used by the Authorisation Interface ............... 14

6.2


6.2.1

Specification of the authorise Operation .................................................................................... 15

7

Specification of Authorisation Administration Interface ............................................................................ 17

8

Specification of Permission Administration Interface ............................................................................... 18 8.1 Specification of an OAS Profile of Parameter Types used by the Permission Administration Interface........................................................................................................................................................ 18 8.2


8.2.1

Specification of the assignPermissionToPrincipal Operation..................................................... 19

8.2.2

Specification of the unassignPermissionFromPrincipal Operation ............................................ 20

5/40

Specification of the Authorisation Service – Table of Contents 8.2.3 9

Specification of the getPermissions Operation .......................................................................... 21

Rbac Authorisation Administration Interface Specification....................................................................... 23 9.1 Specification of an OAS Profile of Parameter Types used by the Rbac Authorisation Administration Interface........................................................................................................................................................ 23 9.2


9.2.1

Specification of the createRole Operation.................................................................................. 24

9.2.2

Specification of the deleteRole Operation.................................................................................. 25

9.2.3

Specification of the getRoles Operation..................................................................................... 26

9.2.4

Specification of the updateRole Operation ................................................................................ 27

9.2.5

Specification of the assignPermissionToRole Operation ........................................................... 28

9.2.6

Specification of the unassignPermissionFromRole Operation................................................... 29

9.2.7

Specification of the assignRoleToPrincipal Operation ............................................................... 30

9.2.8

Specification of the unassignRoleFromPrincipal Operation....................................................... 31

9.3


9.3.1

OA_Permission .......................................................................................................................... 33

9.3.2

OA_OperationPermission .......................................................................................................... 33

9.3.3

OA_Role ..................................................................................................................................... 34

9.3.4

OA_AuthorisationContext........................................................................................................... 35

9.3.5

OA_KeyValueAuthorisationContext ........................................................................................... 35

9.3.6

OA_RoleNotFoundException ..................................................................................................... 35

9.3.7

OA_PermissionDeniedException ............................................................................................... 35

9.3.8

OA_PermissionNotFoundException........................................................................................... 35

9.3.9

OA_AssociationAlreadyExistsException .................................................................................... 35

9.3.10

OA_NoSuchAssociationException ............................................................................................. 36

10 Specification of extended Service Capabilities......................................................................................... 37 11 Appendix A: Abstract Test Suite (normative)............................................................................................ 39 12 Appendix B: UML Models (normative) ...................................................................................................... 40 12.1

XMI Model ...................................................................................................................................... 40

6/40

Specification of the Authorisation Service – Tables and Diagrams

Tables Table 1: Summary of operations...................................................................................................................... 14 Table 2: Referenced OA Types ....................................................................................................................... 15 Table 3: Specification of the authorise Operation............................................................................................ 16 Table 4: Summary of Operations ..................................................................................................................... 18 Table 5: Referenced OA Types ....................................................................................................................... 19 Table 6: Specification of the assignPermissionToPrincipal Operation ............................................................ 20 Table 7: Specification of the unassignPermissionFromPrincipal Operation .................................................... 21 Table 8: Specification of the getPermissions Operation .................................................................................. 22 Table 9: Summary of Operations ..................................................................................................................... 23 Table 10: Referenced OA Types ..................................................................................................................... 24 Table 11: Specification of the createRole Operation ....................................................................................... 25 Table 12: Specification of the deleteRole Operation ....................................................................................... 26 Table 13: Specification of the getRoles Operation .......................................................................................... 27 Table 14: Specification of the updateRole Operation ...................................................................................... 28 Table 15: Specification of the assignPermissionToRole Operation................................................................. 29 Table 16: Specification of the unassignPermissionFromRole Operation ........................................................ 30 Table 17: Specification of the assignRoleToPrincipal Operation..................................................................... 31 Table 18: Specification of the unassignRoleFromPrincipal Operation ............................................................ 32 Table 19: Sections of the service specific capabilities..................................................................................... 37 Table 20: Attributes of the service specific capabilities of section supportedPermissionTypes ...................... 38 Table 21: Attributes of the service specific capabilities of section supportedAuthorisationParadigms ........... 38

Diagrams Diagram 1: Class Diagram of the Authorisation Service.................................................................................. 11 Diagram 2: Class Diagram of the Authorisation Interface................................................................................ 14 Diagram 3: Class Diagram of the Authorisation Administration Interface, including two specialisations for Permission and Role-based Authorisation Administration ....................................................................... 17 Diagram 4: Class Diagram of the Permission Administration Interface........................................................... 18 Diagram 5: Class Diagram of the Rbac Authorisation Administration Interface .............................................. 23 Diagram 6: Class diagram of OA_Permission ................................................................................................. 33 Diagram 7: Class diagram of OA_OperationPermission ................................................................................. 33 Diagram 8: Class diagram of OA_Role............................................................................................................ 34 Diagram 9: Class diagram of OA_AuthorisationContext ................................................................................. 35 Diagram 10: New exceptions in the Authorisation Service .............................................................................. 36 Diagram 11: Authorisation Service specific capabilities .................................................................................. 37 Diagram 12: Meta-information necessary for time-slice permission................................................................ 38

7/40

Specification of the Authorisation Service – Foreword

1

Foreword This document is an abstract specification of the Authorisation Service and is based on the Template for the abstract Specification of ORCHESTRA Services Types version 2.2.2. It updates the specification version 2.0.6. An update was required to accommodate the changes of the new service templates. This document includes two annexes: Appendix A: Abstract Test Suite (normative) is mandatory and Appendix B: UML Models (normative) is optional. In addition to the abstract specification of the Authorisation Service it is essential to study UAA Guidelines. Especially core statements give further instruction for service designers and service developers. The UAA Guidelines should be read before reading the abstract specifications.

8/40

Specification of the Authorisation Service – Conventions

2

Conventions

2.1


2.2


2.3


2.4 2.4.1


2.4.2


9/40

Specification of the Authorisation Service – Overview and Architecture Outline

3 3.1

Overview and Architecture Outline Role and Scope of the Authorisation Service The Authorisation Service decides whether some principal (user or service) is authorised to access a certain resource. In response to a service request a service invokes its Authorisation Service in order to retrieve an authorisation decision. The authorisation decision is based upon the authorisation context passed by the service. This context comprises the authenticated principals of the service requestor as well as individual state variables of the service. The authorisation decision is provided as a compliance value indicating how to treat the request (e.g. permit or deny).

Each Authorisation Service offers two interfaces 1. Authorisation Interface 2. Administration Interface The authorisation interface includes all operations which are common to all Authorisation Services regardless to their underlying paradigms. The administration interface is specific to the underlying paradigm, e.g. supporting role management and thus may vary for different Authorisation Service implementations. In the following a representative administration interface for a role based Authorisation Service is presented.

3.2

Service Interface Specification Summary This service type specification of the Authorisation Service is comprised of the following interface that is defined in separate interface type specification: •


The following interfaces are specified as integral part of this service in chapter 6: •

The Authentication Interface Type

•

Authorisation Administration Interface Type

•

Permission Administration Interface Type

•

Rbac Authorisation Administration Interface Type

10/40

Specification of the Authorisation Service – Overview and Architecture Outline cd Authorisation Serv ice AuthorisationInterface PermissionAdministrationInterface RbacAuthorisationAdministrationInterface ServiceCapabilities «interface» AuthorisationService + + + + + + + + + + + + +

assignPermissionToPrincipal(OA_Permission, OA_Principal) : void assignPermissionToRole(OA_Permission, OA_Role) : void assignRoleToPrincipal(OA_Principal, OA_Role) : void authorise(OA_AuthorisationContext) : CharacterString createRole(OA_Role) : void deleteRole(OA_Role) : void getCapabilities(OA_GetCapabilitiesRequest) : OA_CapabilitiesDocument getPermissions(OA_Query) : Sequence getRoles(OA_Query) : Sequence unassigneRoleFromPrincipal(OA_Principal, OA_Role) : void unassignPermissionFromPrincipal(OA_Permission, OA_Principal) : void unassignPermissionFromRole(OA_Permission, OA_Role) : void updateRole(OA_Role) : void

Diagram 1: Class Diagram of the Authorisation Service

11/40

Specification of the Authorisation Service – Context of the Authorisation Service

4

Context of the Authorisation Service

4.1

Relations to Standards •

RFC 2704: The KeyNote Trust-Management System Version 2 KeyNote is a representative of an authorisation paradigm called Trust Management. More information about Trust Management can be found under http://www.crypto.com/trustmgt/kn.html. Since the reference implementation of KeyNote has been created in C systems using KeyNote currently need to be programmed in C/C++ or any other language that is able to interact with C natively (e.g. Java).

•

David F. Ferraiolo et. al, Proposed NIST Standard for Role-Based Access Control, National Institute of Standards and Technology, 2001 This proposed standard describes components as well as a classification of systems using an role based authorisation paradigm which can be relevant for the implementation of a role based Authorisation Service.

•

OASIS eXtensible Access Control Markup Language (XACML) TC http://www.oasis-open.org/committees/workgroup.php?wg_abbrev=xacml The XACML standard could be used by Authorisation Service implementations to describe policies. For some authorisation paradigms like trust management, for example, it might be necessary to create a separate XACML profile.

•

OGC Geo Digital Rights Management (GeoDRM) http://www.opengeospatial.org/projects/groups/geodrmwg The Geo Digitial Rights Managment can be considered as an authorisation paradigm.

The Authorisation Service currently does not qualify for the contribution to a standard.

4.2

Relations to ongoing Initiatives and related Projects The Authorisation Service has no immediate relation to ongoing projects.

4.3

Relations to ORCHESTRA Application Schemas The Authorisation Interface Type Specification that is specified as integral part of this Service Type Specification uses Basic and OA Types that are defined in the package OAS/Basic Types, OAS/OA Types and OAS-MI/OA-MI Types of the Information Viewpoint. The Authorisation Interface Type Specification that is specified as integral part of this Service Type Specification defines new parameter types. These parameter types are defined the in the package OAS/OA Types/«Application Schema» Authorisation Service Exceptions, OAS/OA Types/ «Application Schema» Authorisation Service Types of the Information Viewpoint.

4.4 4.4.1

Relations to other ORCHESTRA Service Specifications Authentication Service In an Authorisation Service permissions can be assigned to principals which have been defined and authenticated using an Authentication Service. During an authorisation request an Authorisation Service retrieves an Authorisation Context containing authenticated principals and runtime information of the service requesting the authorisation decision. With a list of authenticated principals the Authorisation Service determines an enumeration of permissions assigned to these principals. The authorisation decision bases upon that list of permissions.

12/40

Specification of the Authorisation Service – Requirements

5 5.1

Requirements Security Requirements The Authorisation Service has the following requirements. •

5.2

Communication between a service and its Authorisation Service should be protected, e.g. by using encrypted communication channels. Otherwise, an attacker might be able to record or even imitate security information.

Reliability Requirements In order to ensure consistency to User Management and Authentication Services, principals should be deleted within transactions. Such a transaction should span all services referencing the corresponding principal.

13/40

Specification of the Authorisation Service – Specification of the Authorisation Interface

6

Specification of the Authorisation Interface

cd Authorisation Interface «interface» AuthorisationInterface +

authorise(OA_AuthorisationContext) : CharacterString

Diagram 2: Class Diagram of the Authorisation Interface

The Authorisation Interface defines the following operation:

Operation Name

Description Requests an authorisation decision for a given authorisation context.

authorise

Table 1: Summary of operations

6.1

Specification of an OAS Profile of Parameter Types used by the Authorisation Interface The following non basic types are used within this specification:

Name

Usage

from OAS

New

OA_AuthorisationContext

I

OA Types

Yes


O

OA Types

No


O

OA MI Types

No


I

OA Types

No


E


No


E


No

OA_NoApplicableCode

E


No

OA_InternalError

E


No

14/40

Specification of the Authorisation Service – Specification of the Authorisation Interface


E


No


6.2 6.2.1

Specification of the Operations Specification of the authorise Operation The mandatory authorise operation requests an authorisation decision for a given authorisation context. The signatures of the operation is CharacterString authorise (OA_AuthorisationContext) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PermissionDeniedException

Overrides

Not applicable

Preconditions

none

Post conditions

none

Use

mandatory

Receives

Name

Type

authorisationContext

OA_Authorisatio nContext

Use

mandatory

Description Authorisation context, a set of information used by the authorisation service to determine the authorisation decision for a given request. The authorisation context can contain e.g. the requesting principal(s), name of the invoked operation, etc. Authorisation contexts have to be agreed between a service and its Authorisation Service.

Returns

Type CharacterString

Description Compliance value representing the advice how to treat a certain service request. Compliance values need to be agreed between a service and its Authorisation Service.

Throws

Type

Cause




Operation request does not include a parameter value. Return the name of the missing pa-

15/40

Specification of the Authorisation Service – Specification of the Authorisation Interface rameter. OA_NoApplicableCode


OA_InternalError



Thrown if an unknown service requests an authorisation decision.

Table 3: Specification of the authorise Operation

16/40

Specification of the Authorisation Service – Specification of Authorisation Administration Interface

7

Specification of Authorisation Administration Interface

cd Authorisation Serv ice «interface» AuthorisationAdministration

«interface» PermissionAdministration + + +

assignPermissionToPrincipal(OA_Permission, OA_Principal) : void getPermissions(OA_Query) : Sequence unassignPermissionFromPrincipal(OA_Permission, OA_Principal) : void

«interface» RbacAuthorisationAdministration + + + + + + + +

assignPermissionToRole(OA_Permission, OA_Role) : void assignRoleToPrincipal(OA_Role, OA_Principal) : void createRole(OA_Role) : void deleteRole(OA_Role) : void getRoles(OA_Query) : Sequence unassignPermissionFromRole(OA_Permission, OA_Role) : void unassignRoleFromPrincipal(OA_Role, OA_Principal) : void updateRole(OA_Role) : void

Diagram 3: Class Diagram of the Authorisation Administration Interface, including two specialisations for Permission and Role-based Authorisation Administration The Authorisation Administration Interface reflects the circumstance that different authorisation paradigms might have no operations in common. Nonetheless, it is important to indicate that every Authorisation Service implementation needs to support an appropriate and paradigm specific authorisation administration interface. Authorisation administration implementations will implement the authorisation administration interface as a marker interface.

17/40

Specification of the Authorisation Service – Specification of an OAS Profile of Parameter Types used by the Permission Administration Interface

8

Specification of Permission Administration Interface cd Permission Administration Interface «interface» PermissionAdministrationInterface + + +

assignPermissionToPrincipal(OA_Permission, OA_Principal) : void getPermissions(OA_Query) : Sequence unassignPermissionFromPrincipal(OA_Permission, OA_Principal) : void

Diagram 4: Class Diagram of the Permission Administration Interface

The Permission Administration Interface provides basic operations to (un-)assign permissions directly to principals. The Permission Administration Interface defines the following operations:

Operation Name

Description

assignPermissionToPrincipal

Assigns a permission to a principal.

unassignPermissionToPrincipal

Removes a permission from a principal.

getPermissions

Allows retrieval of permissions specified by the given query. Table 4: Summary of Operations

8.1

Specification of an OAS Profile of Parameter Types used by the Permission Administration Interface The following non basic types are used within this specification:

Name

Usage

from OAS

New

OA_Principal

O

OA Types

No

OA_Permission

I

OA Types

Yes

OA_Query

I

OA_Types

No


E


No


E


No


E


No

18/40

Specification of the Authorisation Service – Specification of the Operations


E


No

OA_NoApplicableCode

E


No

OA_InternalError

E


No


E


No


E


Yes

OA_PermissionNotFoundException

E


Yes

OA_AssociationAlreadyExistsException

E


Yes

OA_NoSuchAssociationException

E


Yes


8.2 8.2.1

Specification of the Operations Specification of the assignPermissionToPrincipal Operation The mandatory assignPermissionToPrincipal operation assigns permission to a certain principal. Permission and principal have to exist already. The signatures of the operation is void assignPermissionToPrincipal (OA_Permission OA_Principal) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PrincipalNotFoundException, OA_PermissionNotFoundException, OA_PermissionDeniedException OA_AssociationAlreadyExistsException

Overrides

Not applicable

Preconditions

None

Post conditions

None

Use

mandatory

Receives

Returns

Name

Type

Use

Description

permission

OA_Permission

mandatory

Permission to be assigned to the given principal.

Principal

OA_Principal

mandatory

Principal to which permissions should be assigned.

Type

Description

19/40


None

None

Throws

Type

Cause





OA_NoApplicableCode


OA_InternalError





The permission to act on cannot be found.


The requesting principal is no sufficient permission to invoke the requested operation.


There is already an association between the given principal and role.

Table 6: Specification of the assignPermissionToPrincipal Operation 8.2.2

Specification of the unassignPermissionFromPrincipal Operation The mandatory unassignPermissionFromPrincipal operation removes permission from a certain principal. The signatures of the operation is void unassignPermissionFromPrincipal (OA_Principal, OA_Permission) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PrincipalNotFoundException, OA_PermissionNotFoundException, OA_PermissionDeniedException, OA_NoSuchAssociationException

Overrides

Not applicable

Preconditions

None

Post conditions

None

Use

mandatory

Receives

Name principal

Type OA_Principal

Use mandatory

20/40

Description Principal from which the permission should be removed.


Permission Returns

OA_Permission

mandatory

Type

Description

None Throws

Permission to be removed from the given principal.

None Type

Cause





OA_NoApplicableCode


OA_InternalError









There is no association between the given principal and permission which could be deleted.

Table 7: Specification of the unassignPermissionFromPrincipal Operation 8.2.3

Specification of the getPermissions Operation The mandatory getPermissions operation retrieves a list of permissions specified by a given query. The signatures of the operation is OA_Permission getPermissions (OA_Query) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PrincipalNotFoundException, OA_PermissionNotFoundException, OA_PermissionDeniedException

Overrides

Not applicable

Preconditions

None

Post conditions

None

Use

mandatory

Receives

Name

Type

Use

21/40

Description


query

Returns

OA_Query

optional

Type

Description

Throws

Query describing permissions to be retrieved. The query could include, for example, a principal or group to retrieve permissions bound to it.

Permissions matching the given query.

Type

Cause





OA_NoApplicableCode


OA_InternalError








Table 8: Specification of the getPermissions Operation

22/40

Specification of the Authorisation Service – Specification of an OAS Profile of Parameter Types used by the Rbac Authorisation Administration Interface

9

Rbac Authorisation Administration Interface Specification cd RBAC Authorisation Administration Interface «interface» RbacAuthorisationAdministrationInterface + + + + + + + +

assignPermissionToRole(OA_Permission, OA_Role) : void assignRoleToPrincipal(OA_Principal, OA_Role) : void createRole(OA_Role) : void deleteRole(OA_Role) : void getRoles(OA_Query) : Sequence unassigneRoleFromPrincipal(OA_Principal, OA_Role) : void unassignPermissionFromRole(OA_Permission, OA_Role) : void updateRole(OA_Role) : void

Diagram 5: Class Diagram of the Rbac Authorisation Administration Interface The Rbac Authorisation Administration Interface provides operations to create/delete roles and to assign/unassign them to several principals. A role is a collection of permissions. An implementation of the Rbac Authorisation Administration interface may make use of an implementation of the Permission Administration interface. The Rbac Authorisation Service interface defines the following operations:

Operation Name

Description

createRole

Creates a new role. Newly created roles are empty. Neither permission nor principals are assigned, yet.

deleteRole

Deletes an existing role. Permission and principal assignments are deleted as well.

getRoles

Retrieves an enumeration of existing roles.

updateRole

Updates an existing role, e.g. description, etc.

assignPermissionToRole

Assigns permission to a certain role. Permission and role have to exist already.

unassignPermissionFromRole

Removes permission from a certain role.

assignRoleToPrincipal

Assigns an existing role to an existing principal. This indirectly assigns permissions associated with the role to the principal.

unassignRoleFromPrincipal

Removes the given role from a certain principal. This indirectly removes permissions associated with the role from the principal. Table 9: Summary of Operations

9.1

Specification of an OAS Profile of Parameter Types used by the Rbac Authorisation Administration Interface The following non basic types are used within this specification:

23/40


Name

Usage

from OAS

New

OA_Principal

O

OA Types

No

OA_Permission

I

OA Types

Yes

OA_Role

I, O

OA Types

Yes

OA_Query

I

OA_Types

No

OA_RoleNotFoundException

E


Yes


E


No


E


Yes


E


Yes


E


Yes


E


Yes


9.2 9.2.1

Specification of the Operations Specification of the createRole Operation The mandatory createRole operation creates a new role. Newly created roles are empty. Neither permission nor principals are assigned, yet. The signatures of the operation is void createRole(OA_Role) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PermissionDeniedException

Overrides

Not applicable

Preconditions

None

Post conditions

None

Use

mandatory

Receives

Name role

Returns

Type OA_Role

Use mandatory

Type

Description Role to be created. Description

24/40


Not applicable Throws

Not applicable

Type

Cause





OA_NoApplicableCode




OA_InternalError


Table 11: Specification of the createRole Operation 9.2.2

Specification of the deleteRole Operation The mandatory deleteRole operation deletes an existing role. Permission and principal assignments are deleted as well. The signatures of the operation is void deleteRole(OA_Role) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PermissionDeniedException, OA_RoleNotFoundException

Overrides

Not applicable

Preconditions

None

Post conditions

None

Use

mandatory

Receives

Name

Type

role Returns

OA_Role

mandatory

Type Not applicable

Throws

Use

Role to be deleted. Description

Not applicable

Type OA_InvalidParameterValue

Description

Cause Operation request contains an invalid parameter value. Return the name of the parameter with invalid value.

25/40




OA_NoApplicableCode


OA_InternalError





The role to be deleted cannot be found.

Table 12: Specification of the deleteRole Operation 9.2.3

Specification of the getRoles Operation The mandatory getRoles operation retrieves an enumeration of existing roles. The signatures of the operation is Sequence getRoles(OA_Query) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PermissionDeniedException

Overrides

Not applicable

Preconditions

None

Post conditions

None

Use

mandatory

Receives

Name query

Returns

Type

Use

OA_Query

optional

Type Sequence

Throws

Description Query to specify which roles to be retrieved. Description

Enumeration of OA_Role features.

Type

Cause





OA_NoApplicableCode


26/40




OA_InternalError


Table 13: Specification of the getRoles Operation 9.2.4

Specification of the updateRole Operation The mandatory updateRole operation updates an existing role, e.g. its description, etc. The signatures of the operation is void updateRole(OA_Role) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PermissionDeniedException, OA_RoleNotFoundException

Overrides

Not applicable

Preconditions

None

Post conditions

None

Use

mandatory

Receives

Name

role

Returns

Type

OA_Role

mandatory

Type None

Throws

Use

Description Role containing the changes to be made including a unique role identifier. This necessary to be able to locate the role to be updated. Description

None Type

Cause





OA_NoApplicableCode


OA_InternalError




27/40



Role to act on cannot be found.

Table 14: Specification of the updateRole Operation 9.2.5

Specification of the assignPermissionToRole Operation The mandatory assignPermissionToRole operation assigns permission to a certain role. Permission and role have to exist already. The signatures of the operation is void assignPermissionToRole(OA_Role, OA_Permission) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PermissionDeniedException, OA_RoleNotFoundException, OA_PermissionNotFoundException, OA_AssociationAlreadyExistsException

Overrides

Not applicable

Preconditions

None

Post conditions

None

Use

mandatory

Receives

Name

Type

Use

Description

role

OA_Role

mandatory

Role to which permissions should be assigned.

Permission

OA_Permission

mandatory

Permission to be assigned to the given role.

Returns

Type

Description

None Throws

None Type

Cause





OA_NoApplicableCode


OA_InternalError





Permission to act on cannot be found.

28/40





There is already an association between the given role and principal.

Table 15: Specification of the assignPermissionToRole Operation 9.2.6

Specification of the unassignPermissionFromRole Operation The mandatory unassignPermissionFromRole operation removes permission from a certain role. The signatures of the operation is void unassignPermissionFromRole(OA_Role, OA_Permission) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PermissionDeniedException, OA_RoleNotFoundException, OA_PermissionNotFoundException, OA_NoSuchAssociationException

Overrides

Not applicable

Preconditions

None

Post conditions

None

Use

mandatory

Receives

Name

Type

Description

role

OA_Role

mandatory

Role from which the permission should be removed.

Permission

OA_Permission

mandatory

Permission to be removed from the given role.

Returns

Type None

Throws

Use

Description None

Type

Cause





OA_NoApplicableCode


OA_InternalError


29/40





Permission to act on cannot be found.




There is no association between the given principal and the given role which could be deleted.

Table 16: Specification of the unassignPermissionFromRole Operation 9.2.7

Specification of the assignRoleToPrincipal Operation The mandatory assignRoleToPrincipal operation assigns a given role to a certain principal. Role and principal have to exist already. The signatures of the operation is void assignRoleToPrincipal(OA_Role, OA_Principal) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PermissionDeniedException, OA_PrincipalNotFoundException, OA_PermissionNotFoundException, OA_AssociationAlreadyExistsException

Overrides

Not applicable

Preconditions

None

Post conditions

None

Use

mandatory

Receives

Name

Type

Use

role

OA_Role

mandatory

Role to be assigned to the given principal.

principal

OA_Principal

mandatory

Principal to which permissions should be assigned.

Returns

Type

Description

None Throws

Description

None Type

Cause





30/40


OA_NoApplicableCode


OA_InternalError









There is already an association between the given principal and role.

Table 17: Specification of the assignRoleToPrincipal Operation 9.2.8

Specification of the unassignRoleFromPrincipal Operation The mandatory unassignRoleFromPrincipal operation removes a role from a certain principal. The signatures of the operation is void unassignRoleFromPrincipal(OA_Role, OA_Principal) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PermissionDeniedException, OA_PrincipalNotFoundException, OA_PermissionNotFoundException, OA_NoSuchAssociationException

Overrides

Not applicable

Preconditions

None

Post conditions

None

Use

mandatory

Receives

Name

Type

Description

role

OA_Role

mandatory

Role to be revoked from the specified principal.

principal

OA_Principal

mandatory

Principal from which the permission should be removed.

Returns

Type None

Throws

Use

Description None



31/40




OA_NoApplicableCode


OA_InternalError









There is no association between the given principal and permission which could be deleted.

Table 18: Specification of the unassignRoleFromPrincipal Operation

32/40

Specification of the Authorisation Service – Specification of Parameter Types

9.3

Specification of Parameter Types This interface specification defines new OA Types. These new OA Types will become part of the OAS “OA Types”. This interface specification does not define any new OT Types. This interface specification does not introduce any new non-orchestra Types.

9.3.1

OA_Permission cd Authorisation Serv ice «type» OA_Permission +

grant: Boolean = false

Diagram 6: Class diagram of OA_Permission The abstract OA_Permission type is not used directly. Instead, concrete permission types have to inherit from OA_Permission. The Boolean grant attribute indicates whether the permission grants (grant = true) or revokes (grant = false, default) access to the corresponding resource. 9.3.2

OA_OperationPermission cd Authorisation Serv ice «type» OA_Permission +


«type» OA_OperationPermission +

operationName: CharacterString

Diagram 7: Class diagram of OA_OperationPermission The OA_OperationPermission type is used to grant or revoke access to individual service operations. The operationName attribute contains the name of the operation to which access is granted or revoked.

33/40

Specification of the Authorisation Service – Specification of Parameter Types 9.3.3

OA_Role cd Authorisation Serv ice RBAC «type» OA_Role + + +

name: CharacterString description: CharacterString permission: OA_FeatureCollection

«type» OA_Permission +


Diagram 8: Class diagram of OA_Role The OA_Role type represents a role consisting of a set of associated permissions. The attribute name contains the role’s name. The attribute description contains the role’s description. The attribute permissions contains a OA_FeatureCollection of OA_Permission features representing the permissions associated with the role.

34/40

Specification of the Authorisation Service – Specification of Parameter Types 9.3.4

OA_AuthorisationContext cd Authorisation Serv ice Authorisation Context «type» OA_AuthorisationContext + +

sourceService: OA_OSI_Identifier authenticatedPrincipals: Sequenmce

«type» OA_KeyValueAuthorisationContext +

context: Dictionary

Dictionary

«enumeration» OA_AuthorisationContextAttribute

Diagram 9: Class diagram of OA_AuthorisationContext The sourceService attribute contains the OA_OSI_Identifier of the service requesting an authorisation decision. This is important for Authorisation Services serving multiple services. 9.3.5

OA_KeyValueAuthorisationContext In order to provide the capability to support different authorisation paradigms the class OA_KeyValueAuthorisationContext introduces the attribute context as a dictionary (that is a list of keyvalue pairs). The actual content of these pairs is defined by the respective authorisation paradigm.

9.3.6

OA_RoleNotFoundException The OA_RoleNotFoundException is throws if the role to act on cannot be found.

9.3.7

OA_PermissionDeniedException The OA_PermissionDeniedException has to be used by every service using an Authorisation Service. It is thrown if the service of the requested operation has received an negative compliance value from its Authorisation Service.

9.3.8

OA_PermissionNotFoundException The OA_PermissionNotFoundException is thrown if the permission to act on cannot be found.

9.3.9

OA_AssociationAlreadyExistsException The OA_AssociationAlreadyExistsException is throws if an association should be created which already

35/40

Specification of the Authorisation Service – Specification of Parameter Types exists. 9.3.10 OA_NoSuchAssociationException The OA_NoSuchAssociationException is thrown if the association, for example a permission association between a principal and permission, cannot be found. cd Authorisation Serv ice Exceptions «type» OA_AbstractException + +


+


«type» OA_RoleNotFoundException

«type» OA_NoSuchAssociationException

«type» OA_PermissionDeniedException

«type» OA_AssociationAlreadyExistException

«type» OA_PermissionNotFoundException

Diagram 10: New exceptions in the Authorisation Service

36/40

Specification of the Authorisation Service – Specification of extended Service Capabilities

10 Specification of extended Service Capabilities As part of ORCHESTRA D3.3.2 a meta-information schema for services is defined acting as a default OAS-MI for service capabilities. OA_MI_CapabilitiesDocument includes both the common capabilities and the service specific capabilities. While the common capabilities are defined in the specification of the Service Capabilities Interface, the specific capabilities have to be specialized in each service specification.

cd Authorisation Serv ice Capabilities «type» OA_MI_Serv ice_SpecificCapabilities

«type» OA_MI_AuthorisationServ iceCapabilities + + +

supportedPermissionTypes: OA_MI_PermissionType [1..*] supportedAdministrationInterfaces: OA_MI_AuthorisationParadigms [1..*] supportedAuthorisationParadigms: OA_MI_AuthorisationParadigms [1..*]

Type

«enumeration» OA_MI_AuthorisationParadigms + +

«type» OA_MI_PermissionType

Permission Rbac

Diagram 11: Authorisation Service specific capabilities The schema for service specific capabilities defined here is explicitly divided into the following schema sections:

Section Name

Section Contents

supportedPermissionTypes

This lists the supported permission types, e.g. the types OA_OperationPermission or the type corresponding to time-slice permission.

supportedAuthorisationParadigms

Paradigms for authorisation, currently permission-authorisation and role-based access control are included. This list may be extended.

supportedAdministrationInterfaces

The administration of each authorisation paradigm (see above) may be supported by an individual administration interface.


37/40

Specification of the Authorisation Service – Specification of extended Service Capabilities

Name

Definition

Data Type


OA_OperationPermission

This allows to restrict access on basis of the called operation.

CharacterString

0,1 mandatory

TimeSlicePermission

This allows to restrict access on basis of time-constraints.

CharacterString

0,1 mandatory

Further permissions-types may be added when needed. Table 20: Attributes of the service specific capabilities of section supportedPermissionTypes

Name

Definition

Data Type


Permission

The authorisation-decision bases upon permissions directly associated to principals.

CharacterString

0,1 mandatory

Rbac

In role-based access control a role is a set of permissions. A principal can be associated with a role and hence has all its permissions.

CharacterString

0,1 mandatory

Further authorisation-paradigms may be added when needed. Table 21: Attributes of the service specific capabilities of section supportedAuthorisationParadigms Depending on the permission type different descriptions are needed. In case of operation-permissions it must be possible to refer to operations, this capability is provided by the type OA_MI_Operation – this meta-information type has originally been defined for the purpose of discovery of services. In case of time-slice permission a time-span and recurring time-spans are defined as meta-information: cd Authorisation Serv ice Capabilities OA_MI_TimeSpan + +

startTime: DateTime endTime: DateTime

«type» OA_MI_RecurringTimeSpans + + + +

firstOcurrence: DateTime intervalBetweenStartingTimes: DateTime timeSpan: OA_MI_TimeSpan lastOccurrence: DateTime

Diagram 12: Meta-information necessary for time-slice permission

38/40

Specification of the Authorisation Service – Appendix A: Abstract Test Suite (normative)

11

Appendix A: Abstract Test Suite (normative) When creating an implementation specification of the Authorisation Service, the “Rules for Implementation Specifications of ORCHESTRA Services” defined in chapter 9.2.2.3 and the “Rules for the Service Mapping to a given Platform” of the RM-OA shall be obeyed. In addition, the following tests shall be performed to ensure conformance of an implementation specification to the platform-independent specification of the Authorisation Service: 1. Syntactical Conformance •


•


•


•




Additional conformance checks that are specifically to the Authorisation Service are not required.

39/40

Specification of the Authorisation Service – Appendix B: UML Models (normative)

12



40/40




Specification of the Catalogue Service

Revision

1/76

[1.3/ 2.2.1]

Specification of the Catalogue Service – Document Control Page


Specification of the Catalogue Service

Creator

Hilbring, Désirée

Subject


Description

This document defines an abstract and platform independent formal specification of the Catalogue Service.

Publisher


Contributor

Coraboeuf, Damien

Date

2008-05-19

Type

Text

Format

application/msword

Identifier


Source

Not applicable

Language

en-GB.

Relation

none

Coverage


IITB

BRGM


D3.4.4


WP3.4

Contractual Date of Delivery Actual Date of Delivery Audience


Version number

1.3 / 2.2.1

Date

2009-07-22

Modified by

Hilbring, Désirée

IITB

Comments Status


2/76

Specification of the Catalogue Service – Document Control Page


to be revised by partners involved in the preparation of the deliverable for approval of the WP leader for approval of the SP leader for approval of the Technical Supervisor for approval of the Quality Manager for approval of the Project Coordinator Deadline for action:

3/76

Specification of the Catalogue Service – Revision History


Date

1.1 / 2.2.1

2007-10-17

1.2 / 2.2.1

2008-05-19

Sections changed all

Description Specification adapted to new template, integration of semantic interface Inclusion of operation activateOntology in semantic interface Inclusion of Catalogue Management Interface and according extension of specific catalogue capabilities.

1.3 / 2.2.1

2008-06-19

Navigation Interface removed.

1.4 / 2.2.1

2009-07-22

Harvest operation included

4/76

Specification of the Catalogue Service – Table of Contents

Table of Contents 1

Foreword ...................................................................................................................................................11

2

Conventions ..............................................................................................................................................12 2.1

Abbreviations .....................................................................................................................................12

2.2

Terms and definitions .........................................................................................................................12

2.3

UML Notation .....................................................................................................................................12

2.4

Conformance ......................................................................................................................................12

2.4.1

Conformance to the OMM ..........................................................................................................12

2.4.2

Conformance of Implementation Specifications .........................................................................12

2.5 3

4

5

6

Used parts of other documents ..........................................................................................................12

Overview and Architecture Outline ............................................................................................................12 3.1

Role and Scope of the Catalogue Service .........................................................................................12

3.2

Service Specification Summary .........................................................................................................13

Context of the Catalogue Service .............................................................................................................19 4.1

Relations to Standards .......................................................................................................................19

4.2

Relations to ongoing Initiatives and related Projects .........................................................................19

4.3

Relations to ORCHESTRA Application Schemas ..............................................................................19

4.4

Relations to other ORCHESTRA Service Specifications ...................................................................20

Requirements ............................................................................................................................................21 5.1

Security Requirements .......................................................................................................................21

5.2

Reliability Requirements ....................................................................................................................21

Specification of the Search Interface ........................................................................................................22 6.1

Specification of an OAS Profile of Parameter Types used by the Catalogue Search Interface ........23

6.2

Specification of the Operations ..........................................................................................................24

6.2.1

Specification of the search Operation .........................................................................................24

6.2.2

Specification of the getMetaInformation Operation ....................................................................26

6.2.3

Specification of the getQueryDomain Operation ........................................................................29

6.2.4

Specification of the getMetainformationType Operation.............................................................31

6.3

Specification of Parameter Types ......................................................................................................34

6.3.1

OA_SearchRequest ....................................................................................................................34

6.3.2

OA_SortSpec ..............................................................................................................................34

6.3.3

OA_SortOrder .............................................................................................................................34

6.3.4

OA_SearchType .........................................................................................................................34

5/76

Specification of the Catalogue Service – Table of Contents 6.3.5

OA_SearchResponse .................................................................................................................34

6.3.6

OA_FeatureIDList .......................................................................................................................34

6.3.7

OA_CoreMIList ...........................................................................................................................35

6.3.8

OA_GetMetaInformationRequest ...............................................................................................35

6.3.9

OA_GetMetaInformationResponse.............................................................................................35

6.3.10 OA_GetQueryDomainRequest ...................................................................................................35 6.3.11 OA_GetQueryDomainResponse ................................................................................................35 6.3.12 OA_QueryParameterDomain......................................................................................................35 6.3.13 OA_ConceptualScheme .............................................................................................................35 6.3.14 OA_Range ..................................................................................................................................35 6.3.15 OA_GetMetaInformationTypeRequest .......................................................................................35 6.3.16 OA_GetMetaInformationTypeResponse ....................................................................................35 6.3.17 OA_CatalogEntryType ................................................................................................................35 6.3.18 OA_CatalogEntryTypeReference ...............................................................................................36 6.3.19 OA_CatalogueMetaInformationType ..........................................................................................36 6.3.20 OA_UnsupportedCatalogueEntryType .......................................................................................36 6.3.21 OA_UnknownSubCategoryId......................................................................................................36 6.3.22 OA_UnsupportedQueryLanguage ..............................................................................................36 6.3.23 OA_InvalidCursorPosition...........................................................................................................36 7

Specification of the Publication Interface ..................................................................................................37 7.1

Specification of an OAS Profile of Parameter Types used by the Catalogue Publication Interface ..38

7.2


7.2.1

Specification of the createMetaInformation Operation ...............................................................39

7.2.2

Specification of the setMetaInformation Operation.....................................................................40

7.2.3

Specification of the deleteMetaInformation Operation................................................................42

7.3

8


7.3.1

OA_CreateMetaInformationRequest ..........................................................................................44

7.3.2

OA_PublicationMetainformationResponse .................................................................................44

7.3.3

OA_MIElementID ........................................................................................................................44

7.3.4

OA_MetaInformationSet .............................................................................................................44

7.3.5

OA_SetMetaInformationRequest ................................................................................................45

7.3.6

OA_DeleteMetaInformationRequest ...........................................................................................45

7.3.7

OA_UnsupportedMetaInformationType ......................................................................................45

7.3.8

OA_UnknownFeatureId ..............................................................................................................45

7.3.9

OA_NumberOfIdException .........................................................................................................45

Specification of the Collection Interface ....................................................................................................46

6/76

Specification of the Catalogue Service – Table of Contents 8.1

Specification of an OAS Profile of Parameter Types used by the Catalogue Publication Interface ..46

8.2


8.2.1

Specification of the collectMetaInformation Operation ...............................................................48

8.2.2

Specification of the collectMetaInformationPeriodic Operation ..................................................49

8.3

9


8.3.1

OA_CollectMetaInformationRequest ..........................................................................................52

8.3.2

OA_CollectMetaInformationPeriodicRequest .............................................................................52

8.3.3

OA_CollectType ..........................................................................................................................52

8.3.4

OA_CollectTypeEnum ................................................................................................................52

8.3.5

OA_IntervalNotSupported ...........................................................................................................52

Specification of the Semantic Interface .....................................................................................................53 9.1

Specification of an OAS Profile of Parameter Types used by the Catalogue Semantic Interface.....53

9.2


9.2.1

Specification of the improveQuery Operation .............................................................................54

9.2.2

Specification of the activateOntology Operation.........................................................................56

9.3


9.3.1

OA_ActivateOntologyRequest ....................................................................................................58

9.3.2

OA_ActivateOntologyResponse .................................................................................................58

10 Specification of the Catalogue Management Interface .............................................................................59 10.1

Specification of an OAS Profile of Parameter Types used by the Catalogue Semantic Interface .60

10.2

Specification of the Operations ......................................................................................................60

10.2.1 Specification of the activateCatalogue Operation.......................................................................61 10.2.2 Specification of the setCatalogue Operation ..............................................................................62 10.2.3 Specification of the getCatalogue Operation ..............................................................................63 10.2.4 Specification of the deleteCatalogue Operation .........................................................................64 10.3

Specification of Parameter Types ..................................................................................................65

10.3.1 OA_ActivateCatalogueRequest ..................................................................................................65 10.3.2 OA_ActivateCatalgueResponse .................................................................................................65 10.3.3 OA_SetCatalogueRequest .........................................................................................................65 10.3.4 OA_SetCatalogueResponse.......................................................................................................65 10.3.5 OA_GetCatalogueRequest .........................................................................................................65 10.3.6 OA_GetCatalogueResponse ......................................................................................................66 10.3.7 OA_DeleteCatalogueRequest ....................................................................................................66 10.3.8 OA_DeleteCatalgueResponse....................................................................................................66 11 Specification of the Harvesting Interface...................................................................................................67

7/76

Specification of the Catalogue Service – Table of Contents 11.1

Specification of an OAS Profile of Parameter Types used by the Catalogue Harvesting Interface 67

11.2

Specification of the Operations ......................................................................................................68

11.2.1 Specification of the harvest Operation ........................................................................................68 11.3

Specification of Parameter Types ..................................................................................................70

11.3.1 Harvest........................................................................................................................................70 11.3.2 Source .........................................................................................................................................70 11.3.3 ResourceType.............................................................................................................................70 11.3.4 ResourceFormat .........................................................................................................................70 11.3.5 HarvestInterval ............................................................................................................................70 11.3.6 ResponseHandler .......................................................................................................................70 11.3.7 ExternalResourceUrl ...................................................................................................................70 11.3.8 HarvestResponse .......................................................................................................................70 11.3.9 Acknowledgement.......................................................................................................................71 11.3.10

TransactionResponse .............................................................................................................71

11.3.11

TransactionSummary ..............................................................................................................71

12 Specification of the Service specific Capabilities ......................................................................................71 12.1

Specification of additional OA Types..............................................................................................72

12.1.1 OA_CatalogueCapabilities..........................................................................................................73 12.1.2 OA_CatalogueEntryTypeDescriptor ...........................................................................................73 12.1.3 OA_QueryLanguageInformation .................................................................................................73 12.1.4 OA_QueryExtension ...................................................................................................................73 12.1.5 OA_OGCFilterExtension .............................................................................................................73 12.1.6 Other extension types derived from OA_QueryExtension ..........................................................73 12.1.7 OA_UnknownFeatureId ..............................................................................................................73 13 Known Issues and Limitations ...................................................................................................................74 13.1

Known Issues and Limitations of Search Interface ........................................................................74

13.2

Known Issues and Limitations of Specific Capabilities ..................................................................74

14 Appendix A: Abstract Test Suite (normative) ............................................................................................75 15 Appendix B: UML Models (normative) ......................................................................................................76 15.1

XMI Model ......................................................................................................................................76

8/76

Specification of the Catalogue Service – Tables and Diagrams

Tables Table 1: Summary of inherited Service Operations ....................................................................................22 Table 2: Summary of additional Service Operations ........................................................................................23 Table 3: Referenced OA Types ........................................................................................................................24 Table 4: Specification of the search Operation ................................................................................................26 Table 5: Specification of the getMetaInformation Operation ............................................................................29 Table 6: Specification of the getQueryDomain Operation ................................................................................31 Table 7: Specification of the getMetainformationType Operation ....................................................................33 Table 8: Summary of inherited Service Operations ....................................................................................37 Table 9: Summary of additional Service Operations ........................................................................................37 Table 10: Referenced OA Types ......................................................................................................................38 Table 11: Specification of the createMetaInformation Operation .....................................................................40 Table 12: Specification of the setMetaInformation Operation ..........................................................................42 Table 13: Specification of the deleteMetaInformation Operation .....................................................................44 Table 14: Summary of inherited Service Operations ..................................................................................46 Table 15: Summary of additional Service Operations ......................................................................................46 Table 16: Referenced OA Types ......................................................................................................................47 Table 17: Specification of the collectMetaInformationPeriodic Operation ........................................................49 Table 18: Specification of the collectMetaInformationPeriodic Operation ........................................................51 Table 19: Summary of inherited Service Operations ..................................................................................53 Table 20: Summary of additional Service Operations ......................................................................................53 Table 21: Referenced OA Types ......................................................................................................................54 Table 22: Specification of the improveQuery Operation ..................................................................................56 Table 23: Specification of the activateOntology Operation ..............................................................................57 Table 24: Summary of inherited Service Operations ..................................................................................59 Table 25: Summary of additional Service Operations ......................................................................................60 Table 26: Referenced OA Types ......................................................................................................................60 Table 27: Specification of the activateCatalogue Operation ............................................................................62 Table 28: Specification of the setCatalogue Operation ....................................................................................63 Table 29: Specification of the getCatalogue Operation ....................................................................................64 Table 30: Specification of the deleteCatalogue Operation ...............................................................................65 Table 31: Summary of inherited Service Operations ..................................................................................67 Table 32: Summary of additional Service Operations ......................................................................................67 Table 33: Referenced OA Types ......................................................................................................................68 Table 34: Specification of the harvest Operation .............................................................................................70 Table 35: Sections of the service specific capabilities .....................................................................................71 Table 36: Attributes of the service specific capabilities of section CatalogueCapabilities ...............................71

9/76

Specification of the Catalogue Service – Tables and Diagrams

Diagrams Diagram 1: Catalogue use cases .....................................................................................................................13 Diagram 2: Catalogue purpose publication ......................................................................................................14 Diagram 3: Catalogue purpose collection ........................................................................................................15 Diagram 4: Class Diagram of the Service Interface .........................................................................................16 Diagram 5: Class Diagram of the OA_CatalogueSearchInterface ...................................................................16 Diagram 6: Class Diagram of the OA_CataloguePublicationInterface .............................................................16 Diagram 7: Class Diagram of the OA_CatalogueCollectionInterface...............................................................17 Diagram 8: Class Diagram of the OA_CatalogueSemanticInterface ...............................................................17 Diagram 9: Class Diagram of the OA_CatalogueManagementInterface .........................................................18 Diagram 10: Class Diagram of the OA_CatalogueSearchInterface .................................................................22 Diagram 11: Class diagram for search Operation ............................................................................................25 Diagram 12: Class diagram for getMetaInformation Operation........................................................................28 Diagram 13: Class diagram for getQueryDomain Operation ...........................................................................30 Diagram 14: Class diagram for getMetaInformationType Operation................................................................32 Diagram 15: Class Diagram of the OA_CataloguePublicationInterface ...........................................................37 Diagram 16: Class diagram for createMetaInformation Operation...................................................................39 Diagram 17: Class diagram for setMetaInformation Operation ........................................................................41 Diagram 18: Class diagram for deleteMetaInformation Operation ...................................................................43 Diagram 19: Class Diagram of the OA_CatalogueCollectionInterface.............................................................46 Diagram 20: Class diagram for collectMetaInformation Operation ..................................................................48 Diagram 21: Class diagram for collectMetaInformationPeriodic Operation .....................................................50 Diagram 22: Class Diagram of the OA_CatalogueSemanticInterface .............................................................53 Diagram 23: Class diagram for improveQuery Operation ................................................................................55 Diagram 24: Class diagram for activateOntology Operation ............................................................................56 Diagram 25: Class Diagram of the OA_CatalogueManagementInterface .......................................................59 Diagram 26: Class diagram for activateCatalogue Operation ..........................................................................61 Diagram 27: Class diagram for setCatalogue Operation .................................................................................62 Diagram 28: Class diagram for getCatalogue Operation .................................................................................63 Diagram 29: Class diagram for deleteCatalogue Operation ............................................................................64 Diagram 30: Class Diagram of the OA_HarvestingInterface............................................................................67 Diagram 31: Class diagram for harvest Operation ...........................................................................................69 Diagram 32: Class diagram for capabilities ......................................................................................................72

10/76

Specification of the Catalogue Service – Foreword

1

Foreword This document is an abstract specification of the Catalogue service and is based on the Template for the abstract Specification of ORCHESTRA Service Types version 2.2. It replaces the specification version 1.1/2.0.6. A replacement of all chapters was required due to the update of a new template. This document includes two annexes: Appendix A: Abstract Test Suite (normative) is mandatory and Appendix B: UML Models (normative) is optional. Improvements in this document are desirable to include the improvement for the described issues in the chapters regarding “Known Issues and Limitations”.

11/76

Specification of the Catalogue Service – Conventions

2

Conventions

2.1

Abbreviations •

2.2

The abbreviations used in this document are defined in chapter 3.1 of the Reference Model for the ORCHESTRA Architecture Version 2.0 (RM-OA).

Terms and definitions Terms and definitions necessary for understanding this document are defined in chapter 3.2 of the RMOA Glossary and in chapter 2.2 of the referenced interface type specifications, except for the following terms: •

2.3

Use cases, which describe the different tasks of a Catalogue Service related to its interfaces


2.4

Conformance

2.4.1

Conformance to the OMM This abstract service specification is specified according to the rules of the ORCHESTRA Service Metamodel (OMM-Service) and follows the rules for ORCHESTRA Services as described in chapter 9.2 of the RM-OA. The extended service capabilities are be modelled according to the RM-OA rules for OAS-MI.

2.4.2


2.5

Used parts of other documents This document does not use significant parts of other documents. To reduce the need to refer to that document, this document copies some of those parts with small modifications. To indicate those parts to readers of this document, the largely copied parts are shown with a light grey background.

3 3.1

Overview and Architecture Outline Role and Scope of the Catalogue Service The Catalogue Service supports the ability to publish, query and retrieve descriptive information (meta information) for resources (i.e. data and services), meta information about Orchestra Source Systems just like meta information for other Orchestra services and instances of feature types that are referred to by extensions of the OMM_FeatureType, such as documents, schemas, dictionaries, equations and models. The Catalogue Service is not tied to a particular schema of a meta information standard (e.g. ISO 19115); instead it supports all application schemas for meta information (OAS-MI) that are designed according to the rules of the OMM. The goal is not to create another OGC Catalogue Specification. Due

12/76

Specification of the Catalogue Service – Overview and Architecture Outline to independence of a specific meta information standard the catalogue can be used to store meta information about services and data according the meta information schema used in the catalogue. Therefore a catalogue instance can be used as data catalogue, service registry or both if multiple meta information types are used in the catalogue instance. The multilinguality of the catalogue is dependent of the multilinguality capabilities of the meta-information schema used inside the catalogue. The intention of the Orchestra Catalogue is to provide a flexible standard, which can be adapted to the needs of the implementation. Meta information entries in catalogues represent resource characteristics that can be queried and presented for evaluation and further processing by both humans and software. The Catalogue Service supports the discovery of registered resources within an information community and returns binding information that allows a user to locate and access the resource (e.g. an URI). Services provided by a catalogue can be divided into four use cases: Search, Navigation, Publication and Collection as illustrated on the diagram below: ud OA_Catalogue - Purpose ov erv iew

Catalogue Publication

Catalogue Search

Catalogue Client

Catalogue Collection

Catalogue Nav igation

Diagram 1: Catalogue use cases These use cases should not be confused with the meta information purposes defined in D 3.3.1. However the catalogue is related to the different meta information purposes from D 3.3.1 as well. The catalogue is related to two kinds of meta-information: 1. Meta information included in a catalogue: The main purpose of meta information managed by the catalogue will be meta information for the discovery purpose. This does not exclude the managing of meta information regarding other purposes. The meta information is managed with meta information types in the catalogue representing a meta information standard, for example structured according to an Orchestra meta information schema (OAS-MI), other schemas (e.g. OGC or UDDI) or structures for semantic information (e.g. RDF for OWL). 2. Meta information offered by the catalogue: A catalogue instance will offer meta information through its capabilities. The capabilities of the catalogue service can concern many purposes (e.g. Data Access and Service Invocation). Thus the catalogue provides five interfaces, as described in the following sections.

3.2

Service Specification Summary This service type specification of the Catalogue Service is comprised of the following interfaces that are defined in separate interface type specifications: •


The following interfaces are specified as integral part of this service in chapter 6, 7, 8 and 9: •

The Catalogue Search Interface Type:

13/76

Specification of the Catalogue Service – Overview and Architecture Outline The use case search is providing means for searching information in the catalogue: The client asks the catalogue capabilities for the available catalogue entry types. Each entry type is associated with a meta information type and its corresponding query languages. With this information the client can query the catalogue entry type with the appropriate query language. •

The Catalogue Publication Interface Type: The use case publication is responsible for including, updating and deleting meta information in the catalogue. It is pushing information into the catalogue. So the purpose publication provides operations for filling the catalogue. The needed meta information could be created in the catalogue client with some kind of meta information editor, in which the user is specifying the meta information about resources he wants to register in the catalogue, or be collected with the purpose collection.

ud OA_Catalogue - Publication - purpose ov erv iew MetaInformation Editor

include, update and delete catalogue entries

The OA Catalogues wants to store meta information for the Discovery purpose. This type of meta information must be created from the resources in the Orchestra Source Systems. But be aware: 1. Other kinds of meta information exist, which does not belong into a catalogue. 2. Other kinds of meta information than Discovery might exist, we may want to include in a catalogue later on.

OA Catalogue Serv ice

Diagram 2: Catalogue purpose publication •

The Catalogue Collection Interface Type: The use case collection provides operations, which are helpful for the automatic update of catalogue content in difference to the purpose publication, which just fills the catalogue with given content. It is pulling meta information into the catalogue. The operations in this purpose should be able to be triggered from the outside of the catalogue and it should be possible to define a periodic update from the catalogue content. The operations in this interface needs to use other means or services, which are responsible for creating the meta information which is going to be stored in the catalogue. This will be meta information with the main purpose discovery collected from several sources holding data or services structured according to different meta information types the catalogue is able to handle.

14/76

Specification of the Catalogue Service – Overview and Architecture Outline ud OA_Catalogue - Collection - purpose ov erv iew

The catalogue needs meta information for the primarily for the discovery purpose. How this meta information looks like might be different for different catalogue instances. An example: one catalogue might be only interested in storing information necessary for retrieving documents another might want to add some information about the content of the document. So we need a service or several services who are responsible for creating the appropriate kind of meta information, which can be stored into the catalogue.

Orchestra Source System w ith Documents

Orchestra Source System - DB The resources for which the meta information should be collected are stored in different Orchestra Source Systems with different schemas.

«extract information»

«extract information» Orchestra Source System - Web Serv ice

Serv ice for obtaining meta information



Orchestra Source System w ith ...

collecting meta information

The OA Catalogues wants to store meta information for the Discovery purpose. This type of meta information must be created from the resources in the Orchestra Source Systems. But be aware: 1. Other kinds of meta information exist, which does not belong into a catalogue. 2. Other kinds of meta information than Discovery might exist, we may want to include in a catalogue later on.

OA Catalogue Serv ice

Diagram 3: Catalogue purpose collection

•

The Catalogue Semantic Interface Type: The CatalogueSemanticInterface provides semantic extensions for the search in a catalogue. Using ontologies given user requests can be expandend leading to more catalogue search results.

•

The Catalogue Management Interface Type: The CatalogueManagementInterface provides operations for the user influenced configuration of cascading catalogue scenarios. cd OA_Catalogue - Serv ice - Ov erv iew ServiceCapabilities OA_CatalogueServ ice +


15/76

Specification of the Catalogue Service – Overview and Architecture Outline Diagram 4: Class Diagram of the Service Interface cd OA_Catalogue - Discov ery - Ov erv iew

Catalogue Search

«realize» «Interface» OA_CatalogueSearchInterface + + + +

getMetaInformation(OA_GetMetaInformationRequest) : OA_GetMetaInformationResponse getMetaInformationType(OA_GetMetaInformationTypeRequest) : OA_GetMetaInformationTypeResponse getQueryDomain(OA_GetQueryDomainRequest) : OA_GetQueryDomainResponse search(OA_SearchRequest) : OA_SearchResponse

«realize» ServiceCapabilities OA_CatalogueServ ice +


Diagram 5: Class Diagram of the OA_CatalogueSearchInterface cd OA_Catalogue - Publication - Ov erv iew


«realize» «Interface» OA_CataloguePublicationInterface + + +

createMetaInformation(OA_CreateMetaInformationRequest) : OA_PublicationMetaInformationResponse deleteMetaInformation(OA_DeleteMetaInformationRequest) : OA_PublicationMetaInformationResponse setMetaInformation(OA_SetMetaInformationRequest) : OA_PublicationMetaInformationResponse



Diagram 6: Class Diagram of the OA_CataloguePublicationInterface

16/76

Specification of the Catalogue Service – Overview and Architecture Outline cd OA_Catalogue - Collection - Ov erv iew «Interface» OA_CatalogueCollectionInterface + +

collectMetaInformation(OA_CollectMetaInformationRequest) : OA_PublicationMetaInformationResponse collectMetaInformationPeriodic(OA_CollectMetaInformationPeriodicRequest) : OA_PublicationMetaInformationResponse



Diagram 7: Class Diagram of the OA_CatalogueCollectionInterface cd Interfaces «Interface» Catalogue Serv ice Types::OA_CatalogueSemanticInterface + +

improveQuery(OA_ImproveQueryRequest) : OA_ImproveQueryResponse activateOntology(OA_ActivateOntologyRequest) : OA_ActivateOntologyResponse

«realize» «Interface» Catalogue Serv ice Types::OA_CatalogueServ ice +

getCapabilities(OA_GetCapabilitiesRequest) : OA_ActivateCatalogueResponse

Diagram 8: Class Diagram of the OA_CatalogueSemanticInterface class Interfaces

«interface» Catalogue Ser v ice Types:: OA_CatalogueHarv estingInterface +

harvest(Harvest) : HarvestResponse real ize

«interface» Catalogue Serv ice Type s::OA_CatalogueServ ice +

getCapabilities(OA_GetCapabilitiesRequiest) : OA_CatalogueCapabilities

Diagram 9: Class Diagram of the OA_CatalogueHarvestingInterface

17/76

Specification of the Catalogue Service – Overview and Architecture Outline cd Catalogue Management Interface «Interface» Catalogue Serv ice Types::OA_CatalogueManagementInterface + + + +

activateCatalogue(OA_ActivateCatalogueRequest) : OA_ActivateCatalogueResponse setCatalogue(OA_SetCatalogueRequest) : OA_SetCatalogueResponse getCatalogue(OA_GetCatalogueRequest) : OA_GetCatalogueResponse deleteCatalogue(OA_DeleteCatalogueRequest) : OA_DeleteCatalogueResponse

«realize»

«Interface» Catalogue Serv ice Types::OA_CatalogueServ ice +


Diagram 10: Class Diagram of the OA_CatalogueManagementInterface

18/76

Specification of the Catalogue Service – Context of the Catalogue Service

4 4.1

Context of the Catalogue Service Relations to Standards Due to the fact that multiple catalogue standards are existing (e.g. OGC Catalogue Specification V2.0 or UDDI), the goal of this abstract specification is not to support a single standard. Another goal is the realisation of a semantic search in the catalogue. Thus we are going to define an abstract specification, which will be able to be extended by specific interface views to well known standards in the implementation specification. Available standards are: • OGC Catalogue Service Specification – OGC 04-021-r3: The OGC Catalogue Service Specification, widely accepted in the geospatial world, specifies interfaces for searching and publishing descriptive information about data and services (The specification uses the reference OGC CSW). In addition, several application profiles are available refining the standard with implementation specifications for specific meta-information schemas (e.g. OGC ISO19115/ISO19119 Application Profile for CSW 2.0) • UDDI - UDDI Version 3.0.2: The goal of the Universal Description, Discovery, and Integration (UDDI) protocol is to define standard methods for publishing and discovering services of a SOA. UDDI, developed by the Organization of Advancement Structured Information Standards (OASIS), is used as a Web Service registry. Used standards: • The operation harvest of the OGC Catalogue Services Specification – OGC 04-021-r3 has been directly used in the Catalogue Harvesting Interface. The Catalogue Service uses no data types which are defined in other standards. See also Relations to ORCHESTRA Application Schemas.

4.2

Relations to ongoing Initiatives and related Projects The Catalogue Service has no immediate relation to ongoing projects.

4.3

Relations to ORCHESTRA Application Schemas The Catalogue Interface Type Specification that is specified as integral part of this Service Type Specification uses Basic and OA Types that are defined in the package OAS/Basic Types, OAS/OA Types and OAS-MI/OA-MI Types of the Information Viewpoint. The Catalogue Interface Type Specification that is specified as integral part of this Service Type Specification uses OA-MI Types that are defined in the package OAS-MI/OA-MI Types of the Information Viewpoint. The Catalogue Interface Type Specification that is specified as integral part of this Service Type Specification defines new parameter types. These parameter types are defined the in the package OAS/OA Types/Catalogue. Catalogue entries are stored by the catalogue using the meta-information type associated with the catalogue entry type. These meta-information types could rely on different existing standards. The following list shows example for these standards: •

Orchestra meta information (OAS-MI), like the Service Capabilities or Service Specific Capabilities from other services containing information about data and services.

•

Other meta information according to well know standards like for example an meta information type used in IS019115 or a UDDI registry or the ebXML Registry Information Model.

19/76

Specification of the Catalogue Service – Context of the Catalogue Service •

Ontologies like for example an RDF schema for the inclusion of semantic information in a catalogue

The types of theses standards are not explicitly defined or used in this abstract Catalogue specification, since the interface of the Catalogue is independent from the meta information schema of the Catalogue.

4.4

Relations to other ORCHESTRA Service Specifications One important task of the catalogue is the storage of meta information for the purpose of discovery. Thus the catalogue service needs meta information. This meta information might be generated by other services. That means the operation collectMetaInformation could use the means of other services for meta information generation.

20/76

Specification of the Catalogue Service – Requirements

5 5.1

Requirements Security Requirements The Catalogue Service has no requirements beyond the scope of the Authentication and Authorisation Service.

5.2

Reliability Requirements The overall goal of the abstract specification is to be independent from other services. Thus the specification does not foresee the failure of connected services. Differently at the implementation level, other services could be used for the collection of the meta information. The possibility for the usage of these Services is stated in this abstract specification, but it is not reflected in the service interface, since these issues need to be handled inside the operation collectMetaInformation of the OA_CatalogueCollectionInterface.

21/76

Specification of the Catalogue Service – Specification of the Search Interface

6

Specification of the Search Interface cd OA_Catalogue - Discov ery - Ov erv iew

Catalogue Search

«realize» «Interface» OA_CatalogueSearchInterface + + + +




Diagram 11: Class Diagram of the OA_CatalogueSearchInterface The Catalogue Search interface defines or uses the following operations of inherited interfaces:

Interface Name

Operation Name

Service Capabilities

GetCapabilities

Specialisation No

Table 1: Summary of inherited Service Operations Table 1 does not list optional operations that are not used by this service. The Catalogue Search interface defines the following operations:

Operation Name

Description

search

Given a request in a given language, the catalogue returns a list of identifiers for corresponding features.

getMetaInformation

Given some identifiers of features managed by the catalogue, as returned by a previous query, this method returns the associated meta information instances.

getQueryDomain

This operation is used by catalogue clients in order to get the domain of values that are applicable to a query parameter. getQueryDomain delivers allowed values of a property of a meta information type.

getMetaInformationType

Given a list of catalogue entry types managed by the catalogue, this operation returns the associated meta information type. The meta information type can include meta information defined in an OAS_MI or could include other meta information used in well known standards.

22/76

Specification of the Catalogue Service – Specification of the Search Interface Table 2: Summary of additional Service Operations

6.1

Specification of an OAS Profile of Parameter Types used by the Catalogue Search Interface The following non basic types are used within this specification:

Name

Usage

from OAS

New

OA_SearchRequest

I

OA_Types / Catalogue Service Types

Yes

OA_SortSpec

I


Yes

OA_SortOrder

I


Yes

OA_Query

I

OA_Types

No

OA_QueryLanguage

I/O

OA_Types

No

OA_SearchType

I/O


Yes

OA_SearchResponse

O


Yes

OA_FeatureIDList

O


Yes

OA_CoreMIList

O


Yes

OA_GetMetaInformationReques t

I


Yes

OA_GetMetaInformationRespon se

O


Yes

OA_CatalogueMetaInformationT ype

I/O


Yes

OA_GetQueryDomainRequest

I


Yes

OA_GetQueryDomainResponse

O


Yes

OA_QueryParameterDomain

O


Yes

OA_Range

O


Yes

OA_ConceptualScheme

O


Yes

OA_GetMetaInformationTypeRe quest

I


Yes

23/76

Specification of the Catalogue Service – Specification of the Search Interface

OA_GetMetaInformationTypeRe sponse

O


Yes

OA_CatalogueEntryType

I/O


Yes

OA_CatalogueEntryTypeRefere nce

O


Yes

OA_UnsupportedCatalogueEntr yType

E

OA Types/ Catalogue Service Exceptions

Yes

OA_UnsupportedQueryLanguag e

E


Yes

OA_UnknownSubCatagoryId

E


Yes

OA_InvalidCursorPosition

E


Yes


E


No

OA_NoApplicableCode

E


No

OA_InternalError

E


No


6.2

Specification of the Operations Operations which have been inherited from other interfaces and which do not provide extended or limited functionality to original specification are omitted in this specification. This applies to all operations that are not marked as a specialisation in Table 1.

6.2.1

Specification of the search Operation The mandatory search operation does return a list of identifiers of corresponding features, given a request expressed in a given language.

24/76

Specification of the Catalogue Service – Specification of the search Operation cd search «DataType» Catalogue Serv ice Types: :OA_CoreMiList +

coreMI: AnyType [1..*] 0..1

«DataType» Catalogue Serv ice Types:: OA_SearchRequest + + + + + + + +

«Enumeration» Catalogue Serv ice Types:: OA_SearchType

catalogEntryTypeName: CharacterString +searchType cursorPosition: Integer [0..1] = 1 1 + iteratorSize: Integer [0..1] = 10 + query: OA_Query searchType: OA_SearchType sortSpec: OA_SortSpec[0..1] [0..1] subCategoryId: CharacterString hopCount: Integer [0..1]

+sortSpec 0..1

Hits: OA_SearchType 1 Results: OA_SearchType

+ + + + + +

cursorPosition: Integer featureIDList: OA_FeatureIDList [0..1] requestValidity: Boolean resultCount: Integer searchType: OA_SearchType oasmiList: OA_CoreMiList [0..1]

0..1 «DataType» Catalogue Serv ice Types::OA_FeatureIDList

«DataType» Now OABasic::OA_Query

sortAttName: CharacterString sortOrder: OA_SortOrder

-

language: OA_QueryLanguage query: CharacterString

+sortOrder 1

+

featureIds: CharacterString [1..*]

1

«Enumeration» Catalogue Serv ice Types:: OA_SortOrder + +

+searchType

1

«DataType» Catalogue Serv ice Types:: OA_SortSpec + +

«DataType» Catalogue Serv ice Types::OA_SearchResponse

«CodeList» Now OABasic:: OA_QueryLanguage

ascending: OA_SortOrder descending: OA_SortOrder

Diagram 12: Class diagram for search Operation

OA_SearchResponse search (OA_SearchRequest) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_UnsupportedCatalogueEntryType, OA_UnsupportedQueryLanguage, OA_UnknonwSubCategoryId, OA_InvalidCursorPosition

Overrides

not applicable The client knows:

Preconditions

o

which catalogue entry type he will search on (see getCapabilities operation);

o

which query language is available for the search on this catalogue entry type (see getCapabilities operation);

o

which value to use for query parameters (see getQueryDomain operation).

25/76

Specification of the Catalogue Service – Specification of the getMetaInformation Operation

Postconditions

The client obtains either identifiers of found results or just a result count.

Use

mandatory Name

Receives

request

Type

Use

OA_SearchRequest

mandatory

Type Returns

Description Search request Description

OA_SearchResponse

Search response

Type

Cause





OA_NoApplicableCode


OA_InternalError


OA_UnsupportedCalogueEntryType

The given catalogue entry type is not supported by this catalogue.

OA_UnsupportedQueryLanguage

The query language used in the request is not supported by the given catalogue entry type.

OA_UnknownSubCategoryId

The given sub category id is unknown from this catalogue.


The cursor position given in the request is not valid regarding the actual search results.

Throws

Table 4: Specification of the search Operation

6.2.2

Specification of the getMetaInformation Operation The mandatory getMetaInformation operation does return associated meta information instances, given some identifiers of features managed by the catalogue as returned by a previous search operation call.

26/76

Specification of the Catalogue Service – Specification of the getMetaInformation Operation cd OA_Catalogue - Discov ery - getMetaInformation «Interface» OA_CatalogueSearchInterface + + + +


«type» OA_GetMetaInformationRequest +

«type» OA_GetMetaInformationResponse

featureIDList: OA_FeatureIDList +

featureMetaInformation: OA_CatalogueMetaInformationType [1..*]

+featureIDList 1 «type» OA_FeatureIDList -

featureIds: CharacterString [1..*] {ordered}

+featureMetaInformation 1..* {ordered} «type» OA_CatalogueMetaInformationType

Contains the catalogue meta information instances for each feature identifiers.

+

27/76

oasmi: Any

Specification of the Catalogue Service – Specification of the getMetaInformation Operation cd OA_Catalogue - Discov ery - getMetaInformation «Interface» OA_CatalogueSearchInterface + + + +


«type» OA_GetMetaInformationRequest +

«type» OA_GetMetaInformationResponse

featureIDList: OA_FeatureIDList +

featureMetaInformation: OA_CatalogueMetaInformationType [1..*]

+featureIDList 1 «type» OA_FeatureIDList -

featureIds: CharacterString [1..*] {ordered}

+featureMetaInformation 1..* {ordered} «type» OA_CatalogueMetaInformationType

Contains the catalogue meta information instances for each feature identifiers.

+

oasmi: Any

Diagram 13: Class diagram for getMetaInformation Operation OA_GetMetaInformationResponse getMetaInformation (OA_GetMetaInformationRequest) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_UnknownFeatureId

Overrides

not applicable

Preconditions

The client has a list of feature ids that have been retrieved by a previous query.

Postconditions

The client obtains corresponding meta information instances for the requested feature ids. The meta information instances are retrieved from meta informations types stored in the catalogue.

Use

mandatory Name

Receives Returns

request

Type

Use

OA_GetMetaInformationRequest

mandatory

Type

Description List of feature ids. Description

28/76

Specification of the Catalogue Service – Specification of the getQueryDomain Operation

List of corresponding meta information instances.

OA_GetMetaInformationResponse Type

Throws

Cause





OA_NoApplicableCode


OA_InternalError


OA_UnknownFeatureID

A feature ID given in the list is unknown from this catalogue.

Table 5: Specification of the getMetaInformation Operation 6.2.3

Specification of the getQueryDomain Operation The mandatory getQueryDomain operation does return the domain of values that are applicable to a property of the meta-information type. It is used by catalogue clients. Using this operation, the client shall know what values are allowed for a meta-information property. A typical scenario is: 1. the client has retrieved the meta information type which he wants to query; 2. to build a request, the client needs to know what values are allowed for a particular meta information type property; 3. the client uses the getQueryDomain operation to retrieve allowed values for this property. These possible parameters or properties can depend from the meta-information schema used by the catalogue. Thus they shall be discussed in the Implementation Specification.

29/76

Specification of the Catalogue Service – Specification of the getQueryDomain Operation cd OA_Catalogue - Discov ery - getQueryDomain «Interface» OA_CatalogueSearchInterface + + + +


«type» OA_GetQueryDomainRequest +

«type» OA_GetQueryDomainResponse

parameterName: CharacterString [1..*]

+parameterDomain 0..* «type» OA_QueryParameterDomain + + + +

conceptualScheme: OA_ConceptualScheme [0..1] listOfValues: Any [0..1] {ordered} parameterName: CharacterString rangeOfValues: OA_Range [0..1]

constraints {Only one attribute between : listOfValues, rangeOfValues, conceptualScheme}

0..1 This type should be moved to the Information OAS package.

0..1

«type» OA_Range + +

«type» OA_ConceptualScheme

max: Any min: Any

+ + +

authority: OA_URI document: OA_URI name: CharacterString

Diagram 14: Class diagram for getQueryDomain Operation OA_GetQueryDomainRequest OA_InvalidParameterValue, OA_InternalError

getQueryDomain (OA_GetQueryDomainResponse) throws OA_MissingParameterValue, OA_NoApplicableCode,

Overrides

not applicable

Preconditions

The client has retrieved the meta information type using the getMetaInformationType() operation.

Postconditions

The client obtains values he can used for meta information properties when building

30/76

Specification of the Catalogue Service – Specification of the getMetainformationType Operation a search query. Use

mandatory Name

Receives

request

Type

Use

Description

OA_GetQueryDomainRequest

mandatory

List of meta information properties

Type Returns

Description List of values for the requested meta information properties.

OA_GetQueryDomainResponse Type

Throws

Cause





OA_NoApplicableCode


OA_InternalError


Table 6: Specification of the getQueryDomain Operation

6.2.4

Specification of the getMetainformationType Operation The mandatory getMetaInformationType operation does return the associated meta information type, given a list of catalogue entry types managed by the catalogue.

31/76

Specification of the Catalogue Service – Specification of the getMetainformationType Operation cd getMetaInformationType «DataType» Catalogue Serv ice Types:: OA_GetMetaInformationTypeRequest +

«DataType» Catalogue Serv ice Types::OA_GetMetaInformationTypeResponse +

catalogueEntryTypeReferences: OA_CatalogEntryTypeReference [0..*]

catalogueEntryTypeName: CharacterString [1..*]

«DataType» Catalogue Serv ice Types:: OA_CatalogEntryTypeReference + + +

metaInformationTypeReference: OA_URI name: CharacterString queryLanguage: OA_QueryLanguage [1..*]

1..* «CodeList» Now OABasic:: OA_QueryLanguage

Diagram 15: Class diagram for getMetaInformationType Operation OA_GetMetainformationTypeResponse (OA_GetMetainformationTypeRequest) OA_MissingParameterValue, OA_UnsupportedCatalogueEntryType

throws OA_NoApplicableCode,

getMetaInformationType OA_InvalidParameterValue, OA_InternalError,

Overrides

not applicable

Preconditions

The client has a list of available catalogue entry types. Those ones are declared by the capabilities of the Catalogue service.

Postconditions

The client obtains the meta information type that is used by the catalogue.

Use

mandatory

Receives

Name

Type

Use

request

OA_GetMetaInformationTypeRequest

mandatory

Type Returns

Description List of catalogue entry types.

Description

OA_GetMetaInformationTypeResponse Type

List of meta information types. Cause Operation request contains an invalid parameter value. Return the name of the parameter with invalid value.

OA_InvalidParameterValue Throws

32/76

Specification of the Catalogue Service – Specification of the getMetainformationType Operation



OA_NoApplicableCode


OA_InternalError


OA_UnsupportedCalogueEntryType


Table 7: Specification of the getMetainformationType Operation

33/76

Specification of the Catalogue Service – Specification of Parameter Types

6.3

Specification of Parameter Types This service specification does define any new OA Types. These new OA Types will become part of the OAS “OA Types”. This service specification does not define any new OT Types. This service specification does not introduce any new non-orchestra Types.

6.3.1

OA_SearchRequest Request that is sent to the search operation.

6.3.2

o

subCategoryId – (optional) Defines on which sub category in the catalogue the search must be restricted. The list of available sub catalogue ids is given by the capabilities.

o

cursorPosition, iteratorSize – (optional) The cursorPosition parameter is used to indicate at which record position the catalogue should start generating output. The default value is 1 meaning it starts at the first record in the result set. The iteratorSize parameter is used to define the maximum number of records that should be returned from the result set of a query. A default values is provided.

o

catalogEntryTypeName – name of the catalogue entry type the search must be made for. It holds a list of available catalogue entry types, which include the meta information type (typically: description of feature sets, services, …) and the associated query languages. Both are given by the capabilities.

o

hopCount – this parameter is used to control how far must be performed a query along cascading catalogues. If this parameter is not set, no cascading is allowed. If it greater than 0, then cascading is authorized. This parameter is decreased by 1 each time a cascading is performed. OA_SortSpec

Specifications of sorting instructions while performing a search. 6.3.3

OA_SortOrder Ascending or descending sort order.

6.3.4

OA_SearchType

Two different types of search can be performed: o Hits – the search just counts the number of matching results. No actual result identifier is returned. o Results – that’s the default search type: identifiers of matching results are returned by the operation. 6.3.5

OA_SearchResponse

Response that is returned by the search operation. o requestValidity – Boolean indicating if the request is valid (returned for all types of search) o cursorPosition, resultCount – Indications about the ranges of returned results. o featureIDList – List of result identifiers (returned only for Results search type). 6.3.6

OA_FeatureIDList List of feature identifiers.

34/76

Specification of the Catalogue Service – Specification of Parameter Types 6.3.7

OA_CoreMIList List of core meta-information entries to be returned via the search response. The meta-information type is flexible but to ensure interoperability the usage of Dublin Core elements for the description of the meta-information is suggested.

6.3.8

OA_GetMetaInformationRequest List of feature identifiers which the meta information instances are retrieved for.

6.3.9

OA_GetMetaInformationResponse List of meta information instances for each feature identifier. The capabilities of a catalogue instance gives the information which meta information types are handled by the catalogue.

6.3.10 OA_GetQueryDomainRequest List of meta information properties the client is looking values for. 6.3.11 OA_GetQueryDomainResponse For each meta information property, the corresponding parameter value. 6.3.12 OA_QueryParameterDomain Contains information about the type of the parameter and authorised values for a meta information property. It is either: o a list of literal values, defining for example a limited set of allowed values; o a range of values between a lower and an inner bound; o a conceptual scheme. 6.3.13 OA_ConceptualScheme Defines a document with the conceptual scheme and the corresponding authority. 6.3.14 OA_Range A range of values between a lower and inner bound. 6.3.15 OA_GetMetaInformationTypeRequest List of catalogue entry name to get the meta information type for. Available catalogue entry type names are available in capabilities. 6.3.16 OA_GetMetaInformationTypeResponse Contains the list of corresponding catalogue entry types, including the meta information type and the correspondding query languages. 6.3.17 OA_CatalogEntryType Catalogue entry types are types of entities that are served by a catalogue. Typically: feature sets, services. A catalogue entry type is associated with one and only one specific meta information type, and with a set of supported query languages. The available catalogue entry types are defined in the capabilities of the catalogue through the

35/76

Specification of the Catalogue Service – Specification of Parameter Types OA_CatalogueEntryTypeDescriptor. 6.3.18 OA_CatalogEntryTypeReference Contains a reference to the meta information schema of the catalogue. 6.3.19 OA_CatalogueMetaInformationType Contains the catalogue meta-information instances. The meta information types could include Orchestra meta information types like service common and specific capabilities. A meta information type represents a meta information standard, for example structured according to an Orchestra meta information schema (OAS-MI), other schemas (e.g. OGC or UDDI) or structures for semantic information (e.g. RDF for OWL). 6.3.20 OA_UnsupportedCatalogueEntryType The defined catalogue entry type is not supported in the meta-information schema of the catalogue. 6.3.21 OA_UnknownSubCategoryId The id used to identify sub categories in the catalogue is not valid. 6.3.22 OA_UnsupportedQueryLanguage The query language is not supported by the given catalogue entry type. 6.3.23 OA_InvalidCursorPosition The cursor position is not valid regarding the actual results.

36/76


7

Specification of the Publication Interface cd OA_Catalogue - Publication - Ov erv iew


«realize» «Interface» OA_CataloguePublicationInterface + + +




Diagram 16: Class Diagram of the OA_CataloguePublicationInterface The Catalogue Publication interface defines or uses the following operations of inherited interfaces:

Interface Name

Operation Name


GetCapabilities

Specialisation No

Table 8: Summary of inherited Service Operations Table 1 does not list optional operations that are not used by this service. The Catalogue Publication interface defines the following operations:

Operation Name

Description

createMetaInformation

This operation creates meta information in catalogue entries manages by the catalogue

setMetaInformation

This operation updates meta information in existing catalogue entries

deleteMetaInformation

This operation deletes meta information from the catalogue Table 9: Summary of additional Service Operations

37/76

Specification of the Catalogue Service – Specification of an OAS Profile of Parameter Types used by the Catalogue Publication Interface

7.1

Specification of an OAS Profile of Parameter Types used by the Catalogue Publication Interface The following non basic types are used within this specification:

Name

Usage

from OAS

New

OA_CreateMetaInformationRequest

I

OA Types / Catalogue Service Types

Yes

OA_MetaInformationSet

I


Yes

OA_CatalogueEntryType

I


Yes

OA_PublicationMetaInformationResponse

O


Yes

OA_MIElementID

O


Yes

OA_SetMetaInformationRequest

I


Yes

OA_DeleteMetaInformationRequest

I


Yes

OA_UnsupportedMetaInformationType

E


Yes


E


Yes

OA_NumberOfIDException

E


Yes

OA_UnknownFeatureId

E


Yes

OA_InternalError

E


No

OA_NoApplicableCode

E


No


E


No


E


No


7.2


38/76

Specification of the Catalogue Service – Specification of the Operations

7.2.1

Specification of the createMetaInformation Operation The optional createMetaInformation operation does push information into the catalogue. The task of this operation is to insert catalogue content into the catalogue. The operation receives the meta information to be stored. cd createMetaInformation «DataType» Catalogue Serv ice Types:: OA_CreateMetaInformationRequest + +

«DataType» Catalogue Serv ice Types:: OA_PublicationMetaInformationResponse

metaInformationSet: OA_MetaInformationSet subCategoryId: CharacterString

+ + +

deletedElements: OA_MIElementID [0..*] insertedElements: OA_MIElementID [0..*] updatedElements: OA_MIElementID [0..*]

+metaInformationSet 1 «DataType» Catalogue Serv ice Types::OA_MetaInformationSet +

resultEntries: OA_CatalogueEntryType [0..*]

0..* «DataType» Catalogue Serv ice Types::OA_CatalogueEntryType + + +

oasmi: AnyType name: CharacterString queryLanguage: OA_QueryLanguage

Diagram 17: Class diagram for createMetaInformation Operation OA_PublicationMetaInformationResponse createMetaInformation (OA_CreateMetaInformationRequest) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_UnsupportedMetaInformationType, OA_UnknownSubCategoryId

Overrides

not applicable

Preconditions

Client has elements with meta information he wants to store in the catalogue.

Postconditions

The meta information is stored in the catalogue.

Use

optional

Receives

Name

Type

39/76

Use

Description


request


Type Returns

mandatory

Request for inserting meta information into catalogue

Description


Response for updating meta information in catalogue

Type

Cause





OA_NoApplicableCode


OA_InternalError



The meta information type createMetaInformation tries to store in the catalogue is not supported by the catalogue. Information which meta information types can be stored in the catalogue are given by the capabilties of the catalogue.


The Id used to identify subcategories in the catalogue is not valid.

Throws

Table 11: Specification of the createMetaInformation Operation 7.2.2

Specification of the setMetaInformation Operation The optional setMetaInformation operation updates the catalogue content. The operation receives the meta information types to be stored.

40/76

Specification of the Catalogue Service – Specification of the Operations cd setMetaInformation «DataType» Catalogue Serv ice Types:: OA_SetMetaInformationRequest + + +


idsForUpdate: CharacterString [0..*] subCategoryId: CharacterString metaInformationSet: OA_MetaInformationSet

+ + +


+metaInformationSet 1 «DataType» Catalogue Serv ice Types:: OA_MetaInformationSet +

resultEntries: OA_CatalogueEntryType [0..*]

0..* «DataType» Catalogue Serv ice Types::OA_CatalogueEntryType + + +

oasmi: AnyType name: CharacterString queryLanguage: OA_QueryLanguage

Diagram 18: Class diagram for setMetaInformation Operation OA_PublicationMetaInformationResponse (OA_SetMetaInformationRequest) throws OA_MissingParameterValue, OA_NoApplicableCode, OA_UnsupportedMetaInformationType, OA_UnknownFeatureID, OA_UnknownSubCategoryId

setMetaInformation OA_InvalidParameterValue, OA_InternalError, OA_NumberOfIDException,

Overrides

not applicable

Preconditions

Client has elements with meta information he wants to update in the catalogue.

Postconditions

The meta information is updated in the catalogue.

Use

optional Name

Receives

Returns

request

Type

Use

OA_SetMetaInformationRequest Type

M

Description Request for updating meta information in the catalogue Description

41/76



Response for updating meta information in catalogue

Type

Throws

Cause





OA_NoApplicableCode


OA_InternalError



The meta information type createMetaInformation tries to store in the catalogue is not supported by the catalogue. Information which meta information types can be stored in the catalogue are given by the capabilities of the catalogue.

OA_UnknownFeatureID

The Id used to identify elements in the catalogue is not valid.

OA_NumberOfIDException

The number of ids specified in the request does not match the number of meta information types.


The id used to identify catalogue subcategories is not valid.

Table 12: Specification of the setMetaInformation Operation 7.2.3

Specification of the deleteMetaInformation Operation The optional deleteMetaInformation operation does delete catalogue content from the catalogue.

42/76

Specification of the Catalogue Service – Specification of the Operations cd OA_Catalogue - Publication - deleteMetaInformation «Interface» OA_CataloguePublicationInterface

+ + +


«type» OA_PublicationMetaInformationResponse

«type» OA_DeleteMetaInformationRequest + +

+ + +

delete: OA_Query subCategoryId: CharacterString


Diagram 19: Class diagram for deleteMetaInformation Operation OA_PublicationMetaInformationResponse (OA_DeleteMetaInformationRequest) throws OA_MissingParameterValue, OA_NoApplicableCode, OA_UnknownSubCategoryId

deleteMetaInformation OA_InvalidParameterValue, OA_InternalError,

Overrides

not applicable

Preconditions

Client has elements with meta information he wants to delete from the catalogue.

Postconditions

The meta information is deleted from the catalogue.

Use

optional Name

request

Type


Receives

Type

Use

Description

mandatory

Request for deleting meta information in the catalogue

Description

OA_PublicationMetaInformationResponse Returns Type

Response for updating meta information in catalogue Cause Operation request contains an invalid parameter value. Return the


43/76

Specification of the Catalogue Service – Specification of Parameter Types name of the parameter with invalid value.



OA_NoApplicableCode


OA_InternalError



The Id used to identify sub categories in the catalogue is not valid.

Table 13: Specification of the deleteMetaInformation Operation

7.3


7.3.1


This request contains the set of meta information which is going to be included into the catalogue. •

insert – set of meta information to be inserted into catalogue

•

subCategoryId – (optional) identifier for subcategory in catalogue. Information about subcategories can be retrieved from the capabilities (OA_CatalogueCapabilities)

7.3.2

OA_PublicationMetainformationResponse Response after the update of the catalogue content. Contains included, updated or deleted elements.

7.3.3

•

deletedElements (mandatory)

•

insertedElements (mandatory)

•

updatedElements (mandatory)

OA_MIElementID Contains id of catalogue entry.

7.3.4

OA_MetaInformationSet Array of entries to be included in the catalogue.

44/76

Specification of the Catalogue Service – Specification of Parameter Types 7.3.5

OA_SetMetaInformationRequest

This request contains the set of meta information which is going to be updated in the catalogue. •

update – set of meta information to be inserted into catalogue

•

idsForUpdate – identifiers for catalogue entries to be updated

•

subCategoryId – (optional) identifier for subcategory in catalogue.

7.3.6


This request contains information for the removal of catalogue entries. •

delete – Constraint to decide, which entries are going to be removed from the catalogue

•

subCategoryId – (optional) identifier for subcategory in catalogue.

7.3.7

OA_UnsupportedMetaInformationType The meta-information type createMetaInformation tries to store in the catalogue is not supported by the catalogue. Information about valid meta-information types are given by the catalogue specific capabilities.

7.3.8

OA_UnknownFeatureId The feature id is not used by the catalogue.

7.3.9

OA_NumberOfIdException The number of ids specified in the request does not match the number of meta-information types.

45/76

Specification of the Catalogue Service – Specification of an OAS Profile of Parameter Types used by the Catalogue Publication Interface

8

Specification of the Collection Interface cd OA_Catalogue - Collection - Ov erv iew «Interface» OA_CatalogueCollectionInterface + +

collectMetaInformation(OA_CollectMetaInformationRequest) : OA_PublicationMetaInformationResponse collectMetaInformationPeriodic(OA_CollectMetaInformationPeriodicRequest) : OA_PublicationMetaInformationResponse



Diagram 20: Class Diagram of the OA_CatalogueCollectionInterface The Catalogue Collection interface defines or uses the following operations of inherited interfaces:

Interface Name

Operation Name

Specialisation


GetCapabilities

No

AsynchronousInteraction

invokeAsync

No

AsynchronousInteraction

abort

No

Table 14: Summary of inherited Service Operations Table 1 does not list optional operations that are not used by this service. The Catalogue Collection interface defines the following operations:

Operation Name

Description

collectMetaInformation

This operation given one reference to a source of meta information, collects meta information for the discovery purpose using the means from other services. This operation can be called directly in a synchronous way or asynchronously using the interface for asynchronous operation support.

collectMetaInformationPeriodic

This operation gives the possibility for periodic collection of meta information from the given source. It should only be called asynchronously.

Table 15: Summary of additional Service Operations

8.1

Specification of an OAS Profile of Parameter Types used by the Catalogue Publication Interface The following non basic types are used within this specification:

Name

Usage

46/76

from OAS

New


OA_CollectMetaInformationRequest

I


Yes

OA_CollectMetaInformationPeriodicRequest

I


Yes

OA_CollectType

I


Yes

OA_CollectTypeEnum

I


Yes

OA_CatalogueEntryTypeReference

I


OA_DateTime

I

OA Types

No


O


Yes

OA_MIElementID

O


Yes

OA_UnsupportedCatalogueEntryType

E


Yes

OA_IntervalNotSupported

E


Yes

OA_InternalError

E


No

OA_NoApplicableCode

E


No


E


No


E


No


8.2


47/76

Specification of the Catalogue Service – Specification of the collectMetaInformation Operation

8.2.1

Specification of the collectMetaInformation Operation The optional collectMetaInformation operation does pull meta information into the catalogue. The operation receives one reference of a source of meta information and a catalogue entry type. This catalogue entry type is the type in which the meta information is going to be stored in the catalogue. Inside collectMetaInformation other means or services are used for the actual creation of meta information for the discovery purpose from the specified meta information source. The resulting meta information is stored into the catalogue. This operation can be called directly in a synchronous way or asynchronous using the interface for asynchronous operation support. cd collectMetaInformation «DataType» Catalogue Serv ice Types:: OA_CollectMetaInformationRequest + + + + +


catalogueEntryType: OA_CatalogEntryTypeReference collectType: OA_CollectType operationRequest: CharacterString sourceReference: OA_URI subCategoryId: CharacterString

+ + +


0..* 1 «DataType» Catalogue Serv ice Types:: OA_CatalogEntryTypeReference + + +

«DataType» Catalogue Serv ice Types:: OA_MIElementID

«DataType» Catalogue Serv ice Types:: OA_CollectType


+ +

name: CharacterString type: OA_CollectTypeEnum

+

id: CharacterString

1 «Enumeration» Catalogue Serv ice Types:: OA_CollectTypeEnum + +

dataset: OA_CollectTypeEnum operation: OA_CollectTypeEnum

Diagram 21: Class diagram for collectMetaInformation Operation OA_PublicationMetaInformationResponse (OA_CollectMetaInformationRequest) throws OA_MissingParameterValue, OA_NoApplicableCode, OA_UnsupportedCatalogueEntryType

collectMetaInformation OA_InvalidParameterValue, OA_InternalError,

Overrides

not applicable

Preconditions

The client should know from getCapabilities, which meta information types can be stored in the catalogue.

Postconditions

Due to the request of the client meta information was collected from the source system and included in the catalogue.

48/76

Specification of the Catalogue Service – Specification of the collectMetaInformationPeriodic Operation

Use

optional Name

Receives

metainformationRequest

Type


Use

Description

mandatory

Request for collecting meta information

Type Returns

Description


Response for collecting meta information

Type

Cause




Operation request does not include a parameter value. Return the name of the missing parameter.

OA_NoApplicableCode


OA_InternalError



It is not possible to deliver the requested CatalogueEntryType from the source. .

Throws

Table 17: Specification of the collectMetaInformationPeriodic Operation 8.2.2

Specification of the collectMetaInformationPeriodic Operation The optional collectMetaInformationPeriodic operation does receive one reference of a source of meta information, the catalogue entry type and the time interval between two collections and a date to stop the collect. The catalogue entry type is the type in which the meta information is going to be stored into the catalogue. The operation uses the same services as collectMetaInformation for retrieving meta information for the discovery purpose from the specified meta information source. The operation is processes periodically according to the given intervals ant stored the resulting meta information into the catalogue. The operation should be called asynchronously using the interface for asynchronous operation support.

49/76

Specification of the Catalogue Service – Specification of the collectMetaInformationPeriodic Operation cd collectMetaInformationPeriodic «DataType» Catalogue Serv ice Types:: OA_CollectMetaInformationPeriodicRequest + + + + + + +


catalogueEntryType: OA_CatalogEntryTypeReference collectType: OA_CollectType interval: DateTime [2] sourceReference: OA_URI stopDate: DateTime subCategoryId: CharacterString operationRequest: CharacterString

+ + +


1 «DataType» Catalogue Serv ice Types:: OA_CatalogEntryTypeReference + + +

«DataType» Catalogue Serv ice Types:: OA_CollectType


+ +

name: CharacterString type: OA_CollectTypeEnum

1 «Enumeration» Catalogue Serv ice Types:: OA_CollectTypeEnum + +

dataset: OA_CollectTypeEnum operation: OA_CollectTypeEnum

Diagram 22: Class diagram for collectMetaInformationPeriodic Operation OA_PublicationMetaInformationResponse collectMetaInformationPeriodic (OA_CollectMetaInformationPeriodicRequest) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_UnsupportedCatalogueEntryType, OA_IntervalNotSupported

Overrides

not applicable

Preconditions

The client should know from getCapabilities, which meta information types can be stored in the catalogue.

Postconditions

Due to the request of the client meta information was collected from the source system and included in the catalogue.

Use

optional Name

Receives

metainformationRequest

Type OA_CollectMetaInformation PeriodicRequest

50/76

Use

Description

mandatory

Request for collecting meta information

Specification of the Catalogue Service – Specification of the collectMetaInformationPeriodic Operation

Type Returns

Description

OA_PublicationMetaInformationResponse Type

Response for collecting meta information Cause





OA_NoApplicableCode


OA_InternalError



It is not possible to deliver the requested CatalogueEntryType from the source. .

OA_IntervalNotSupported

The source system does not support the collection of meta information at the given times.

Throws

Table 18: Specification of the collectMetaInformationPeriodic Operation

8.3


51/76

Specification of the Catalogue Service – OA_CollectMetaInformationRequest 8.3.1


Request that is sent to collect meta information. •

catalogueEntryType– (mandatory) meta information type according to data in source.(see 5.1.4)

•

sourceReference – (mandatory) reference to a source of meta information. This can be either a source system holding data or a service. OA_CollectMetaInformationRequest is expecting a subclass of ServiceCapabilities. For the access to data in a source system it could be a FeatureAccessService used within source system integration or another access service. For the access to service other kinds of OA or OT services are possible.

•

subCategoryId – (optional) identifier for sub category in catalogue. Information about sub categories can be retrieved from the capabilities of the catalogue.

•

operationRequest – (mandatory) request for operation to be called for collection meta information.

•

collectType – (mandatory) identifier for type of collection.

8.3.2

OA_CollectMetaInformationPeriodicRequest

Request that is sent to collect meta information. •

catalogueEntryType– (mandatory) meta information type according to data in source (see 5.1.4).

•

sourceReference – (mandatory) reference to a source of meta information. This can be either a source system holding data or a service. OA_CollectMetaInformationRequest is expecting a subclass of ServiceCapabilities. For the access to data in a source system it could be a FeatureAccessService used within source system integration or another access service. For the access to service other kinds of OA or OT services are possible.

•

subCategoryId – (optional) identifier for sub category in catalogue. Information about sub categories can be retrieved from the capabilities of the catalogue.

•

operationRequest – (mandatory) request for operation to be called for collection meta information.

•

collectType – (mandatory) identifier for type of collection (e.g collection from another service (e.g via a getCapabilities operation) or collection via a reference to a meta information set).

•

interval – (mandatory) An interval for the repeated collection of meta information. The interval between two collection events is defined with two time stamps.

•

stopDate – (mandatory) Date for stopping the periodic execution of collectMetaInformation

8.3.3

OA_CollectType Identifier for a type of collection (e.g. collection from another service or collection via a reference to a meta information set).

8.3.4

OA_CollectTypeEnum Valid values are “dataset” or “operation”.

8.3.5

OA_IntervalNotSupported The accessed source does not support the collection of meta-information at the given times.

52/76

Specification of the Catalogue Service – OA_IntervalNotSupported

9

Specification of the Semantic Interface cd Interfaces «Interface» Catalogue Serv ice Types::OA_CatalogueSemanticInterface + +

improveQuery(OA_ImproveQueryRequest) : OA_ImproveQueryResponse activateOntology(OA_ActivateOntologyRequest) : OA_ActivateOntologyResponse

«realize» «Interface» Catalogue Serv ice Types::OA_CatalogueServ ice +


Diagram 23: Class Diagram of the OA_CatalogueSemanticInterface The Catalogue Navigation interface defines or uses the following operations of inherited interfaces:


Operation Name

Specialisation

GetCapabilities

No

Table 19: Summary of inherited Service Operations Table 1 does not list optional operations that are not used by this service. The Catalogue Semantic interface defines the following operation:

Operation Name

Description

improveQuery

ImproveQuery return semantically connected keywords related to a given search request.

activateOntology

ActivateOntology activates the given ontology as default ontology for the usage in the improveQuery operation. Table 20: Summary of additional Service Operations

9.1

Specification of an OAS Profile of Parameter Types used by the Catalogue Semantic Interface The following non basic types are used within this specification:

Name

Usage

53/76

from OAS

New

Specification of the Catalogue Service – Specification of the improveQuery Operation

OA_ImproveQueryRequest

I


Yes

OA_SearchRequest

I


No

OA_SC_Config

I


Yes

OA_ActivateOntologyRequest

I


Yes

OA_ImproveQueryResponse

O


Yes

OA_SC_ImproveQueryResponse

O


Yes

OA_ActivateOntologyResponse

O


Yes

OA_UnsupportedOntologyAnalyzer

E

OA Types / Catalogue Service Exception

Yes

OA_UnknownOntology

E


Yes


E


No


E


No


E


No


E


No

OA_InternalError

E


No

OA_NoApplicableCode

E


No


E


No


E


No


9.2


9.2.1

Specification of the improveQuery Operation The optional improveQuery operation returns semantically connected keywords related to a given search request.

54/76

Specification of the Catalogue Service – Specification of the improveQuery Operation cd improv eQuery «DataType» Catalogue Serv ice Types:: OA_Improv eQueryRequest + +

«DataType» Catalogue Serv ice Types:: OA_Improv eQueryResponse

scConfig: OA_SC_Config [0..1] searchRequest: OA_SearchRequest

+

scResponse: OA_SC_ImproveQueryResponse [0..1]

0..1 1

«DataType» Catalogue Serv ice Types:: OA_SC_Improv eQueryResponse

«DataType» Catalogue Serv ice Types::OA_SC_Config + + + +

childrenLevel: Integer [0..1] parentLevel: Integer [0..1] analyzer: OA_SC_OntologyAnalyzer [0..1] relationLevel: Integer [0..1]

+

newKeywords: OA_SC_KeywordType [0..*]

0..* «DataType» Catalogue Serv ice Types:: OA_SC_Keyw ordType

0..1 + +

«Enumeration» Catalogue Serv ice Types:: OA_SC_OntologyAnalyzer + + +

keyword: CharacterString queryable: CharacterString

is: OA_SC_OntologyAnalyzer oas: OA_SC_OntologyAnalyzer jena: OA_SC_OntologyAnalyzer

Diagram 24: Class diagram for improveQuery Operation OA_ImproveQueryResponse[] improveQuery (OA_ImproveQueryRequest) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_UnsupportedOntologyAnalyzer, OA_InvalidCursorPosition, OA_UnknownSubCategoryId, OA_UnsupportedQueryLanguage, OA_UnsupportedCatalogueEntryType

Overrides

not applicable

Preconditions

None.

Use

optional

Postconditions

Connected keywords are available. Name

Receives Returns

request

Type

Use

OA_ImproveQueryRequest Type

Description

mandatory

Request for improveQuery

Description

55/76

Specification of the Catalogue Service – Specification of the activateOntology Operation

request

OA_ImproveQueryRequest Type

Cause





OA_NoApplicableCode


OA_InternalError


OA_UnsupportedOntologyAnalyzer

The component for the improvement of the query is not supported.


The cursor position given in the request is not valid regarding the actual search results.


The given sub category id is unknown from this catalogue.


The query language used in the request is not supported by the given catalogue entry type.



Throws

Table 22: Specification of the improveQuery Operation 9.2.2

Specification of the activateOntology Operation The optional activateOntology operation activates a given ontology for the default use in the semantic interface. Ontologies can be managed by the Catalogue Service using the Ontology Access Interface. cd activ ateOntology «DataType» Catalogue Serv ice Types:: OA_Activ ateOntologyRequest +

ontologyName: CharacterString

«DataType» Catalogue Serv ice Types:: OA_Activ ateOntologyResponse +

acknowledgement: Boolean

Diagram 25: Class diagram for activateOntology Operation

56/76

Specification of the Catalogue Service – Specification of the activateOntology Operation OA_ActivateOntologyResponse OA_InvalidParameterValue, OA_InternalError

activateOntology (OA_ActivateOntologyRequest) throws OA_MissingParameterValue, OA_NoApplicableCode,

Overrides

not applicable

Preconditions

Catalogue Service has ontology management. This can be realized using the Ontology Access Service.

Use

optional

Postconditions

Ontology is activated

Receives

Name

Type

request

OA_ActivateOntology

Use mandatory

Type Returns

Description

Description

response

OA_ActivateOntologyResponse Type

Throws

Cause





OA_NoApplicableCode


OA_InternalError


OA_UnknownOntology

Ontology to be activated is unknown.

Table 23: Specification of the activateOntology Operation

9.3

Request for activateOntology


57/76

Specification of the Catalogue Service – OA_ActivateOntologyRequest 9.3.1

OA_ActivateOntologyRequest The request type for activate ontology contains the name of the ontology as identifier.

9.3.2

OA_ActivateOntologyResponse The activate ontology response contains an acknowledgement parameter.

58/76

Specification of the Catalogue Service – OA_ActivateOntologyResponse

10 Specification of the Catalogue Management Interface cd Catalogue Management Interface «Interface» Catalogue Serv ice Types::OA_CatalogueManagementInterface + + + +

activateCatalogue(OA_ActivateCatalogueRequest) : OA_ActivateCatalogueResponse setCatalogue(OA_SetCatalogueRequest) : OA_SetCatalogueResponse getCatalogue(OA_GetCatalogueRequest) : OA_GetCatalogueResponse deleteCatalogue(OA_DeleteCatalogueRequest) : OA_DeleteCatalogueResponse

«realize»

«Interface» Catalogue Serv ice Types::OA_CatalogueServ ice +


Diagram 26: Class Diagram of the OA_CatalogueManagementInterface The Catalogue Management interface defines or uses the following operations of inherited interfaces:


Operation Name GetCapabilities

Specialisation No

Table 24: Summary of inherited Service Operations Table 1 does not list optional operations that are not used by this service. The Catalogue Management interface defines the following operations:

Operation Name

Description

activateCatalogue

ActivateCatalogue activates the given catalogue for the usage in a cascading catalogue scenario.

setCatalogue

SetCatalogue includes a new catalogue in the list of catalogues available for the creation of a cascading catalogue.

getCatalogue

GetCatalogue returns access information about a catalogue contained in the list of catalogues available for the creation of a cascading catalogue.

deleteCatalogue

DeleteCatalogue deletes a catalogue from the list of catalogues available for the creation of a cascading catalogue.

59/76

Specification of the Catalogue Service – OA_ActivateOntologyResponse Table 25: Summary of additional Service Operations

10.1 Specification of an OAS Profile of Parameter Types used by the Catalogue Semantic Interface The following non basic types are used within this specification:

Name

Usage

from OAS

New

OA_ActivateCatalogueRequest

I


Yes

OA_SetCatalogueRequest

I


Yes

OA_GetCatalogueRequest

I


Yes

OA_DeleteCatalogueRequest

I


Yes

OA_ActivateCatalogueResponse

O


Yes

OA_SetCatalogueResponse

O


Yes

OA_GetCatalogueResponse

O


Yes

OA_DeleteCatalogueResponse

O


Yes

OA_DoubleCSIndetifier

E


No

OA_UnknownCatalogue

E


No

OA_InternalError

E


No

OA_NoApplicableCode

E


No


E


No


E


No


10.2 Specification of the Operations Operations which have been inherited from other interfaces and which do not provide extended or limited functionality to original specification are omitted in this specification. This applies to all operations that are not marked as a specialisation in Table 1.

60/76

Specification of the Catalogue Service – Specification of the activateCatalogue Operation 10.2.1 Specification of the activateCatalogue Operation The optional activateCatalogue operation activates or deactivates the given catalogue for the usage in a cascading catalogue scenario. cd activ ateCatalogue «DataType» Catalogue Serv ice Types:: OA_Activ ateCatalogueRequest + +

«DataType» Catalogue Serv ice Types:: OA_Activ ateCatalogueResponse

catalogueName: CharacterString activate: Boolean

+ +

catalogueName: CharacterString activated: Boolean

Diagram 27: Class diagram for activateCatalogue Operation OA_ActivateCatalogueResponse activateCatalogue (OA_ActivateCatalogueRequest) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_UnknownCatalogue

Overrides

not applicable

Preconditions

Catalogue to be activated was included in catalogue list via setCatalogue operation.

Use

optional

Postconditions

Catalogue is activated. Name

Receives

request

Type

Use

OA_ActivateCatalogueRequest Type

Returns

Description

mandatory

Request for activateCatalogue

Description

response

OA_ActivateCatalogueResponse Type

Cause





OA_NoApplicableCode


OA_InternalError


Throws

61/76

Specification of the Catalogue Service – Specification of the setCatalogue Operation

Catalogue is not known in catalogue list.

OA_UnknownCatalogue

Table 27: Specification of the activateCatalogue Operation 10.2.2 Specification of the setCatalogue Operation The optional setCatalogue operation includes the given catalogue into the list of available catalogues for a cascading catalogue scenario. cd setCatalogue «DataType» Catalogue Serv ice Types:: OA_SetCatalogueRequest + +

«DataType» Catalogue Serv ice Types:: OA_SetCatalogueResponse

catalogueName: CharacterString catalogueUrl: OA_URI

+


«DataType» Catalogue Serv ice Exceptions:: OA_DoubleCSIdentifier + +

catalogueName: CharacterString catalogueUrl: OA_URI

Diagram 28: Class diagram for setCatalogue Operation OA_SetCatalogueResponse OA_InvalidParameterValue, OA_DoubleCSIdentifier

setCatalogue (OA_SetCatalogueRequest) throws OA_MissingParameterValue, OA_NoApplicableCode,

Overrides

not applicable

Preconditions

None

Use

optional

Postconditions

Given catalogue is available in list of catalogues for the creation of an cascading catalogue scenario. Name

Receives

request

Type

Use

OA_SetCatalogue

mandatory

Type Returns

Description Request for setCatalogue

Description

response

OA_SetCatalogueResponse Type

Cause





Throws

62/76

Specification of the Catalogue Service – Specification of the getCatalogue Operation

OA_NoApplicableCode


OA_InternalError


OA_DoubleCSIdentifier

Catalogue was already included in list of catalogues.

Table 28: Specification of the setCatalogue Operation 10.2.3 Specification of the getCatalogue Operation The optional getCatalogue operation return access information about the specified catalogue from the list of available catalogues for a cascading catalogue scenario. cd getCatalogue «DataType» Catalogue Serv ice Types:: OA_GetCatalogueRequest +

«DataType» Catalogue Serv ice Types:: OA_GetCatalogueResponse

catalogueName: CharacterString

+

catalogueUrl: CharacterString

Diagram 29: Class diagram for getCatalogue Operation OA_GetCatalogueResponse OA_InvalidParameterValue, OA_UnknownCatalogue

getCatalogue (OA_GetCatalogueRequest) throws OA_MissingParameterValue, OA_NoApplicableCode,

Overrides

not applicable

Preconditions

Catalogues are available in list of catalogues for the creation of a cascading catalogue scenario.

Use

optional

Postconditions

Information about request catalogue has been returned. Name

Receives

request

Type

Use

OA_GetCatalogue

mandatory

Type Returns

Description Request for getCatalogue

Description

response

OA_GetCatalogueResponse Type

Cause Operation request contains an invalid parameter value. Return the name of the parameter with


63/76

Specification of the Catalogue Service – Specification of the deleteCatalogue Operation invalid value.



OA_NoApplicableCode


OA_InternalError


OA_UnkwownCatalogue

Catalogue is not included in list of catalogues.

Table 29: Specification of the getCatalogue Operation 10.2.4 Specification of the deleteCatalogue Operation The optional deleteCatalogue operation deletes the given catalogue form the list of available catalogues for a cascading catalogue scenario. cd deleteCatalogue

+

«DataType» Catalogue Serv ice Types:: OA_DeleteCatalogueRequest

«DataType» Catalogue Serv ice Types:: OA_DeleteCatalogueResponse


+


«DataType» Catalogue Serv ice Exceptions:: OA_Unknow nCatalogue +


Diagram 30: Class diagram for deleteCatalogue Operation OA_DeleteCatalogueResponse OA_InvalidParameterValue, OA_UnknownCatalogue

deleteCatalogue (OA_DeleteCatalogueRequest) throws OA_MissingParameterValue, OA_NoApplicableCode,

Overrides

not applicable

Preconditions

Catalogues are available in list of catalogues for the creation of a cascading catalogue scenario.

Use

optional

Postconditions

Catalogue is deleted from list.

Receives Returns

Name

Type

request

OA_DeleteCatalogue

Use

Description

mandatory

Type

Request for deleteCatalogue

Description

64/76

Specification of the Catalogue Service – OA_ActivateCatalogueRequest

response

OA_DeleteCatalogueResponse Type

Throws

Cause





OA_NoApplicableCode


OA_InternalError


OA_UnkwownCatalogue

Catalogue is not included in list of catalogues.

Table 30: Specification of the deleteCatalogue Operation

10.3 Specification of Parameter Types This service specification does define any new OA Types. These new OA Types will become part of the OAS “OA Types”. This service specification does not define any new OT Types. This service specification does not introduce any new non-orchestra Types. 10.3.1 OA_ActivateCatalogueRequest The request type for activate catalogue contains the name of the catalogue as identifier and a boolean parameter to define the action activate or deactivate. 10.3.2 OA_ActivateCatalgueResponse The activate catalogue response contains an acknowledgement parameter and the catalogue name. 10.3.3 OA_SetCatalogueRequest The set catalogue request contains the name of the catalogue and its access url. 10.3.4 OA_SetCatalogueResponse The set catalogue response contains an acknowledgement parameter. 10.3.5 OA_GetCatalogueRequest The get catalogue request contains the name of the catalogue.

65/76

Specification of the Catalogue Service – OA_GetCatalogueResponse 10.3.6 OA_GetCatalogueResponse The get catalogue request contains the url as access point to the catalogue. 10.3.7 OA_DeleteCatalogueRequest The delete catalogue request contains the name of the catalogue as identifier. 10.3.8 OA_DeleteCatalgueResponse The delete catalogue response contains an acknowledgement parameter.

66/76

Specification of the Catalogue Service – Specification of an OAS Profile of Parameter Types used by the Catalogue Harvesting Interface

11 Specification of the Harvesting Interface class Interfaces

«interface» Catalogue Ser v ice Types:: OA_CatalogueHarv estingInterface +

harvest(Harvest) : HarvestResponse real ize

«interface» Catalogue Serv ice Type s::OA_CatalogueServ ice +

getCapabilities(OA_GetCapabilitiesRequiest) : OA_CatalogueCapabilities

Diagram 31: Class Diagram of the OA_HarvestingInterface The Catalogue Harvesting interface defines or uses the following operations of inherited interfaces:


Operation Name

Specialisation

GetCapabilities

No

Table 31: Summary of inherited Service Operations Table 1 does not list optional operations that are not used by this service. The Catalogue Harvesting interface defines the following operation:

Operation Name

Description Harvest collects meta-information from given resources and includes it into the catalogue. It returns information about the harvested resources.

harvest


11.1 Specification of an OAS Profile of Parameter Types used by the Catalogue Harvesting Interface The following non basic types are used within this specification:

Name Harvest

Usage I

67/76

from OAS from OGC CSW

New Yes


Source

I

from OGC CSW

Yes

ResourceType

I

from OGC CSW

Yes

ResourceFormat

I

from OGC CSW

Yes

HarvestInterval

I

from OGC CSW

Yes

ResponseHandler

I

from OGC CSW

Yes

ExternalRessourceUrl

I


Yes

HarvestResponse

O

from OGC CSW

Yes

Acknowledgement

O

from OGC CSW

Yes

TransactionResponse

O

from OGC CSW

Yes

TranscactionSummary

O

from OGC CSW

Yes

InsertResult

O

from OGC CSW

Yes


E


No


E


No

OA_NoApplicableCode

E


No

OA_UnknownCatalogue

E


No

OA_InternalError

E


No


11.2 Specification of the Operations Operations which have been inherited from other interfaces and which do not provide extended or limited functionality to original specification are omitted in this specification. This applies to all operations that are not marked as a specialisation in Table 1. 11.2.1 Specification of the harvest Operation The optional harvest operation collects meta-information from given resources and includes it into the catalogue. It returns information about the harvested resources.

68/76

Specification of the Catalogue Service – Specification of the Operations class harv est

«DataType» Harv estResponse

«DataType» Harv est + + + + +

+ +

Source: OA_URI ResourceType: CharacterString ResourceFormat: CharacterString HarvestInterval: Ch aracterString [0..1] ResponseHandler: OA_URI [0..*]

transactionResponse: TransactionResponse [0..1] acknowledgement: Ac knowledgement [0..1]

«DataType» TransactionResponse + +

transactionSummary: TransactionSummary insertResult: In sertResult [0..*]

0..* «DataType» TransactionSummary + + +

totalInserted: int totalUpdated: int totalDeleted: int

Diagram 32: Class diagram for harvest Operation HarvestResponse[] harvest (Harvest) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_UnknownCatalogue

Overrides

not applicable

Preconditions

Resources for harvesting must be available.

Use

optional

Postconditions

New catalogue entries have been created. Name

Receives

request

Type Harvest

Use

Description

mandatory

Request for harvest

Type Returns

Description

request

Harvest Type



69/76




OA_NoApplicableCode


OA_InternalError

A problem occurred in the runtime environment (e.g. out of memory) Catalogue not known

OA_UnknownCatalogue

Table 34: Specification of the harvest Operation

11.3 Specification of Parameter Types This service specification does define any new OA Types. These new OA Types will become part of the OAS “OA Types”. This service specification does not define any new OT Types. 11.3.1 Harvest The request type for the harvesting operation. 11.3.2 Source The URL from which the resource is retrieved (see OGC CSW ). 11.3.3 ResourceType URL to schema of resource being harvested (see OGC CSW ). 11.3.4 ResourceFormat Media type indicating the format of being harvested: “application/xml” (see OGC CSW ). 11.3.5 HarvestInterval Interval specifying time between harvest attempts (see OGC CSW ). 11.3.6 ResponseHandler Endpoint to which the response shall be forwarded when the harvest operation has been completed (see OGC CSW ) 11.3.7 ExternalResourceUrl URL to additional meta-information needed to fulfil requirements of catalogue meta-information schema. 11.3.8 HarvestResponse In case of an available ResponseHandler, and Acknowledgement is sent immediately, otherwise a TransactionResponse is sent (see OGC CSW ).

70/76

Specification of the Catalogue Service – Specification of Parameter Types 11.3.9 Acknowledgement Acknowledgement message. 11.3.10 TransactionResponse Contains TransactionSummary (see OGC CSW ). 11.3.11 TransactionSummary Response containing number of inserted/updated/deleted entries in catalogue (see OGC CSW ).

12 Specification of the Service specific Capabilities As part of ORCHESTRA D3.3.2 a meta-information schema for services is defined acting as a default OAS-MI for service capabilities. OA_MI_CapabilitiesDocument includes both the common capabilities and the service specific capabilities. While the common capabilities are defined in the specification of the Service Capabilities Interface, the specific capabilities have to be specialized in each service specification. The schema for service specific capabilities defined here is explicitly divided into the following schema sections:

Section Name

CatalogueCapabilities

Section Contents Includes information about the specific capabilities of the Catalogue Service, containing information about the meta-information stored in the catalogue, like structure of meta-information and according query languages.

Table 35: Sections of the service specific capabilities Name

Definition

Data Type


subCategoryID

Available sub categories in catalogue. A sub category is an optional element in the catalogue to restrict searches to a part of the catalogue.

CharacterString

0 - * / optional

entryTypeDescriptor

Type for defining the meta-information and query languages a catalogue is able to handle

OA_Catalogue EntryTypeDescriptor

1-*/ mandatory

cascadingCS

Type for defining possible cascading catalogue scenarios

OA_Cascadin gCS

0 - * / optional

Table 36: Attributes of the service specific capabilities of section CatalogueCapabilities

71/76

Specification of the Catalogue Service – Specification of additional OA Types cd CatalogueSpecCap «DataType» ::OA_CascadingCS + +

«DataType» Catalogue Serv ice Types::OA_CatalogueCapabilities

availableCatalogues: CharacterString [0..*] 0..1 activeCatalogue: CharacterString [0..*]

+ + +

entryTypeDescriptor: OA_CatalogueEntryTypeDescriptor [1..*] cascadingCS: OA_CascadingCS [0..1] subCategoryId: CharacterString

+entryType 1..* «DataType» Catalogue Serv ice Types::OA_CatalogueEntryTypeDescriptor + + +

nameOfMetaInformationType: CharacterString queryLanguageInformation: OA_QueryLanguageInformation [1..*] referenceOfMetaInformationType: OA_URI

1..* «DataType» Catalogue Serv ice Types:: OA_QueryExtension + +

queryables: CharacterString [1..*] sortQueryables: CharacterString [0..*]

«DataType» Catalogue Serv ice Types:: OA_QueryLanguageInformation 0..1

+ +

queryExtension: OA_QueryExtension queryLanguage: OA_QueryLanguage

1 «DataType» Catalogue Serv ice Types::OA_OGCFilterExtension +

«CodeList» Now OABasic::OA_QueryLanguage

filterCapabilities: OA_OGCFilterCapabilities

0..1 «DataType» Catalogue Serv ice Types:: OA_OGCFilterCapabilities +

filterCapabilities: OA_URI

Diagram 33: Class diagram for capabilities

12.1 Specification of additional OA Types This service specification does define any new OA Types. These new OA Types will become part of the OAS “OA Types”. This service specification does not define any new OT Types. This service specification does not introduce any new non-orchestra Types. This subchapter holds types used for the service specific capabilities of the Catalogue Service and types used in several interfaces of the Catalogue Service.

72/76

Specification of the Catalogue Service – Specification of additional OA Types 12.1.1 OA_CatalogueCapabilities Holds service specific capabilities of Catalogue Service: •

subCategoryId. A sub category is an optional element in the catalogue to restrict searches to a part of the catalogue.

•

entryTypeDescriptor. See 6.4.2.

•

cascadingCS. Defines a list of available catalogues for the creation of cascaded catalogue scenarios and defined a list of activated catalogues of a cascaded catalogue scenario.

12.1.2 OA_CatalogueEntryTypeDescriptor Type for defining the meta-information and query languages the catalogue is able to handle. •

nameOfMetaInformationType – (mandatory) name of a meta-infirmation type the catalogue is able to handle

•

referenceOfMetaInformationType – (mandatory) reference to the schema of the meta information type the catalogue is able to handle. This includes information structured according to an Orchestra meta information schema (OAS-MI), other schemas (e.g. OGC or UDDI) or structures for semantic information (e.g. RDF for OWL)

•

queryLanguageInformation – (mandatory)

12.1.3 OA_QueryLanguageInformation The query languages which are supported by the catalogue. They must be able to query the supported catalogueEntryTypes. The type OA_QueryLanguageInformation holds the OA_QueryLanguage and an optional QueryExtension type specifying the filter capabilities of the query language. 12.1.4 OA_QueryExtension Specific query extension types can be derived from this type. The basic class contains the queryables of the Catalogue Service. 12.1.5 OA_OGCFilterExtension A type holding information about OGC Filter Encoding query possibilities 12.1.6 Other extension types derived from OA_QueryExtension A type holding information about a specific query language. 12.1.7 OA_UnknownFeatureId The id used to identify meta-information elements in the catalogue is not valid.

73/76

Specification of the Catalogue Service – Known Issues and Limitations of Search Interface

13 Known Issues and Limitations 13.1 Known Issues and Limitations of Search Interface Issus for the OA_CatalogueSearchInterface: a. Is there a need to restrict the returned meta information types like in OGC (brief, summary, full)? b. It is still unclear, where the list of parameters for getQueryDomain comes from. The available parameters depend from meta information types used in the catalogue.

13.2 Known Issues and Limitations of Specific Capabilities Since the OA_CatalogueServiceInterface is the base interface of the Catalogue Service, the common issues and limitations of the Catalogue will be discussed here. Issues related to a specific interface will be discussed in the according interface chapter.

74/76

Specification of the Catalogue Service – Appendix A: Abstract Test Suite (normative)

14

Appendix A: Abstract Test Suite (normative) When creating an implementation specification of the Catalogue Service, the “Rules for Implementation Specifications of ORCHESTRA Services” defined in chapter 9.2.2.3 and the “Rules for the Service Mapping to a given Platform” of the RM-OA shall be obeyed. In addition, the following tests shall be performed to ensure conformance of an implementation specification to the platform-independent specification of the Catalogue Service: 1. Syntactical Conformance •


•


•


•




Additional conformance checks that are specifically to the Catalogue Service are not required.

75/76

Specification of the Catalogue Service – Appendix B: UML Models (normative)

15 Appendix B: UML Models (normative) 15.1 XMI Model The XMI Models of this service specification can be downloaded from a to be defined place (SANY or ORCHESTRA?) The XMI Model contains only the parameters specified in this service specification. Additional parameters used by this service can be found in the XMI Models of the following interface or service specifications: •


76/76




Specification of the Coordinate Operation Service

Revision

129

[3.2/ 2.2.2]

Specification of the Coordinate Operation Service – Document Control Page


Specification of the Coordinate Operation Service

Creator

Cruz, Alberto J.

Subject


Description

This document defines an abstract and platform independent formal interface specification of the Coordinate Operation Service.

Publisher


Contributor

Tebar, Carlos

Atos Origin

Cruz, Alberto J.

Atos Origin

Calero, Aitor

Atos Origin

Date

2006-05-09

Type

Text

Format

application/msword

Atos Origin

Identifier Source

Not applicable

Language

en-GB.

Relation

None

Coverage



D3.4.4


WP3.4



Version number

3.1 / 2.0.6

Date

2007-09-05

Modified by

Calero, Aitor

Atos Origin

Comments Status

Draft WP leader accepted SP leader accepted

229

Specification of the Coordinate Operation Service – Document Control Page

Technical supervisor accepted Quality checked Project coordinator accepted Action requested

to be revised by partners involved in the preparation of the deliverable for approval of the WP leader for approval of the SP leader for approval of the Technical Supervisor for approval of the Quality Manager for approval of the Project Coordinator Deadline for action:

329

Specification of the Coordinate Operation Service – Revision History


Date

0.1 / 1.6

2005-12-02

0.2 / 1.7

2006-01-31

Sections changed

Description Working draft

All

Updated to template v1.7 Draft completed. To be reviewed

1.0 / 2.0.3

2006-05-15

All

Updated to template v2.0

1.1 / 2.0.4

2006-05-24

All

Updated to template v2.0.4

1.3 / 2.0.4

2006-05-30

All

Changes to the OAS and imported types. OA_InvalidNewCRS has been removed

1.4 / 2.0.4

2006-07-28

3, 6

Added checkOperation operation and OA_CoordinateOperationInformation type

1.5 / 2.0.4

2006-08-03

6, 8

OAS_ types renamed to OA_ Appendix B content removed.

1.6 / 2.0.4

2006-09-06

1, 2

Minor changes and corrections

3.0 / 2.0.4

2007-02-27

All

Specification rewritten to offer an interface more similar to the OGC WCTS draft version 0.3.0

3.1 / 2.2.1

2007-09-05

All

Updated to new specification template

3.1 / 2.2.1

2007-11-05

All

Updated to new specification template

429§

Specification of the Coordinate Operation Service – Table of Contents

Table of Contents 1Foreword...........................................................................................................................................................9 2Conventions....................................................................................................................................................10 2.1Abbreviations ...........................................................................................................................................10 2.2Terms and definitions...............................................................................................................................10 2.3UML Notation ...........................................................................................................................................10 2.4Conformance ...........................................................................................................................................10 2.4.1Conformance to the OMM.................................................................................................................10 2.4.2Conformance of Implementation Specifications................................................................................10 3Overview and Architecture Outline .................................................................................................................10 3.1Role and Scope of the Coordinate Operation Service.............................................................................10 3.2Service Specification Summary ...............................................................................................................11 4Context of the Coordinate Operation Service.................................................................................................12 4.1Relations to Standards.............................................................................................................................12 4.2Relations to ongoing Initiatives and related Projects ...............................................................................12 4.3Relations to ORCHESTRA Application Schemas ...................................................................................12 4.4Relations to other ORCHESTRA Service Specifications.........................................................................12 5Requirements ................................................................................................................................................13 5.1Security Requirements.............................................................................................................................13 5.2Reliability Requirements ..........................................................................................................................13 6Specification of the Coordinate Operation Interface ......................................................................................14 6.1Specification of an OAS Profile of Parameter Types used by the Coordinate Operation Interface ........15 6.2Specification of the Operations ................................................................................................................17 6.2.1Specification of the transform Operation...........................................................................................18 6.2.2Specification of the isTransformable Operation ................................................................................19 6.2.3Specification of the getTransformation Operation.............................................................................20 6.2.4Specification of the describeTransformation Operation ....................................................................21 6.2.5Specification of the describeCRS Operation.....................................................................................22 6.2.6Specification of the describeMethod Operation ................................................................................22 6.3Specification of Parameter Types ............................................................................................................23 6.3.1OA_IsTransformableResponse.........................................................................................................23 6.3.2OA_IsTransformableProblem............................................................................................................23 6.3.3OA_NoInputData ...............................................................................................................................24

529§

Specification of the Coordinate Operation Service – Table of Contents 6.3.4OA_TransformException...................................................................................................................24 6.3.5OA_InvalidArea .................................................................................................................................24 6.3.6OA_SC_CRS.....................................................................................................................................24 7Specification of the Service specific Capabilities ...........................................................................................25 8Known Issues and Limitations ........................................................................................................................27 9Appendix A: Abstract Test Suite (normative) .................................................................................................28 10Appendix B: UML Models (normative)..........................................................................................................29 10.1XMI Model ..............................................................................................................................................29

629§

Specification of the Coordinate Operation Service – Tables and Diagrams

Tables Table 1: Summary of inherited Service Operations..........................................................................................14 Table 2: Summary of additional Service Operations ........................................................................................14 Table 3: Referenced OA Types ........................................................................................................................15 Table 4: Specification of the transform Operation ............................................................................................19 Table 5: Specification of the isTransformable Operation .................................................................................20 Table 6: Specification of the getTransformation Operation..............................................................................21 Table 7: Specification of the describeTransformation Operation .....................................................................22 Table 8: Specification of the describeCRS Operation ......................................................................................22 Table 9: Specification of the describeMethod Operation .................................................................................23 Table 10: Sections of the service specific capabilities .....................................................................................25 Table 11: Attributes of the service specific capabilities of section supportedTransformation..........................25 Table 12: Attributes of the service specific capabilities of the section supportedMethod ................................25 Table 13: Attributes of the service specific capabilities of the section sourceCRS..........................................25 Table 14: Attributes of the service specific capabilities of the section targetCRS ...........................................26 Table 15: Attributes of the service specific capabilities of the section featureAbilities....................................26

Diagrams Diagram 1: Class Diagram of the Coordinate Operation Service.....................................................................11 Diagram 2: Class Diagram of the Coordinate Operation Service Interface .....................................................14 Diagram 3: Types from the Service Capabilities Interface inherited of the OA Basic Service .........................16 Diagram 4: Common Exceptions inherited from the OA Basic Service ...........................................................17

729§

Specification of the Coordinate Operation Service – Tables and Diagrams Diagram 5: Exceptions inherited from the Service Capabilites Interface of the OA Basic Service ..................17

829§

1

Foreword This document is an abstract specification of the Coordinate Operation Service (COS) service and is based on the Template for the abstract Specification of ORCHESTRA Service Types version 2.2. It replaces the specification version 1.6. A replacement was required due to reflect the changes in the service interface. The interface of the service has been changed from the previous versions to be more similar to the OGC Web Coordinate Transformation Service at its current draft stage. This document includes one annex: Appendix A: Abstract Test Suite (normative) mandatory.

2

Conventions

2.1

Abbreviations The abbreviations used in this document are defined in chapter 4.1 of the RM-OA, except for the following abbreviated terms:

2.2

•

COS

Coordinate Operation Service

•

CRS

Coordinate Reference System

•

WCTS

Web Coordinate Operation Service


2.3


2.4

Conformance

2.4.1


2.4.2


3 3.1

Overview and Architecture Outline Role and Scope of the Coordinate Operation Service The Coordinate Operation Service changes coordinates on features from one coordinate reference system to another (based on a 1-1 relationship). This includes operations on datum and projection. A datum is used as basis for defining a coordinate reference system and it specifies how the coordinate system is related to the earth. Examples are WGS84 and NAD1950. A projection is a method to depict 3dimensional data (the shape of the earth) in 2 dimensions. There are two principal variants of coordinate operation:

1. Coordinate conversion: An operation of coordinates that does not include any change of Datum. Examples of a coordinate conversion are a map projection between projected coordinates and geographic coordinates, or change of units such as from radians to degrees or feet to meters. 2. Coordinate transformation: An operation on coordinates that usually includes a change of Datum. The parameters of a coordinate transformation are empirically derived from data containing the coordinates of a series of points in both coordinate reference systems. This operation introduces errors, hence allowing derivation of error (or accuracy) estimates for the transformation.

3.2

Service Specification Summary This service type specification of the Coordinate Operation Service is comprised of the following inter-

faces that are defined in separate interface type specifications: •


•

The Coordinate Operation Service Interface The following interfaces are specified as integral part of this service in chapter 6:

•

The Coordinate Operation Service Interface Type cd Coordinate Operation Serv ice «Interface» ServiceCapabilities +

getCapabilities(OA_GetCapabilitiesRequest) : OA_GetCapabilitiesResponse

«interface» CoordinateOperationService + + + + + +

transform(OA_FeatureCollection, CharacterString, CharacterString, CharacterString, CharacterString, CharacterString) : OA_FeatureCollection isTransformable(CharacterString, CharacterString, CharacterString, CharacterString, CharacterString) : OA_IsTransformableResponse getTransformation(CharacterString, CharacterString) : CharacterString describeTransformation(CharacterString) : CharacterString describeCRS(CharacterString) : OA_SC_CRS describeMethod(CharacterString) : CharacterString

Diagram 1: Class Diagram of the Coordinate Operation Service

4

Context of the Coordinate Operation Service

4.1

Relations to Standards Related Standards

4.2

ISO 19107, Spatial Schema

ISO 19111, Spatial Referencing by coordinates

ISO 19112, Geographic information – Spatial referencing by geographic identifiers

OGC 04-046r3 The OpenGIS Abstract Specification Topic 2: Spatial referencing by coordinates

OGC 05-013 Web Coordinate Transformation Service (WCTS) draft Implementation specification

Relations to ongoing Initiatives and related Projects The Coordinate Operation Service has no immediate relation to ongoing projects.

4.3

Relations to ORCHESTRA Application Schemas The Coordinate Operation Service specification uses Basic and OA Types that are defined in the package OAS/Basic Types, OAS/OA Types and OAS-MI/OA-MI Types of the Information Viewpoint. The Coordinate Operation Service specification uses OA-MI Types that are defined in the package OAS-MI/OA-MI Types of the Information Viewpoint. The Coordinate Operation Service specification defines new parameter types. These parameter type are defined in the package OA Types/Coordinate Operation Service Types, OA Types/Coordinate Operation Service Exceptions, OAS-MI/OA-MI Types.

4.4

Relations to other ORCHESTRA Service Specifications The Coordinate Operation Service could be invoked by any OA service or OT service that need to handle information in different coordinate reference system or need to transform between then. Typical examples of such services are the Map and Diagram Service or the Feature Access Service.

5 5.1

Requirements Security Requirements The Coordinate Operation Service has no requirements beyond the scope of the Authentication and Authorization Service.

5.2

Reliability Requirements The Coordinate Operation Service has no special reliability requirements.

6

Specification of the Coordinate Operation Interface This interface specification of the Coordinate Operation Service extends the following interfaces: 3. The Service Capabilities Interface of the RM-OA Service Specification cd Coordinate Operation Serv ice «Interface» ServiceCapabilities +


«interface» CoordinateOperationService + + + + + +


Diagram 2: Class Diagram of the Coordinate Operation Service Interface The Coordinate Operation interface defines or uses the following operations of inherited interfaces:

Interface Name

Operation Name


GetCapabilities

Specialisation No

Table 1: Summary of inherited Service Operations Table 1 does not list optional operations that are not used by this service.

The Coordinate Operation Service interface defines the following additional operations:

Operation Name

Description

transform

Transform the requested features between different CRS

isTransformable

Informs about the capability of the service to perform a requested transformation

getTransformation

Provides the definition of a transformation between two CRS

describeTransformation

Provides the definition of an identified transformation

describeCRS

Provides the definition of a coordinate reference systems

describeMethod

Provides the definition of an operation method Table 2: Summary of additional Service Operations

6.1

Specification of an OAS Profile of Parameter Types used by the Coordinate

Operation Interface The following non basic types are used within this specification:

Name

Usage

from OAS

New


O

OA Types

No


I

OA Types

No


E


No


E


No


E


No


E


No

OA_NoApplicableCode

E


No

OA_InternalError

E


No


I&O

OA Types

No

OA_IsTransformableResponse

O

OA Types

Yes

OA_SC_CRS

I&O

OA Types

Yes

OA_NoInputData

E


Yes

OA_TransformException

E


Yes

OA_InvalidArea

E


Yes


cd Serv iceCapabilities types «Interface» ServiceCapabilities +


«type» OA Types::OA_GetCapabilitiesRequest + + +

«type» OA Types::OA_CapabilitiesDocument

acceptFormats: OA_MimeT ype [0..*] {ordered} acceptSpecVersions: CharacterString [0..*] {ordered} sections: OA_CapabilitiesSections [0..1]

+ + + +

capabilitySections: Binary format: OA_MimeType schemaName: OA_CapabilitiesSchema version: CharacterString

constraints {capabilitySections formatted according to indicated format} {capabilitySections structured according to indicated schema} «type» OA Types::OA_CapabilitiesSections + +

schemaName: OA_CapabilitiesSchema [0..1] schemaSections: CharacterString [0..*] = all For schema OAS_MI_Services the value of capabilitySections shall be structured according to type OA_MI_Service_Capabilities Possible schemas are e.g.: «type» OA Types:: OA_CapabilitiesSchema +

identifier: OA_URI

OAS_MI_Services ISO19119 OWS_Common_1.0 OWL-S_1.1 WSMO_Grounding ...

Diagram 3: Types from the Service Capabilities Interface inherited of the OA Basic Service

cd OA Basic Serv ice Exceptions cd Common Exceptions «type» OA_AbstractException + +


+


«type» OA_UnsupportedOperation + +

«type» OA_Inv alidPermission

operationName: CharacterString serviceT ype: OA_ServiceT ype

«type» OA_MissingParameterValue +

parameterName: CharacterString

+ +

operationName: CharacterString serviceType: OA_ServiceT ype

«type» OA_Inv alidParameterValue + +

«type» OA_InternalError +

location: OA_CodeLocation [0..*] {ordered}

«type» OA_NoApplicableCode

parameterName: CharacterString value: CharacterString

«type» OA_CodeLocation + + + +

lineNumber: Integer operationName: CharacterString serviceT ype: OA_ServiceType sourceFileName: CharacterString

Diagram 4: Common Exceptions inherited from the OA Basic Service

cd OA Basic Serv ice Exceptions cd Serv iceCapabilities exceptions «type» OA_AbstractException + +


+


«type» OA_VersionNegotiationFailed +

supportedVersions: CharacterString [1..*]

«type» OA_UnsupportedSchema +

supportedSchemas: OA_CapabilitiesSchema [0..*]

Diagram 5: Exceptions inherited from the Service Capabilites Interface of the OA Basic Service

6.2

Specification of the Operations Operations which have been inherited from other interfaces and which do not provide extended or lim-

ited functionality to original specification are omitted in this specification. This applies to all operations that are not marked as a specialisation in Table 1.

cd Coordinate Operation Serv ice «interface» CoordinateOperationService + + + + + +

6.2.1


Specification of the transform Operation The mandatory transform operation does coordinate transformations on features between two different coordinate reference systems. Since it is feasible in a feature collection to include elements referenced in different CRS, only those that match the the sourceCRS will be transformed.

Overrides

not applicable

Preconditions

None

Post conditions

None

Use

Mandatory

Receives

Name

Description


optional

Features to be transformed

reference

CharacterString

optional

Reference to features to be transformed

sourceCRS

CharacterString

optional

Identifier of the source CRS

targetCRS

CharacterString

optional

Identifier of the target CRS

transformation

CharacterString

optional

Identifier of the desired transformation

optional

Identifier of the desired interpolation method which should be used to transform coverages

CharacterString

Type OA_TransformResponse

Throws

Use

features

method

Returns

Type

Type

Description Output with the transformed features. Cause





OA_NoApplicableCode


OA_InternalError


OA_InvalidArea

Parts of the input data are outside of the domain of validity of the transformation

OA_NoInputData

No input data (feature or reference) was available.

OA_TransformException

Error while performing the transformation

Table 4: Specification of the transform Operation Notes: The optional parameters SourceCRS-TargetCRS pair and transformation are mutually exclusive, but at least one of them must be provided. The parameters features and reference are mutually exclusive, at least one of them must be provided. 6.2.2

Specification of the isTransformable Operation The optional isTransformable operation informs about the capability of a service implementation to transform features between two CRS.

Overrides

not applicable

Preconditions

None

Post conditions

None

Use

Optional

Receives

Name

Type

Use

Description

sourceCRS

CharacterString

optional

targetCRS

CharacterString

optional

transformation

CharacterString

optional

Identifier of the desired transformation

method

CharacterString

optional

Identifier of the desired interpolation method

interpolationMethod

CharacterString

optional

List of interpolation methods that could be used to transform coverages.

Identifier of the source CRS Identifier of the target CRS

Returns

Type

Description

OA_IsTransformableResponse Throws

True or false along with the reason when the response is false

Type

Cause





OA_NoApplicableCode


OA_InternalError


Table 5: Specification of the isTransformable Operation Notes: The parameters SourceCRS-TargetCRS pair, transformation and method are mutually exclusive, at least of them must be provided.

6.2.3

Specification of the getTransformation Operation The optional getTransformation provides the definition of the transformation between a source CRS and a target CRS

Overrides

not applicable

Preconditions

None

Post conditions

None

Use

Optional

Receives

Name

Type

Description

sourceCRS

CharacterString

mandatory

Identifier of the sourceCRS

targetCRS

CharacterString

mandatory

Identifier of the targetCRS

Returns

Type

Description definition of coordinate operation that can transform coordinates from the sourceCRS to the targetCRS

CharacterString Throws

Use





OA_NoApplicableCode


OA_InternalError


Table 6: Specification of the getTransformation Operation 6.2.4

Specification of the describeTransformation Operation The optional describeTransformation operation provides the definition of an identified transformation.

Overrides

not applicable

Preconditions

None

Post conditions

None

Use

Optional

Receives

Name transformation


Returns

Type

mandatory

Description Identifier of the transformation Description

Definition of the identified Transformation

CharacterString Throws

Use

Type

Cause





OA_NoApplicableCode


OA_InternalError


Table 7: Specification of the describeTransformation Operation 6.2.5

Specification of the describeCRS Operation The optional describeCRS operation provides the definition of an identified CRS.

Overrides

not applicable

Preconditions

None

Post conditions

None

Use

Optional

Receives

Name crs


Returns

Use mandatory

Type

Identifier of the CRS Description

OA_SC_CRS Throws

Description

Definition of the identified CRS Type

Cause





OA_NoApplicableCode


OA_InternalError


Table 8: Specification of the describeCRS Operation 6.2.6

Specification of the describeMethod Operation The optional describeMethod operation provides the definition of an identified operation method.

Overrides

not applicable

Preconditions

None

Post conditions

None

Use

Optional

Receives

Name method


Returns


Throws

Use mandatory

Description Identifier of the method Description

Definition of the operation method Type

Cause





OA_NoApplicableCode


OA_InternalError


Table 9: Specification of the describeMethod Operation

6.3

Specification of Parameter Types This service specification does define new OA Types. These new OA Types will become part of the OAS::OA Types and OAS/OA Types/Exception Types.

6.3.1

OA_IsTransformableResponse Holds information about the capability of perform a coordinate transformation.

6.3.2

OA_IsTransformableProblem When a OA_IsTransformableResponse is false, OA_IsTransformableProblem holds the reason. cd Coordinate Operation Serv ice Types «enumeration» OA_IsTransformableProblem

«type» OA_IsTransformableResponse +

6.3.3

transformable: boolean

enum + sourceCRS: +problem + type: + targetCRS: + interpolationmethod: + other:

OA_NoInputData Parts of the input data are outside of the domain of validity of the transformation

6.3.4

OA_TransformException Informs about a problem while performing a coordinate transformation

6.3.5

OA_InvalidArea Parts of the input data are outside of the domain of validity of the transformation

cd Coordinate Operation Serv ice Exceptions «type» OA_AbstractException + +


+


«type» OA_Inv alidArea

6.3.6

OA_SC_CRS The definition of a CRS cd Coordinate Operation Serv i... «type» OA_SC_CRS +

definition: CharacterString

«type» OA_NoInputData

«type» OA_TransformException

Specification of the Coordinate Operation Service –

7

Specification of the Service specific Capabilities As part of ORCHESTRA D3.3.2 a meta-information schema for services is defined acting as a default OAS-MI for service capabilities. OA_MI_CapabilitiesDocument includes both the common capabilities and the service specific capabilities. While the common capabilities are defined in the specification of the Service Capabilities Interface, the specific capabilities have to be specialized in each service specification.

Section Name

Section Contents

supportedTransformation

Coordinate operations which the service can perform

supportedMethod

Operation methods which the service can use

sourceCRS

CRS that the service accepts as sourceCRS

targetCRS

CRS that the service accepts as targetCRS

featureAbilities

Feature handling abilities of this service Table 10: Sections of the service specific capabilities

Name

supportedTransformation

Definition Lists the coordinate operations which the service can perform

Data Type Sequence

Multiplicity and Use 0..* / optional

Table 11: Attributes of the service specific capabilities of section supportedTransformation

Name

supportedMethod

Definition Lists the operation methods that the service can use.

Data Type Sequence


Table 12: Attributes of the service specific capabilities of the section supportedMethod

Name

sourceCRS

Definition Lists the CRS that the service accepts as sourceCRS values

Data Type Sequence

Multiplicity and Use 1..* / mandatoryl

Table 13: Attributes of the service specific capabilities of the section sourceCRS


Name

Definition Lists the CRS that the service accepts as targetCRS values

targetCRS

Data Type Sequence

Multiplicity and Use 1..* / mandatory

Table 14: Attributes of the service specific capabilities of the section targetCRS

Name

featureAbilities

Definition Information about the feature handling abilities of the service

Data Type Sequence


Table 15: Attributes of the service specific capabilities of the section featureAbilities


8

Known Issues and Limitations There are currently no issues and limitations known that may to be resolved in a platform specific specification.

Specification of the Coordinate Operation Service – Appendix A: Abstract Test Suite (normative)

9

Appendix A: Abstract Test Suite (normative) When creating an implementation specification of the Coordinate Operation Service, the “Rules for Implementation Specifications of ORCHESTRA Services” defined in chapter 9.2.2.3 and the “Rules for the Service Mapping to a given Platform” of the RM-OA shall be obeyed. In addition, the following tests shall be performed to ensure conformance of an implementation specification to the platform-independent specification of the Coordinate Operation Service:

Syntactical Conformance





Semantical Conformance


Additional conformance checks that are specifically to the Coordinate Operation Service are not required.

Specification of the Coordinate Operation Service – Appendix B: UML Models (normative) (mandatory or not applicable)

10 Appendix B: UML Models (normative) 10.1 XMI Model The XMI Models of this interface specification can be downloaded from the OGC Portal under the following URL: https://portal.opengeospatial.org/index.php?m=projects&a=view&project_id=140&tab=2&artifact_id=22 237




Specification of the Document Access Service

Revision

1/26

[1.9.1 / 2.2.2]

Specification of the Document Access Service – Document Control Page


Specification of the Document Access Service

Creator

Dihé, Pascal

Subject


Description

This document defines an abstract and platform independent formal specification of the Document Access Service, which supports the access to a document of any type.

Publisher


Contributor

Dihé, Pascal

Environmental Informatics Group

Fischer, Julian


Hofmann, Thomas


Ma, Wenjie


Berlinghoff, Thomas


Schmieder, Martin

Fraunhofer IITB

Hilbring, Desiree

Fraunhofer IITB


Date

2006-02-06

Type

Text

Format

application/msword

Identifier


Source

Not applicable

Language

en-GB.

Relation

none

Coverage



D3.4.3


WP3.4


2006-06-30


2006-06-30

Audience


Version number

1.9.1 / 2.2.2

Date

2007-10-08

2/26

Specification of the Document Access Service – Document Control Page

Modified by

Ma, Wenjie


Comments Status


Action requested


3/26

Specification of the Document Access Service – Revision History


Date

Sections changed

Description st

0.3

2005-07-22

all

1 intermediate release

0.5

2005-07-26

all

n/a

1.0

2005-08-01

all

1 public release

1.2

2005-08-30

1.1.3.3, 1.1.5.1, 1.1.4, 1.1.2.2

incorporated TU’s comments

1.3 / 1.6

2005-11-24

all

Update to Template v1.6, incorporated comments of KA Meeting

1.4 / 1.6

2005-12-06

all

Aligned to the Feature Access Service Specification

1.4.1 / 1.6

2006-01-05

all

Some minor corrections

1.5 / 1.6

2006-01-12

all

incorporated MS’s comments

1.5.1 / 1.7

2006-02-06

all

Add Document Control Page, section Conformance and Annex D: Abstract test suite, changes on headline in some sections.

1.5.2 / 1.7

2006-02-16

1.2, 5

Update of diagrams and added missing function descriptions.

1.6 / 2.0.4

2006-07-22

all

Minor corrections

1.6.1

2006-07-28

all

EIG internal review

1.7

2006-07-28

all

Integrated version; relations to D2.1’s userrequirements

1.8

2006-08-07

all

Update of template 2.0.6

1.9 / 2.2.1

2007-09-03

All

Update of template 2.2.1

1.9.1 / 2.2.2

2007-10-08

10

XMI Clarification

st

4/26

Specification of the Document Access Service – Table of Contents

Table of Contents 1

Foreword..................................................................................................................................................... 8

2

Conventions ................................................................................................................................................ 9

3

4

5

6

2.1

Abbreviations ....................................................................................................................................... 9

2.2


2.3

UML Notation....................................................................................................................................... 9

2.4

Conformance ....................................................................................................................................... 9

2.4.1


2.4.2



Role and Scope of the Document Access Service............................................................................ 10

3.2

Service Specification Summary......................................................................................................... 10

Context of the Document Access Service ................................................................................................ 11 4.1


4.2


4.3


4.4

Relations to other OA and OAS Service Specifications .................................................................... 11

Requirements ........................................................................................................................................... 12 5.1


5.2


Specification of the Document Access Interface ...................................................................................... 13 6.1

Specification of an OAS Profile of Parameter Types used by the Document Access Interface ....... 13

6.2


6.2.1

Specification of the getDocuments Operation............................................................................ 15

6.2.2

Specification of the createDocuments Operation....................................................................... 17

6.2.3

Specification of the setDocuments Operation ............................................................................ 18

6.2.4

Specification of the deleteDocuments Operation....................................................................... 19

6.3

Specification of additional OA Types................................................................................................. 20

6.3.1

OA_File ...................................................................................................................................... 20

6.3.2

OA_DocumentDescriptor ........................................................................................................... 20

6.3.3

OA_MimeType ........................................................................................................................... 20

6.3.4

OA_ResourceLocator................................................................................................................. 20

5/26

Specification of the Document Access Service – Table of Contents 6.3.5

Sequence....................................................................................... 20

6.3.6

Sequence...................................................................................................... 21

6.3.7

OA_DAS_CapabilitiesDocument................................................................................................ 21

6.3.8

OA_ConversionNotSupportedException.................................................................................... 21

6.3.9

OA_ConversionFailedException ................................................................................................ 21

7


8


9



XMI Model ...................................................................................................................................... 26

6/26

Specification of the Document Access Service – Tables and Diagrams

Tables Table 1: Possible interaction between related services................................................................................... 11 Table 2: Summary of Operations ..................................................................................................................... 13 Table 3: Referenced OAS Types ..................................................................................................................... 14 Table 4: Definition of operation getDocuments................................................................................................ 16 Table 5: Definition of operation createDocuments........................................................................................... 17 Table 6: Definition of operation setDocuments................................................................................................ 18 Table 7: Definition of operation deleteDocuments........................................................................................... 19 Table 8: Sections of the service specific capabilities....................................................................................... 22 Table 9: Attributes of the service specific capabilities of section supportedDocumentEncoding .................... 22 Table 10: Attributes of the service specific capabilities of the section supportedMimeType........................... 22 Table 11: Attributes of the service specific capabilities of the section supportedQueryLanguage.................. 23

Diagrams Diagram 1: Class diagram of interface Document Access Service ................................................................. 10 Diagram 2: Class Diagram of the Document Access Interface ....................................................................... 13 Diagram 3: Types introduced in the Document Access Service...................................................................... 20 Diagram 4: Document Access Service specific capabilities ............................................................................ 22

7/26

Specification of the Document Access Service – Foreword

1

Foreword This document is an abstract specification of the Document Access Service and is based on the Template for the abstract Specification of ORCHESTRA Service Types version 2.2.2. It updates the specification version 1.9 1. An update was required to accommodate the changes of the new service templates. This document includes two annexes: Appendix A: Abstract Test Suite (normative) is mandatory and Appendix B: UML Models (normative) is optional.

8/26

Specification of the Document Access Service – Specification of extended Service Capabilities

2

Conventions

2.1

Abbreviations The abbreviations used in this document are defined in chapter 3.1 of the Reference Model for the ORCHESTRA Architecture Version 2.0 (RM-OA), except for the following abbreviated terms:

2.2

•

DAS

Document Access Service

•

MIME

Multipurpose Internet Mail Extensions

•

RDBMS

Relational Database Management System

•

RFC

Request for Comments

•

URI

Uniform Resource Identifiers

•

URL

Uniform Resource Locators


2.3


2.4 2.4.1


2.4.2


9/26


3 3.1

Overview and Architecture Outline Role and Scope of the Document Access Service The Document Access Service (DAS) supports the access to a document of any type (textual documents, images, etc.). A document is regarded as a specialised Feature Type; therefore the Document Access Service may reuse parts of the Feature Access Service. Operations that manipulate Feature Types are not supported by this service, since the sole Feature Type this Service supports is OA_DocumentDescriptor. Compared with the Feature Access Service (see corresponding specification) this service’s contribution is that documents can be converted and that it is guaranteed that the returned Feature Instances are of type OA_DocumentDescriptor.

3.2

Service Specification Summary This service type specification of the Document Access Service is comprised of the following interface that is defined in separate interface type specification: •



The Document Access Interface Type cd Document Access Serv ice Simple ServiceCapabilities «interface» FeatureAccessService + + + + + + + + +

createFeatures(OA_FeatureCollection) : void createFeatureTypes(OA_FeatureTypeCollection) : void deleteFeatures(OA_Query) : void deleteFeatureTypes(OA_Query) : void getCapabilities(OA_GetCapabilitiesRequest) : OA_GetCapabilitiesResponse getFeatures(OA_Query, OA_Encoding) : OA_FeatureCollection getFeatureTypes(OA_Query, OA_Encoding) : OA_FeatureTypeCollection setFeatures(OA_Query, OA_FeatureCollection) : CharacterString setFeatureTypes(OA_Query, OA_FeatureTypeCollection) : CharacterString

DocumentAccessInterface ServiceCapabilities «interface» DocumentAccessService + + + + +

createDocuments(Sequence) : void deleteDocuments(OA_Query) : void getCapabilities(OA_GetCapabilitiesRequest) : OA_GetCapabilitiesResponse getDocuments(OA_Query, OA_MimeType) : Sequence setDocuments(OA_Query, Sequence) : CharacterString

Diagram 1: Class diagram of interface Document Access Service

10/26


4 4.1

Context of the Document Access Service Relations to Standards The Document Access Service uses data types which are defined in the following standards. See also Relations to ORCHESTRA Application Schemas. Related Standards are: •

RFC 2396 - Uniform Resource Identifiers (URI): Generic Syntax

•

RFC 1738 - Uniform Resource Locators (URL)

•

RFC 1521 - MIME (Multipurpose Internet Mail Extensions)

Within the document access service there is a need to uniquely identify each document. Because of the need to have technical access to the document (e.g. using an ftp connection) it is recommendable to use URLs (special URIs) since they provide information about the access protocol as well as the location of a resource. The URL RFC 1738 also enumerates a set of URL schemes (http, ftp, …) that are officially accepted. The Document Access Service currently does not qualify for the contribution to a standard.

4.2

Relations to ongoing Initiatives and related Projects The Document Access Service has no immediate relation to ongoing projects.

4.3

Relations to ORCHESTRA Application Schemas The Document Access Type Specification that is specified as integral part of this Service Type Specification uses Basic and OA Types that are defined in the package OAS/Basic Types, OAS/OA Types and OAS-MI/OA-MI Types of the Information Viewpoint. The Document Access Interface Type Specification that is specified as integral part of this Service Type Specification defines new parameter types. These parameter types are defined the in the package OAS/OA Types/«Application Schema» Document Access Service Exceptions, OAS/OA Types/ «Application Schema» Document Access Service Types of the Information Viewpoint.

4.4

Relations to other OA and OAS Service Specifications Name

Service Type

Service Operation

Format Conversion Service

OAS

convert

Feature Access Service

OAS

Get operations

Table 1: Possible interaction between related services Since the Document Access Service is able to deliver a requested document in a specified format given by a MIME type, it can be necessary to perform a format conversion. The conversion of the requested document itself is could be carried out by the Format Conversion Service.

11/26


5 5.1

Requirements Security Requirements The Document Access Service has the following requirements beyond the scope of the Authentication and Authorisation Service.

5.2

•

The Document Access Service will need an extended security concept that regulates the management of access permissions to all available documents. This concept has to solve the problem of distributed rights management since documents and their requestors have no predefined “location”. In addition the question of responsibility has to be answered, who will be able to grant or revoke access rights to a certain document. Another question could be how to deal with access rights if there are multiple Document Access Service instances.

•

However, these general requirements will most likely be covered by the Authorisation and Feature Access Service.

Reliability Requirements Transaction support may be required.

12/26

Specification of the Document Access Service – Specification of the Document Access Interface

6

Specification of the Document Access Interface

cd Document Access Interface «interface» DocumentAccessInterface + + + + +

createDocuments(Sequence) : void deleteDocuments(OA_Query) : void getCapabilities(OA_GetCapabilitiesRequest) : OA_CapabilitiesDocument getDocuments(OA_Query, OA_MimeType) : Sequence setDocuments(OA_Query, Sequence) : CharacterString

Diagram 2: Class Diagram of the Document Access Interface The Document Access Interface defines the following operations:

Operation

Description

getDocuments

Returns the requested documents.

createDocuments

Creates documents.

setDocuments

Updates existing documents.

deleteDocuments

Removes an existing document. Table 2: Summary of Operations

6.1

Specification of an OAS Profile of Parameter Types used by the Document Access Interface The following OA Types are used within this specification:

Name

Usage

from Schema

New


O

OA Types

No

OA_MI_DAS_Capabilities

O

OA-MI Types

Yes


O

OA Types

Yes


I

OA Types

No

OA_Query

I

OA Types

No

Sequence

I

OA Types

Yes

OA_MimeType

I

OA Types

Yes

13/26


OA_IllegalFeatureType

E


No

OA_IllegalQuery

E


No

OA_IllegalFeature

E


No

OA_ConversionNotSupportedException

E


Yes

OA_ConversionFailedException

E


Yes

OA_OperationRequest

I

OA Types

No


I

OA Types

No

OA_OperationRespons

O

OA Types

No

OA_Notification

I

OA Types

No

OA_OperationResult

O

OA Types

No

OA_InvokeID

O

OA Types

No


E


No


E


No


E


No


E


No

OA_NoApplicableCode

E


No

OA_InternalError

E


No


E


No


E


No


E


No

OA_OperationFailure

E


No


E


No

OA_AbortNotPossible

E


No

OA_InvalidStat

E


No

Table 3: Referenced OAS Types

14/26

Specification of the Document Access Service – Specification of the getDocuments Operation

6.2 6.2.1

Specification of the Operations Specification of the getDocuments Operation The mandatory getDocuments operation returns and optionally converts documents. This operation may use the getFeatures operation of the Feature Access Service. In addition to the getFeatures operation it supports the conversion of a document. Note: If the MIME type of the output format is specified, this operation could call a Format Conversion Service to convert the content to the specified format. The getDocuments operation retrieves features of the feature type OA_DocumentDescriptor. A query can be specified to retrieve certain documents that meet specific requirements. The signatures of the operation is Sequence getDocuments (OA_Query, OA_MimeType) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_IllegalFeatureType, OA_IllegalQuery, OA_ConversionNotSupportedException, OA_ConversionFailedException

Overrides

not applicable

Preconditions

none

Postconditions

none

Use

mandatory Name

Type

Use

query

OA_Query

mandatory

Specifies the query to be used to fetch documents.

targetMimeType

OA_MimeType

optional

The output format of conversion.

Receives Type

Description

Sequence Returns Throws

Description

Type

A sequence of Feature instances of type OA_DocumentDescriptor is returned from the request. Cause





OA_NoApplicableCode

No other basic or service-specific excep-

15/26

Specification of the Document Access Service – Specification of the getDocuments Operation tion type applies.

OA_InternalError



Operation request does not match any feature type. Return Feature Type ID.

OA_IllegalQuery

Operation request does not contain a valid query

Conditional:

There is no conversion available between the source and the target OA_MimeType.

OA_ConversionNotSupportedException Conditional:

The conversion failed unexpectedly.

OA_ConversionFailedException Table 4: Definition of operation getDocuments

16/26

Specification of the Document Access Service – Specification of the createDocuments Operation

6.2.2

Specification of the createDocuments Operation The mandatory createDocuments operation creates new documents of type OA_DocumentDescriptor. This method may use the createFeatures operation of the Feature Access Service. The signatures of the operation is void createDocuments (Sequence ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_IllegalFeatureType, OA_IllegalQuery

Overrides

not applicable

Preconditions

The instance of the DAS allows creation of new documents. Should require authentication and authorization.

Postconditions

none

Use

mandatory Name

Type

Use

documents

Sequence

mandatory

Receives Type Returns

A sequence of Feature instances of type OA_DocumentDescriptor Description

none

none Type

Throws

Description

Cause





OA_NoApplicableCode


OA_InternalError


OA_IllegalQuery


OA_IllegalFeature

Operation request contains invalid features

Table 5: Definition of operation createDocuments

17/26

Specification of the Document Access Service – Specification of the setDocuments Operation 6.2.3

Specification of the setDocuments Operation The mandatory setDocuments operation updates existing documents. This method may use the setFeatures operation of the Feature Access Service. CharacterString setDocuments (OA_Query, Sequence ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_IllegalFeatureType, OA_IllegalQuery

Overrides

not applicable

Preconditions

The instance of the DAS allows updates of new documents. Should require authentication and authorization.

Postconditions

none

Use

mandatory Name query

Type

Use

OA_Query

documents

Sequence

mandatory

Specifies the query to be used to update documents

mandatory

A sequence of Feature instances of type OA_DocumentDescriptor


Description Status information: E.g., how many documents are updated.

CharacterString Type

Throws

Description

Cause





OA_NoApplicableCode


OA_InternalError


OA_IllegalFeature


OA_IllegalQuery


Table 6: Definition of operation setDocuments

18/26

Specification of the Document Access Service – Specification of the deleteDocuments Operation 6.2.4

Specification of the deleteDocuments Operation The mandatory deleteDocuments operation removes existing documents. A query identifies which document to be deleted. This method may use the deleteFeatures operation of the Feature Access Service. This method may use the setFeatures operation of the Feature Access Service. void deleteDocuments (OA_Query) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_IllegalFeatureType, OA_IllegalQuery

Overrides

not applicable

Preconditions

The instance of the DAS allows deletion of new documents. Should require authentication and authorization.

Postconditions

none

Use

mandatory Name query

Type

Use

OA_Query

mandatory


Specifies the query to be used to update documents Description

None

None Type

Throws

Description

Cause





OA_NoApplicableCode


OA_InternalError


OA_IllegalFeature


OA_IllegalQuery


Table 7: Definition of operation deleteDocuments

19/26


6.3

Specification of additional OA Types This service specification does define the OA Types. These new OA Types will become part of the OAS::OA Types and OAS/OA Types/Exception Types. cd Document Type «MetaClass» OMM-Info::OMM_FeatureType «MetaClass» OMM-Info:: OMM_DocumentType

+ + +

«type» Sequence

definition: CharacterString isAbstract: Boolean = false typeName: LocalName

«type» OA_MimeType + +

«type» OA_DocumentDescriptor + + + +

description: CharacterString [0..1] mimeType: OA_MimeType name: OA_GenericName [0..1] resourceLocator: OA_ResourceLocator

+file

1

1

1

1

1..*

«type» OA_File +

content: Binary

contentType: enumeration subType: enumeration

constraints {see IANA Registry http://www.iana.org/assignments/media-types/}

«type» OA_ResourceLocator + + + + + + + +

authority: CharacterString host: CharacterString path: CharacterString port: int protocol: CharacterString query: CharacterString ref: CharacterString userinfo: CharacterString

Diagram 3: Types introduced in the Document Access Service 6.3.1

OA_File OA_File keeps the raw binary content of a file. It is part of the OA_DocumentDescriptor.

6.3.2

OA_DocumentDescriptor The OA_DocumentDescriptor describes the meta-information of a document.

6.3.3

OA_MimeType The standard mime-type describes the content’s encoding format of the document.

6.3.4

OA_ResourceLocator This is the URI description of a resource necessary to publish and retrieve this resource. It is part of the OA_DocumentDescriptor.

6.3.5

Sequence The sequence of OA Type OA_DocumentDescriptor

20/26

Specification of the Document Access Service – Specification of the Document Access Interface 6.3.6

Sequence The sequence of Basic Data Type CharacterString

6.3.7

OA_DAS_CapabilitiesDocument The Document Access Service specific extensions of OA_CapabilitiesDocument of the ServiceCapabilities interface.

6.3.8

OA_ConversionNotSupportedException There is no conversion available between the source and the target OA_MimeType.

6.3.9

OA_ConversionFailedException The conversion failed unexpectedly.

21/26


7


cd Document Access Serv ice Capabilities «type» OA_MI_Serv ice_SpecificCapabilities

«type» OA_MI_DAS_Capabilities + + +

supportedDocumentEncodings: Sequence supportedMimeTypes: Sequence supportedQueryLanguage: CharacterString

Diagram 4: Document Access Service specific capabilities

Section Name

Section Contents

supportedDocumentEncodings

Sequence

supportedMimeTypes

Sequence Table 8: Sections of the service specific capabilities

Name

Definition

Data Type

supportedDocumentEncodings

List of encodings of documents supported.

Sequence


Table 9: Attributes of the service specific capabilities of section supportedDocumentEncoding

Name supportedMimeType

Definition

Data Type

List of mime types supported.

Sequence


Table 10: Attributes of the service specific capabilities of the section supportedMimeType

22/26


Name supportedQueryLanguage

Definition

Data Type

This is the supported query language.

CharacterString

Multiplicity and Use 1 / mandatory

Table 11: Attributes of the service specific capabilities of the section supportedQueryLanguage

23/26

Specification of the Document Access Service – Known Issues and Limitations

8

Known Issues and Limitations Access control is needed to be able to restrict access to documents.

24/26

Specification of the Document Access Service – Appendix A: Abstract Test Suite (normative)

9

Appendix A: Abstract Test Suite (normative) When creating an implementation specification of the Document Access Service, the “Rules for Implementation Specifications of ORCHESTRA Services” defined in chapter 9.2.2.3 and the “Rules for the Service Mapping to a given Platform” of the RM-OA shall be obeyed. In addition, the following tests shall be performed to ensure conformance of an implementation specification to the platform-independent specification of the Document Access Service: 1. Syntactical Conformance •


•


•


•




Additional conformance checks that are specifically to the Document Access Service are not required.

25/26

Specification of the Document Access Service – Appendix B: UML Models (normative)

10 Appendix B: UML Models (normative) 10.1 XMI Model The XMI Models of this interface specification can be downloaded from the OGC Portal under the following URL: https://portal.opengeospatial.org/index.php?m=projects&a=view&project_id=140&tab=2&artifact_id=222 34 The XMI Model contains all parameters required by this service including those data types and exceptions inherited or reused from other interface and service specifications.

26/26




Specification of the Feature Access Service

Revision

1/29

[1.3 / 2.2.1]

Specification of the Feature Access Service – Document Control Page


Specification of the Feature Access Service WP3.4 – Core Service Specifications

Creator

Friis-Christensen, Anders, JRC - IES

Subject


Description

This document defines an abstract and platform independent formal interface specification of the Feature Access Service. The Feature Access Service (FAS) allows interoperable read and write access on feature instances available in an OSN

Publisher


Contributor

Friis-Christensen, Anders, JRC-IES Lutz, Michael, JRC-IES ARCS, IITB, EIG, ETHZ, ATOS, BRGM

Date

2006-02-13

Type

Text

Format

application/msword

Identifier

https://portal.opengeospatial.org/files/?artifact_id=25173

Source

Not applicable

Language

En

Relation

None

Coverage



D3.4.1


WP3.4


NA


NA

Audience


Title


Creator

Friis-Christensen, Anders, JRC - IES

Subject


Description

This document defines an abstract and platform independent formal specification of the Feature Access Service. A Feature Access Ser-

2/29


vice (FAS) allows interoperable read and write access on feature instances available in an OSN. Publisher


Contributor

Friis-Christensen, Anders, JRC-IES Lutz, Michael, JRC-IES ARCS, IITB, EIG, ETHZ, ATOS, BRGM

Date

2007-11-12

Type

Text

Format

application/msword

Identifier


Source

Not applicable

Language

en-GB.

Relation

none

Coverage



D3.4.4


WP3.4


2007-10-31


2007-11-13

Audience


Version number

1.3 / 2.2.1

Date

2007-11-13

Modified by

Lutz, Michael, JRC-IES

Comments Status


Action requested

to be revised by partners involved in the preparation of the deliverable for approval of the WP leader

3/29


for approval of the SP leader for approval of the Technical Supervisor for approval of the Quality Manager for approval of the Project Coordinator Deadline for action: 2007-xx-xx

4/29

Specification of the Feature Access Service – Revision History


Date

Sections changed

Description

0.1

2005-11-07

All

1st draft version

0.2

2005-11-23

All

2nd draft after some input on SP3 meeting in Karlsruhe

0.3

2005-12-21

All

3rd draft based on reviews

0.4

2006-01-02

All

Modifications based on IITB/TU comments to revision 0.3

0.5

2006-01-25

All

Modifications after input from Frankfurt meeting

0.6

2006-02-13

All

Minor changes and adherence to the new template (v1.7)

1.0

2006-02-23

All

No reviews received for ver0.6. Included compression possibility. Final specification for D3.4.1

1.1

2005-06-16

All

Revision based on input on SP3 meetings and modifications according template ver. 2.0

1.2

2006-06-21

2.2 & 6.3

Updated diagrams

1.3 / 2.2.1

2007-11-13

All

Adapted to template version 2.2.1; updated capabilities in section 7; updated relations to standards (section 4.1)

5/29

Specification of the Feature Access Service – Table of Contents

Table of Contents 1

Foreword .....................................................................................................................................................9

2

Conventions ................................................................................................................................................9

3

4

5

6

2.1

Abbreviations .......................................................................................................................................9

2.2

Terms and definitions...........................................................................................................................9

2.3

UML Notation .......................................................................................................................................9

2.4

Conformance........................................................................................................................................9

2.4.1

Conformance to the OMM ............................................................................................................9

2.4.2

Conformance of Implementation Specifications ...........................................................................9

Overview and Architecture Outline........................................................................................................... 10 3.1

Role and Scope of the Feature Access Service ............................................................................... 10

3.2

Service Specification Summary ........................................................................................................ 10

Context of the Feature Access Service.................................................................................................... 12 4.1

Relations to Standards...................................................................................................................... 12

4.2


4.3

Relations to ORCHESTRA Application Schemas............................................................................. 13

4.4

Relations to other ORCHESTRA Service Specifications.................................................................. 13

Requirements ........................................................................................................................................... 14 5.1

Security Requirements...................................................................................................................... 14

5.2

Reliability Requirements ................................................................................................................... 14

Specification of the Feature Access Service Interface............................................................................. 15 6.1

Specification of an OAS Profile of Parameter Types used by the Schema Mapping Interface ........ 15

6.2


6.2.1

Specification of the getFeatureTypes Operation ....................................................................... 16

6.2.2

Specification of the setFeatureTypes Operation ....................................................................... 17

6.2.3

Specification of the createFetureTypes Operation .................................................................... 18

6.2.4

Specification of the deleteFeatureTypes Operation .................................................................. 19

6.2.5

Specification of the getFeatures Operation ............................................................................... 20

6.2.6

Specification of the setFeatures Operation ............................................................................... 21

6.2.7

Specification of the createFeatures Operation .......................................................................... 22

6.2.8

Specification of the deleteFeatures Operation .......................................................................... 23

6.3


6.3.1

OA_IllegalQuery......................................................................................................................... 25

6/29

Specification of the Feature Access Service – Table of Contents 6.3.2

OA_IllegalFeatureType.............................................................................................................. 25

6.3.3

OA_IllegalFeature ...................................................................................................................... 25

6.3.4

OA_Encoding............................................................................................................................. 25

6.3.5

OA_FeatureCollection ............................................................................................................... 25

6.3.6

OA_FeatureDescriptor............................................................................................................... 25

6.3.7

OA_FeatureTypeCollection ....................................................................................................... 25

7

Specification of the Service specific Capabilities ..................................................................................... 25

8

Known Issues and Limitations.................................................................................................................. 27

9

Appendix A: Abstract Test Suite (normative) ........................................................................................... 28

10 Appendix B: UML Models (normative) ..................................................................................................... 29 10.1

XMI Model ..................................................................................................................................... 29

7/29

Specification of the Feature Access Service – Tables and Diagrams

Tables Table 1: Interaction between related services................................................................................................. 13 Table 2: Summary of additional Service Operations ....................................................................................... 15 Table 3: Referenced OA Types ....................................................................................................................... 16 Table 4: Specification of the getFeatureTypes Operation............................................................................... 17 Table 5: Specification of the setFeatureTypes Operation ............................................................................... 18 Table 6: Specification of the createFetureTypes Operation............................................................................ 19 Table 7: Specification of the deleteFeatureTypes Operation .......................................................................... 20 Table 8: Specification of the getFeatures Operation....................................................................................... 21 Table 9: Specification of the setFeatures Operation ....................................................................................... 22 Table 10: Specification of the createFeatures Operation................................................................................ 23 Table 11: Specification of the deleteFeatures Operation ................................................................................ 23 Table 12: Sections of the service specific capabilities .................................................................................... 26 Table 13: Attributes of the service specific capabilities of section OA_MI_FAS_Capabilities ........................ 27

Diagrams Diagram 1: Class Diagram of the Feature Access Service Interface .............................................................. 11 Diagram 2: A scenario of client access to FAS and Schema Mapping Service.............................................. 14 Diagram 3: Class Diagram of the Feature Access Service Interface .............................................................. 15 Diagram 4: Class Diagram of the exception types used in the Feature Access Service ................................ 24 Diagram 5: Class Diagram of the OA types used in the Feature Access Service .......................................... 24 Diagram 6: Service specific capabilities .......................................................................................................... 26

8/29

Specification of the Feature Access Service – Foreword

1

Foreword This document is an abstract specification of the Feature Access Service and is based on the Template for the abstract Specification of ORCHESTRA Services version 2.2. It replaces the specification version 1.2. The update of all chapters were required due to conformance with template version 2.2. This document includes two annexes: Appendix A: Abstract Test Suite (normative) is mandatory and Appendix B: UML Models (normative) is optional.

2

Conventions

2.1

Abbreviations The abbreviations used in this document are defined in chapter 3.1 of the Reference Model for the ORCHESTRA Architecture Version 2.0 (RM-OA), except for the following abbreviated terms: •

2.2

FAS



2.3


2.4 2.4.1


2.4.2


9/29

Specification of the Feature Access Service – Overview and Architecture Outline

3 3.1

Overview and Architecture Outline Role and Scope of the Feature Access Service The Feature Access Service (FAS) allows interoperable read and write access on feature instances available in an OSN. Furthermore, the FAS provides an interface that may be inherited by more specific FASs (e.g., sensor access service) using interface inheritance. The FAS offers information about: - The feature types it is capable to provide or support. - The supported encoding(s) to transfer requested or submitted feature data. - The query language and mechanism that is supported for filtered feature access. Features provided by a FAS are instances of a certain ORCHESTRA Application Schema (OAS) feature type (a feature type defined within an OAS), which again is an instantiation of an OMM_FeatureType (see ref: RM-OA Information Viewpoint). This means that the FAS only allows access to information which are represented through feature types according to the rules of the ORCHESTRA Meta-Model (OMM). Whether information is remodeled on-the-fly by a software component or features are actually stored in a feature store is not crucial for the FAS. Seen from the interface, the feature representation is a black box and is not be visible for clients. The Feature Access Service allows queries to select certain features based on their type, certain attribute values, and, their spatial and temporal extent. The selection statement is encoded using a query language that supports all this functionalities (e.g., SQL including spatiotemporal statements). By selecting and retrieving features access to their attributes and operations are provided. Within an OSN at least one common feature query language has to be defined, which can be used by the ORCHESTRA services. The query language shall support spatiotemporal queries but also queries based on an object-structured model, in particular database structure according to an OAS. SQL3 is an example for such a query language. It is necessary support expressions that ensure that certain features conform to certain criteria without having to retrieve the feature instances themselves. Any Feature Access Service (and its possible profiles or possible inheriting interfaces) may support the update of existing feature instances, the creation of new feature and the deletion of existing features, and hence, in this case, it should also be transactional. It can also allow creation, updates, and deletions of feature types. Feature instances and feature types are identifiable by a Unique Identifier (UID) that is unique with respect to at least one OSN. If a Feature Access Service is used to create a new feature instance or feature type it will also create an appropriate UID for this feature type or instance. Additionally, it is important to emphasize the requirements for authorization and authentication in order to support creation, deletion, and modification of feature and feature types.

3.2

Service Specification Summary This service type specification of the Feature Access Service is comprised of the following interfaces that are defined in separate interface type specifications: •



The Feature Access Service Interface Type

10/29

Specification of the Feature Access Service – Overview and Architecture Outline class Feature Access Service ServiceCapab ilities «interface» FeatureAccessService + + + + + + + + +

createFeatures(features :OA_FeatureCollection) : void createFeatureTypes(featureType :OA_FeatureTypeCollection) : void deleteFeatures(query :OA_Query) : void deleteFeatureTypes(query :OA_Query) : void getCapab ilities(OAS_GetCapab ilitiesRequest :OA_GetCapab ilitiesRequest) : OA_GetCapab ilitiesResponse getFeatures(query :OA_Query, encoding :OA_Encoding) : OA_FeatureCollection getFeatureTypes(query :OA_Query, encoding :OA_Encoding) : OA_FeatureTypeCollection setFeatures(query :OA_Query, features :OA_FeatureCollection) : CharacterString setFeatureTypes(query :OA_Query, featureType :OA_FeatureTypeCollection) : CharacterString

Diagram 1: Class Diagram of the Feature Access Service Interface

11/29

Specification of the Feature Access Service – Relations to Standards

4 4.1

Context of the Feature Access Service Relations to Standards The functionality of the Feature Access Service (FAS) is based on the WFS and WCS OGC implementation specifications: •

OGC Web Feature Service (WFS) Implementation Specification (latest version V1.1, 04-094)

•

OGC Web Coverage Service (WCS) Implementation Specification (latest version V1.1.0, 06083r8)

These specifications allows for retrieval of features and coverages respectively. Coverages and features are considered as Orchestra features at the abstract level, and thus one interface has been developed for the access to both types. The write functionalities of the WFS specifications (which basically consist of a transactional operation) have been transferred into three operations setFeatures, createFeatures, and deleteFeatures, as to follow the ORCHESTRA convention of operation functionality. Additionally, the objective was to put the “write behaviour” of the WFS at the operation level in the interface. Currently, in the OGC WFS specification, the write type of a given operation (i.e., insert, update, or delete) is specified as a parameter to a more generic operation (transaction operation). The lock mechanism offered by the WFS getFeatureWithLock and lockFeature must be implemented using the transaction interface offered by ORCHESTRA. This approach ensures the same transactional model throughout all services within ORCHESTRA where (serializable) transactions are required. Finally, the setFeatureTypes, createFeatureTypes, and deleteFeatureTypes operations have been specified in addition to the OGC specifications in order to provide an interface to manage feature types. This is currently not possible via implementations following the OGC specifications. As the FAS does not define a specific query language or encoding for features, it is up to the implementation specification to define these. Prominent standards which can be used for query languages are: •

ISO/IEC 9075:1995 Information technology -- Database languages – SQL

•

OGC 04-095 Filter Encoding Implementation Specification V1.1

A commonly used standard for the encoding of (especially geographic) features is: •

ISO/DIS 19136 Geographic information -- Geography Markup Language (GML)

GML is based on the XML standard, which can be used for encoding as well: •

W3C - Extensible Markup Language (XML) 1.0 (http://www.w3.org/TR/2006/REC-xml20060816)

Examples of commonly used encodings for coverage features are: •

GeoTIFF (http://www.remotesensing.org/geotiff/geotiff. html)

•

HDF-EOS (http://www.hdfeos.org)

•

CF-NetCDF (http://www.cgd.ucar.edu/cms/eaton/cf-metadata)

The Feature Access Service currently does not qualify for the contribution to a standard.

12/29

Specification of the Feature Access Service – Relations to ongoing Initiatives and related Projects

4.2

Relations to ongoing Initiatives and related Projects The Feature Access Service has no immediate relation to ongoing projects.

4.3

Relations to ORCHESTRA Application Schemas The Feature Access Service Interface Type Specification that is specified as integral part of this Service Type Specification uses Basic and OA Types that are defined in the package OAS/Basic Types, OAS/OA Types and OAS-MI/OA-MI Types of the Information Viewpoint. The Feature Access Interface Type Specification that is specified as integral part of this Service Type Specification uses OA-MI Types that are defined in the package OAS-MI/OA-MI Types of the Information Viewpoint. The Feature Access Service Interface Type Specification that is specified as integral part of this Service Type Specification defines new parameter types. These parameter types are defined the in the package OAS/OA Types/Feature Access Service Types.

4.4

Relations to other ORCHESTRA Service Specifications The FAS is used by other services that need to get access to features.

Name SchemaMappingService

Service Type OAS

Service Operation mapFeatures

Table 1: Interaction between related services A very simple example of a client which uses the FAS and a Schema Mapping Service could be an assessment of Pan-European forest fires based on country specific registrations. In this scenario, the single countries have their own model for fire registrations and publish that on the OSN (as the data are not only to be used for Pan-European forest fire assessment). A client access data and represent it using a common model for Pan-European forest fire registrations. The representation of the source system data (forest fire registrations for different countries) as Orchestra features is not covered by the illustration.

13/29

Specification of the Feature Access Service – Security Requirements

SchemaMapping Service transformData

GetFeatures

GetFeatures

FAS

FAS

…. Forest fire registrations country 1

Forest fire registrations country x

Diagram 2: A scenario of client access to FAS and Schema Mapping Service In the simple example above the client is responsible for access to data and later data transformation via a schema mapping service, however, a more challenging example would be a FAS that is implemented based on cascading services. In the example above, a FAS would then integrate the various instances and support an integrated access to the features of the underlying services by use of the appropriate schema mappings, i.e., the schema mapping request is done by the FAS. Another example could be cascading FAS where one instance of a FAS makes request to several FASs without the user necessarily knowing it. If the requested features of a feature type cover a border area, they might have different schemas in the various FASs. Then, possibly schema transformation has to occur. It is important to underline that the interface of the FAS should not change because of introducing the cascading FAS concept.

5 5.1

Requirements Security Requirements The Feature Access Service has no requirements beyond the scope of the Authentication and Authorization Service. An instance of a FAS may require authentication and authorization provided by the respective services, in order to give access to secured and restricted information provided by FAS. Single attributes of a given feature may also be restricted.

5.2

Reliability Requirements It is independent of other services; however, if there are failures in the sources of a cascading FAS, it cannot return any features. Similarly, it may be affected by a failure in a required Schema Mapping Service. Furthermore, as the FAS supports authentication and authorization it also depends on these.

14/29

Specification of the Feature Access Service – Specification of an OAS Profile of Parameter Types used by the Schema Mapping Interface

6

Specification of the Feature Access Service Interface class Feature Access Service ServiceCapab ilities «interface» FeatureAccessService + + + + + + + + +

createFeatures(features :OA_FeatureCollection) : void createFeatureTypes(featureType :OA_FeatureTypeCollection) : void deleteFeatures(query :OA_Query) : void deleteFeatureTypes(query :OA_Query) : void getCapab ilities(OAS_GetCapab ilitiesRequest :OA_GetCapab ilitiesRequest) : OA_GetCapab ilitiesResponse getFeatures(query :OA_Query, encoding :OA_Encoding) : OA_FeatureCollection getFeatureTypes(query :OA_Query, encoding :OA_Encoding) : OA_FeatureTypeCollection setFeatures(query :OA_Query, features :OA_FeatureCollection) : CharacterString setFeatureTypes(query :OA_Query, featureType :OA_FeatureTypeCollection) : CharacterString

Diagram 3: Class Diagram of the Feature Access Service Interface The Feature Access Service interface defines the following operations:

Operation Name

Description

getFeatureTypes

Gets a description (the schema) of given feature types serviced by a Feature Access Service instance

setFeatureTypes

Updates existing Feature Types

createFeatureTypes

Creates new Feature Types

deleteFeatureTypes

Deletes existing Feature Types

getFeatures

Retrieves features and their attributes

setFeatures

Updates existing features

createFeatures

Creates new features

deleteFeatures

Deletes existing features Table 2: Summary of additional Service Operations

6.1

Specification of an OAS Profile of Parameter Types used by the Schema Mapping Interface The following OA Types are used within this specification:

Name

Usage

from OAS

15/29

New

Specification of the Feature Access Service – Specification of the Operations

OA_IllegalQuery

E

OAS/OA Types/Feature Access Service Exceptions

Yes


E


Yes

OA_IllegalFeature

E


Yes

OA_InternalError

E

OAS/OA Types/OA Basic Service Exceptions

No

OA_NoApplicableCode

E


No


E


No


E


No

OA_Query

I

OAS/OA Types/OA Basic Service Types

No


I,O

OAS/OA Types/Feature Access Service Types

Yes

OA_FeatureDescriptor

O


Yes

OA_FeatureTypeCollection

I,O


Yes

OA_Encoding

I


Yes

OA_SchemaDescriptor

I,O


No


6.2

Specification of the Operations Operations which have been inherited from other interfaces and which do not provide extended or limited functionality to original specification are omitted in this specification.

6.2.1

Specification of the getFeatureTypes Operation The mandatory getFeatureTypes operation returns information in a requested encoding about one or several specific feature types and returns their schemas.

Overrides

Not applicable

Preconditions

The feature types exist. Should require authentication and authorization.

Postconditions

None

Use

Mandatory

16/29


Name

Type

Use

Description

query

OA_Query

Required

A query that identifies the feature types of interest

encoding

OA_Encoding

Optional

Specifies the encoding of the returned FeatureType (default is XML)

Receives Type

Description A list of feature type descriptions containing meta information (name etc) as well as the schema for the feature types.

OA_FeatureTypeCollection Returns Type

Throws

Cause





OA_NoApplicableCode


OA_InternalError

A problem occurred in the runtime environment (e.g., out of memory).

OA_IllegalQuery


Table 4: Specification of the getFeatureTypes Operation 6.2.2

Specification of the setFeatureTypes Operation The optional setFeatureTypes operation updates the schemas of existing feature types, e.g., by adding a new attribute. The setFeatureTypes operation shall include a query parameter which is used to update feature types. The setFeatureTypes operation can include a list of feature type descriptors parameter containing the schemas and id’s of the feature types to be updated. At least one of the parameters query or featureType shall be present. A locking mechanism is required in order to avoid the transactions to cause inconsistencies.

Overrides

Not applicable

Preconditions

The feature types exist and the FAS allows updating of feature types. Should require authentication and authorization.

Postconditions

All existing data must be consistent with the new feature type definitions (schema).

Use

Optional

Receives

Name

Type

Use

17/29

Description


query

OA_Query

Optional

Specifies the query to be used to update feature types

featureType

OA_FeatureTypeCollection

Optional

Specifies a collection of feature types to be updated including their schema and meta-information which is required in order to update.

Type Returns

Description Status information: E.g., how many feature types are updated.


Throws

Cause





OA_NoApplicableCode


OA_InternalError


OA_IllegalQuery


Table 5: Specification of the setFeatureTypes Operation 6.2.3

Specification of the createFetureTypes Operation The optional createFeatureTypes operation creates the schemas of new feature types, e.g., specifying name, attributes, and data types.

Overrides

Not applicable

Preconditions

The instance of the FAS allows creation of feature types. Should require authentication and authorization.

Postconditions

None

Use

Optional Name featureType

Receives Returns

Type

Use

OA_FeatureTypeCollection Type

Required

Description Specifies the feature types to be created Description

18/29


Not applicable

Not applicable Type

Throws

Cause

OAS_InvalidParameterValue




OA_NoApplicableCode

No other basic or service-specific exception type applies. A problem occurred in the runtime environment (e.g., out of memory).

OA_InternalError OA_IllegalFeatureType

Operation request contains invalid feature type descriptors

Table 6: Specification of the createFetureTypes Operation

6.2.4

Specification of the deleteFeatureTypes Operation The optional deleteFeatureTypes operation deletes the schemas of existing feature types.

Overrides

Not applicable

Preconditions

The feature types exist and the instance of the FAS allows creation of feature types. Should require authentication and authorization.

Postconditions

All existing data belonging to the feature type should not be accessible via the FAS. Whether data are deleted or not is to be decided by the data publisher.

Use

Optional Name query

Type OA_Query

Receives

Use

Description

Required


Type Returns Throws

Description

Not applicable

Not applicable Type

Cause




Operation request does not include a pa-

19/29

Specification of the Feature Access Service – Specification of the Operations rameter value. Return the name of the missing parameter. OA_NoApplicableCode


OA_InternalError


OA_IllegalQuery


Table 7: Specification of the deleteFeatureTypes Operation

6.2.5

Specification of the getFeatures Operation The mandatory getFeatures operation retrieves features in a FeatureCollection of existing feature types based on a requested encoding. A query can be specified to retrieve certain features that meet specific requirements. The query also includes the query language, which means that several query languages can be supported. The returned FeatureCollection can be compressed if the user requests this for data transfer performance reasons.

Overrides

Not applicable

Preconditions

The feature type exists. Should require authentication and authorization.

Postconditions

None

Use

Mandatory Name

Type OA_Query

Required

Specifies the query to be used to fetch features.

encoding

OA_Encoding

Optional

Specifies the encoding of the returned FeatureCollection (default is GML)

Type

Throws

Description

query

Receives

Returns

Use

Description A feature collection (list) is returned from the request.

OA_FeaureCollection Type

Cause





20/29


OA_NoApplicableCode


OA_InternalError


OA_IllegalQuery


Table 8: Specification of the getFeatures Operation 6.2.6

Specification of the setFeatures Operation The optional setFeatures operation updates features of an existing feature type. The setFeatures operation should include a query parameter which is used to update features. The setFeatures operation can include a featureCollection parameter containing the values and id’s of the features to be updated. At least one of the parameters query or featureCollection shall be present.

Overrides

Not applicable

Preconditions

The feature(s) exist(s). The instance of the FAS allows updates of features. Should require authentication and authorization.

Postconditions

Data are consistent with the feature type definitions.

Use

Optional Name

Type OA_Query

Optional

Specifies the query to be used to update features

featureCollection


Optional

Specifies values (and id’s) for the features to be updated

Type

Throws

Description

query

Receives

Returns

Use

Description Status information: E.g., how many features are updated.


Cause





21/29


OA_NoApplicableCode

No other basic or servicespecific exception type applies. A problem occurred in the runtime environment (e.g., out of memory).

OA_InternalError OA_IllegalFeature

Operation request contains invalid features Operation request does not contain a valid query

OA_IllegalQuery

Table 9: Specification of the setFeatures Operation 6.2.7

Specification of the createFeatures Operation The optional createFeatures operation creates features of an existing feature type. The query identifies which feature type is in scope of operation.

Overrides

Not applicable

Preconditions

The feature type exists. The instance of the FAS allows creation of new features. Should require authentication and authorization.

Postconditions

Data are consistent with the feature type definitions.

Use

Optional Name featureCollection

Type OA_FeatureCollection

Use

Description

Required

The collection of features that need to be inserted.


Description

None

Throws

None Type

Cause





OA_NoApplicableCode

No other basic or servicespecific exception type applies. A problem occurred in the runtime environment (e.g., out of memory).

OA_InternalError

22/29


OA_IllegalQuery


OA_IllegalFeature


Table 10: Specification of the createFeatures Operation 6.2.8

Specification of the deleteFeatures Operation The optional deleteFeatures operation deletes features of an existing feature type. A query identifies which features to be deleted.

Overrides

Not applicable

Preconditions

The feature type exists. The instance of the FAS allows deletion of features. Should require authentication and authorization.

Postconditions

None

Use

Optional Name

Type

query

OA_Query

Use

Description

Required



Description

None

None Type

Throws

Cause





OA_NoApplicableCode


OA_InternalError


OA_IllegalQuery


OA_IllegalFeature


Table 11: Specification of the deleteFeatures Operation

23/29

Specification of the Feature Access Service – Specification of Parameter Types

6.3

Specification of Parameter Types This interface specification defines new OA Types. These new OA Types will become part of the OAS “Feature Access Service Exceptions” and “Feature Access Service Types”, respectively. Diagram 4 shows all exception types, and Diagram 5 shows all the types used in the Feature Access Service as well as the relationships between them. This interface specification does not define any new OT Types. This interface specification does not introduce any new non-orchestra Types.

class Feature Access Service Exceptions «type» OA_IllegalFeatureType «type» OA_AbstractException

«type» OA_IllegalFeature

+ +


+


«type» OA_IllegalQuery «type» OA_InternalError +

«type» OA_NoApplicableCode

location: OA_CodeLocation [0..*] {ordered}

«type» OA_InvalidParameterValue + +

parameterName: CharacterString value: CharacterString

«type» OA_MissingParameterValue +

parameterName: CharacterString

Diagram 4: Class Diagram of the exception types used in the Feature Access Service class Feature Access Service Types «type» OA_FeatureDescriptor

«type» OA_FeatureTypeCollection # #

description: CharacterString name: CharacterString

«CodeList» OA_Encoding + + +

GML: NONE: XML:

«type» OA_Query + +

Language: OA_QueryLanguage Query: CharacterString

1 1 1

«type» OA_SchemaDescriptor

«type» FeatureCollection + + + +

«CodeList» OA_QueryLanguage

encoding: OA_Encoding purpose: CharacterString schemaName: CharacterString SchemaReference: OA_URI

Diagram 5: Class Diagram of the OA types used in the Feature Access Service This service specification define new OA Types. These new OA Types will become part of the OAS:OA Types and OAS:OA Types: Exceptions Types.

24/29

Specification of the Feature Access Service – Specification of Parameter Types 6.3.1

OA_IllegalQuery Exceptions type that specifies that it is not possible to interpret the query given as parameter

6.3.2

OA_IllegalFeatureType Exceptions type. In a request for updating or inserting feature type it is required to submit a specification of the feature type. If the information provided is not fulfilling the requirements (e.g., schema information) it cannot be inserted/updated.

6.3.3

OA_IllegalFeature Exceptions type. In a request for updating or inserting features it is required to submit a collection of features. If they are not according the schema of the feature type, they cannot be inserted/updated.

6.3.4

OA_Encoding The OA_Encoding is a codelist containing various encodings

6.3.5

OA_FeatureCollection The featurecollection is a list of features which does not necessarily belong to the same feature type. Furthermore, it specifies the encoding used.

6.3.6

OA_FeatureDescriptor The FeatureDescriptor is a representation of the feature type including a name, description, an id, its schema representation, and various information about the schema (encoding, language etc)

6.3.7

OA_FeatureTypeCollection The FeatureTypeCollection is a set of feature descriptions. Furthermore, it specifies the encoding used.

7

Specification of the Service specific Capabilities As part of ORCHESTRA D3.3.2 a meta-information schema for services is defined acting as a default OAS-MI for service capabilities. OA_MI_CapabilitiesDocument includes both the common capabilities and the service specific capabilities. While the common capabilities are defined in the specification of the Service Capabilities Interface, the specific capabilities have to be specialized in each service specification.

25/29

Specification of the Feature Access Service – Specification of Parameter Types class OAS-MI Service Specific FAS «type» OA_MI_Section + + +

name: CharacterString sectionContent: OA_MI_SectionContentBase sectionSchema: CharacterString

1 «type» OA_MI_SectionContentBase

«type» OA_MI_FAS_Capabilities + + + +

supportedFeatureCollectionEncoding: OA_Encoding [1..*] supportedFeatureTypeEncoding: OA_Encoding [1..*] supportedFeatureTypes: CharacterString [0..*] supportedQueryLanguage: OA_QueryLanguage [1..*]

Diagram 6: Service specific capabilities The schema for service specific capabilities defined here is explicitly divided into the following schema sections:

Section Name OA_MI_FAS_Capabilities

Section Contents The service specific capabilities for the Feature Access Service.


Name

Definition

Data Type


supportedFeatureTypeEncoding

Lists which is the encoding of the returned feature type descriptor, e.g. XML

OA_Encoding

1..* / mandatory

supportedFeatureCollectionEncoding

Lists which is the encoding of the returned feature col-

OA_Encoding

1..* / mandatory

26/29

Specification of the Feature Access Service – Specification of Parameter Types lection, e.g. GML

supportedFeatureTypes

Lists which feature types are supported by the service.

CharacterString

0..* / mandatory

supportedQueryLanguage

Lists which query languages are supported by the service.

OA_QueryLanguage

1..* / mandatory

Table 13: Attributes of the service specific capabilities of section OA_MI_FAS_Capabilities The supportedFeatureTypes is required in order to specify which feature types can be requested. The supportedFeatureTypeEncoding is required in order to know which encoding is used for the Feature Type requests. The supportedFeatureCollectionEncoding is required in order to know which encoding is used for the Feature requests. The supportedQueryLanguage is required in order to know which query language that can be used with the specific service instance.

8

Known Issues and Limitations We need to define a common approach to model and specify the queries across all service specs. Also it would be helpful to specify certain types of queries, e.g., a list of predicate types.

27/29

Specification of the Feature Access Service – Appendix A: Abstract Test Suite (normative)

9

Appendix A: Abstract Test Suite (normative) When creating an implementation specification of the Feature Access Service, the “Rules for Implementation Specifications of ORCHESTRA Services” defined in chapter 9.2.2.3 and the “Rules for the Service Mapping to a given Platform” of the RM-OA shall be obeyed. In addition, the following tests shall be performed to ensure conformance of an implementation specification to the platform-independent specification of the Feature Access Service: 1. Syntactical Conformance •


•


•


•




Additional conformance checks that are specifically to the Feature Access Service are not required.

28/29

Specification of the Feature Access Service – Appendix B: UML Models (normative)

10 Appendix B: UML Models (normative) 10.1 XMI Model The XMI Models of this service specification can be downloaded from the OGC Portal under the following URL: http://portal.opengeospatial.org/index.php?m=projects&a=view&project_id=140&tab=2&artifact_id=24302

The XMI Model contains only the parameters specified in this service specification. Additional parameters used by this service can be found in the XMI Models of the following interface or service specifications: •


•

The Feature Access Service Type

•

The OA Basic Service Type

29/29




Specification of the Format Conversion Service

Revision

1/22

[1.7 / 2.2.2]

Specification of the Format Conversion Service – Document Control Page


Specification of the Format Conversion Service

Creator

Fischer, Julian

Subject


Description

This document defines an abstract and platform independent formal specification of the Format Conversion Service.

Publisher


Contributor

Berlinghoff, Thomas


Dihé, Pascal


Fischer, Julian


Hofmann, Thomas


Iosifescu-Enescu, Ionut

ETH Zurich

Ma, Wenjie



Date

2006-07-26

Type

Text

Format

application/msword

Identifier


Source

Not applicable

Language

en-GB.

Relation

none

Coverage



D3.4.3


WP3.4


2006-06-30


2006-07-28

Audience


Version number

1.7 / 2.2.2

Date

2007-10-08

Modified by

Ma, Wenjie

Comments

Intended for incorporation in deliverable 3.4.4


2/22

Specification of the Format Conversion Service – Document Control Page

Status


Action requested


3/22

Specification of the Format Conversion Service – Revision History


Date

Sections changed

Description st

1.0

2005-09-02

all

1 intermediate release

1.1

2005-09-24

all

updated to new template structure

1.1.1

2006-01-05

all

Minor updates

1.2 / 1.7

2006-02-06

all

Add Document Control Page, section Conformance and Annex D: Abstract test suite, changes on headline in some sections.

1.3 / 1.7

2006-02-09

all

Final version after ETHZ review

1.3.1 / 1.7

2006-02-21

1.2, 5.1

Update of class diagrams

1.4 / 1.7

2006-02-23

all

Operation getConversionCapabilities deleted

1.5 / 2.0.5

2006-06-26

all

Adoption to template 2.0.5, completion of missing sections. Removal of chapter “6 Appendix A: Service Implementation Recommendation”

1.6 /2.0.6

2006-08-08

some

Comments resolved; update to template 2.0.6

1.7 / 2.2.2

2007-10-08

all

updated to new template structure

4/22

Specification of the Format Conversion Service – Table of Contents

Table of Contents 1

Foreword..................................................................................................................................................... 8

2

Conventions ................................................................................................................................................ 9

3

4

5

6

2.1

Abbreviations ....................................................................................................................................... 9

2.2


2.3

UML Notation....................................................................................................................................... 9

2.4

Conformance ....................................................................................................................................... 9

2.4.1


2.4.2



Role and Scope of the Format Conversion Service .......................................................................... 10

3.2


Context of the Format Conversion Service............................................................................................... 11 4.1


4.2


4.3


4.4


Requirements ........................................................................................................................................... 13 5.1


5.2


Specification of the Format Conversion Interface..................................................................................... 13 6.1

Specification of an OAS Profile of Parameter Types used by the Format Conversion Interface...... 14

6.2


6.2.1 6.3

Specification of the convert Operation ....................................................................................... 15


6.3.1

OA_UnknownMimeTypeException ............................................................................................ 16

6.3.2

OA_InvalidInputFileException .................................................................................................... 16

6.3.3

OA_ConversionNotSupportedException.................................................................................... 16

7


8

Known Issues and Limitations .................................................................................................................. 19 8.1.1

Support for streamed I/O............................................................................................................ 19

5/22

Specification of the Format Conversion Service – Table of Contents 8.1.2 9

Cooperation and Cascading between Service Instances .......................................................... 19



XMI Model ...................................................................................................................................... 22

6/22

Specification of the Format Conversion Service – Tables and Diagrams

Tables Table 1: Summary of operation........................................................................................................................ 13 Table 2: Referenced OA Types ....................................................................................................................... 15 Table 3: Specification of the convert Operation............................................................................................... 16 Table 4: Sections of the service specific capabilities....................................................................................... 17 Table 5 Attributes of the service specific capabilities of section availableOrdinaryConversions .................... 18

Diagrams Diagram 1: Class Diagram of the Format Conversion Service ........................................................................ 10 Diagram 2: Class Diagram of the Format Conversion Interface...................................................................... 13 Diagram 3 Format Conversion Service specific capabilities............................................................................ 17

7/22

Specification of the Format Conversion Service – Foreword

1

Foreword This document is an abstract specification of the Format Conversion Service and is based on the Template for the abstract Specification of ORCHESTRA Services version 2.2.2. It updates the specification version 2.0.6. An update was required to accommodate the changes of the new service templates. This document includes two annexes: Appendix A: Abstract Test Suite (normative) is mandatory and Appendix B: UML Models (normative) is optional.

8/22

Specification of the Format Conversion Service – Conventions

2

Conventions

2.1


2.2


2.3


2.4 2.4.1


2.4.2


9/22

Specification of the Format Conversion Service – Overview and Architecture Outline

3 3.1

Overview and Architecture Outline Role and Scope of the Format Conversion Service The Format Conversion Service allows the conversion of data given in one format to the corresponding data given in another format. Each conversion between a pair of formats requires a conversion algorithm. The problem we face is how two organisations are able to exchange their documents without caring about the format the other side uses. This is the reason why the “Format Conversion Service” is needed. It allows the conversion from one document type (MS-Word, OpenDocument, pdf, …) to another one in order to easily exchange documents between different organisations. Data could be text based, like a word document or a pdf, or it could be binary data like JPEG or WMF.

3.2

Service Interface Specification Summary This service type specification of the Format Conversion Service is comprised of the following interface that is defined in separate interface type specification: •



The Format Conversion Interface Type

cd Format Conv ersion Serv ice - Ov erv iew «interface» ServiceCapabilities +


FormatConversionInterface «interface» FormatConversionService + +

convert(OA_MimeType, OA_MimeType, OA_File) : OA_File getCapabilities(OA_GetCapabilitiesRequest) : OA_CapabilitiesDocument

Diagram 1: Class Diagram of the Format Conversion Service

10/22

Specification of the Format Conversion Service – Context of the Format Conversion Service

4 4.1

Context of the Format Conversion Service Relations to Standards The way used to specify the format or type is established according to MIME (RFC 2387), a list of available types is maintained at IANA. The MIME-standard is available as RFC 2387 at: http://www.ietf.org/rfc/rfc2387.txt See for available types at: http://www.iana.org/assignments/media-types/ Depending on the requirements of actual applications, the resulting implementation of the Format Conversion Service can adopt different standards. These might be file formats for pictures, e.g.: •

Portable Network Graphics (PNG) [W3C-PNG: http://www.w3.org/TR/PNG/ and ISO/IEC 15948:2003]

•

JPEG (lossy and lossless: ITU-T T.81, ISO/IEC IS 10918-1; extensions: ITU-T T.84)

•

JPEG-LS (lossless: ITU-T T.87, ISO/IEC IS 14495-1)

•

JBIG (black and white: ITU-T T.82, ISO/IEC IS 11544-1)

•

JPEG-2000 (evolved from JPEG/JPEG-LS: ITU-T T.800, ISO/IEC IS 15444-1; extensions: ITUT T.801)

•

Scalable Vector Graphics (SVG) [http://www.w3.org/Graphics/SVG/]

•

ArcView Shapefile

•

…

Hints: •

a list of picture file formats may be found at: http://en.wikipedia.org/wiki/Graphics_file_format_summary

•

a converter from “ArcView Shapefile” to SVG is available under the terms of the LGPL at: http://www.carto.net/papers/svg/utils/shp2svg/

Standard file formats for textual documents might be: •

RTF (various Microsoft™ specifications)

•

OpenDocument (OASIS Open Document Format for Office Applications; ISO/IEC DIS 26300)

•

Microsoft™ Word documents

•

…

The Format Conversion Service currently does not qualify for the contribution to a standard.

4.2

Relations to ongoing Initiatives and related Projects The Format Conversion Service has no immediate relation to ongoing projects.

4.3

Relations to ORCHESTRA Application Schemas The Format Conversion Interface Type Specification that is specified as integral part of this Service Type Specification uses Basic and OA Types that are defined in the package OAS/Basic Types, OAS/OA Types and OAS-MI/OA-MI Types of the Information Viewpoint.

11/22

Specification of the Format Conversion Service – Context of the Format Conversion Service The Format Conversion Interface Type Specification that is specified as integral part of this Service Type Specification defines new parameter types. •

4.4

These parameter types are defined the in the package OAS/OA Types/«Application Schema» Format Conversion Service Exceptions, OAS/OA Types/ «Application Schema» Format Conversion Service Types of the Information Viewpoint.

Relations to other ORCHESTRA Service Specifications The interaction with the Document Access Service is a possible relation to the OA Service. The mode of interaction is to be defined in the respective service’s specification.

12/22

Specification of the Format Conversion Service – Requirements

5 5.1

Requirements Security Requirements The Format Conversion Service has no requirements beyond the scope of the Authentication and Authorisation Service.

5.2

6

Reliability Requirements •

The question about the technical possibility of a certain conversion will be answerable using the getCapabilities operation. If a certain possible conversion will deliver the expected result is a different question.

•

Consider the conversion of a document given in the format with the mime-type “text/html” that has to be converted to “text/plain”. Sloppy spoken the conversion includes parsing the htmldocument, stripping the html-tags and finally produce a reasonable formatted text-file. But finding an algorithm which performs reasonable formatting for an arbitrary html-document is quite hard. Consider the following algorithm: Replace every html-tag with a single space. This will satisfy our requirement converting from “text/html” to “text/plain” but will lead to a huge and hardly readable text. Of course there are many better approaches to do that conversion but the basic problem becomes clear. Two “text/html” to “text/plain” conversion-adapters may be fairly different. Their use has to be considered in the context of their purpose to really ensure a meaningful outcome.

Specification of the Format Conversion Interface

cd Format Conv ersion Interface «interface» FormatConversionInterface +

convert(OA_MimeType, OA_MimeType, OA_File) : OA_File

Diagram 2: Class Diagram of the Format Conversion Interface The Format Conversion Interface defines the following operation:

Operation Name convert

Description Performs the conversion given by input and output mime type. Table 1: Summary of operation

13/22

Specification of the Format Conversion Service – Conformance of Implementation Specifications

6.1

Specification of an OAS Profile of Parameter Types used by the Format Conversion Interface The following non basic types are used within this specification:

Name

Usage

from OAS

New

OA_File

I, O

OA Types

No

OA_MimeType

I, O

OA Types

No


O

OA Types

No

OA_UnknownMimeTypeException

E


Yes

OA_InvalidInputFileException

E


Yes


E


Yes


I

OA Types

No

OA_OperationRequest

I

OA Types

No


I

OA Types

No


O

OA Types

No

OA_Notification

I

OA Types

No

OA_OperationResult

O

OA Types

No

OA_InvokeID

O

OA Types

No


E


No


E


No


E


No


E


No

OA_NoApplicableCode

E


No

OA_InternalError

E


No


E


No

14/22

Specification of the Format Conversion Service – Specification of the convert Operation


E


No


E


No

OA_OperationFailure

E


No


E


No

OA_AbortNotPossible

E


No

OA_InvalidStat

E


No


6.2 6.2.1

Specification of the Operations Specification of the convert Operation The mandatory convert operation converts data. This data is provided via an input-file, the format of the input-file is specified via a parameter, and the same applies for the output-file. The signatures of the operation is OA_File convert (OA_MimeType, OA_MimeType, OA_File) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_UnknownMimeTypeException, OA_InvalidInputFileException, OA_ConversionNotSupportedException

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

Mandatory

Receives

Name

Type

Use

outputFormat

OA_

mandatory

Mime-type the output-file shall have

inputFormat

OA_MimeType

mandatory

Mime-type the input-file has

inputFile

OA_File

mandatory

The reference to the inputfile

Returns

Type

Description

OA_File Throws

Description

The converted file Type

Cause

15/22

Specification of the Format Conversion Service – OA_UnknownMimeTypeException





OA_NoApplicableCode


OA_InternalError


OA_UnknownMimeTypeException

In case a format specified as one of the parameters is not known to this service instance.

OA_InvalidInputFileException

The specified input-file in not valid. Possible reasons are: not found, or the format does not comply to the specified one.


The conversion between the specified input-format and the output-format is not supported.

Table 3: Specification of the convert Operation

6.3

Specification of Parameter Types This interface specification defines the OA Types These new OA Types will become part of the OAS “OA Types”. This interface specification does not define any new OT Types. This interface specification does not introduce any new non-ORCHESTRA Types.

6.3.1

OA_UnknownMimeTypeException In case a format specified as one of the parameters is not known to this service instance.

6.3.2

OA_InvalidInputFileException If the specified input-file in not valid, the possible reason are: not found, or the format does not comply with the specified one.

6.3.3

OA_ConversionNotSupportedException The conversion between the specified input-format and the output-format is not supported by this instance of the Format Conversion Service.

16/22

Specification of the Format Conversion Service – Specification of Parameter Types

7


cd Format Conv ersion Serv ice Capabilities OA_MI_Service_SpecificCapabilities «type» OA_FormatConv ersionCapabilities list + availableOrdinaryConversions: OA_ConversionInformation

«type» OA_Conv ersionInformation + +

input: OA_MimeType output: OA_MimeType

Specialisation/decoration with "isLossy", "isAdapterChain" and so on needs to be rethought. «type» OA_MI_FCS_SpecificCapabilities +

isLossy: Boolean

Diagram 3 Format Conversion Service specific capabilities The schema for service specific capabilities defined here is explicitly divided into the following schema sections:

Section Name availableOrdinaryConversions

Section Contents List of conversions that can be done with using a single conversion algorithm. Each ConversionInformation object represents a single conversion by specifying an input and an output mime type.


17/22

Specification of the Format Conversion Service – Specification of Parameter Types

Name

Data Type

Description


Input

OA_MimeType

The input format of the data

1 / mandatory

output

OA_MimeType

The output format of the data

1 / mandatory

Boolean

Since some conversions can degrade the quality of the given data, this operation indicates whether a conversion uses at least one lossy conversion adapter.

1 / mandatory

isLossy

Table 5 Attributes of the service specific capabilities of section availableOrdinaryConversions

18/22

Specification of the Format Conversion Service –

8

Known Issues and Limitations

8.1.1

Support for streamed I/O In the current specifications only files are considered. Maybe support is needed also for streamed input and output. e.g. one company has a video in one format (consider a very large file) and wants to convert in another format for immediate display. Considering the current specifications, at the beginning the video has to be uploaded to your service, then converted (in its entirety), and then to be sent back. This procedure can take a lot of time for huge file sizes. To improve the efficiency a streamed input and output may be considered. If streamed I/O is possible depends on the source- and target-format on the one hand and on the chosen target-platform.

8.1.2

Cooperation and Cascading between Service Instances In the context of the Format Conversion Service the following question has raised. Consider a service has multiple instances in an OSN. Instances of services can each have different capabilities. In the case of the Format Conversion Service, each instance can support different conversions. The question is now, what the capabilities of each service are? The capabilities supported by the current instance or the union of the capabilities of all instances? The same question can be asked for the conversion itself. In the first case another question raises. How does a user locate the correct service instance for his task? A possible solution could be to use a catalogue service to find an appropriate instance. In the second case service instances would have to cooperate. The service instance of the service request (getCapabilities, conversion) would figure out the correct service instance and delegate the request to an appropriate instance without any involvement of the service requestor. The service cooperation is not intended to make any catalogue service obsolete. This approach is based on the assumption that a communication between two service instances can be very effective since they know their own structure very well and thus additional meta-information is not required to delegate any request. Surely, there are more approaches to handle this scenario. In the following a few others will be drafted. Precondition: There are multiple service instances for a certain service. Requirement: The distribution of the service (multiple service instances) should be invisible to the service client. Examples: Services: • Format Conversion Service (FCS) o What if the current service instance does not support the requested conversion but another instance does? • Document Access Service (DAS) o What if there are multiple DAS instances? How to find a certain document? How to find the instance having a certain document? Possible Solutions: 1. A service client has to contact the proper service having the needed capability. The problem of finding the correct instance is the service client’s problem. Discussion:

19/22

Specification of the Format Conversion Service –

Of course, this in not really a solution! Every client would have to solve this problem if it occurs. There would be no reusability at all. 2. A service client always contacts a catalogue service to determine services offering the formatconversion in question. Possible hits may be different Format Conversion Service instances and service-chains (possible defined and annotated by the Service Chain Access Service). 3. A service client may direct the request to any service instance. A “broker” locates all registered services, checks their capabilities and chooses a proper instance. It delegates the service request to the found instance and redirects the result to the service requestor. Such a broker would make use of Catalogue Services containing service-descriptions especially of Format Conversion Services and a Service Chain Access Service.

20/22

Specification of the Format Conversion Service – Appendix A: Abstract Test Suite (normative)

9

Appendix A: Abstract Test Suite (normative) When creating an implementation specification of the Format Conversion Service, the “Rules for Implementation Specifications of ORCHESTRA Services” defined in chapter 9.2.2.3 and the “Rules for the Service Mapping to a given Platform” of the RM-OA shall be obeyed. In addition, the following tests shall be performed to ensure conformance of an implementation specification to the platform-independent specification of the Format Conversion Service: 1. Syntactical Conformance •


•


•


•




Additional conformance checks that are specifically to the Format Conversion Service are not required.

21/22

Specification of the Format Conversion Service – Appendix B: UML Models (normative)

10



22/22




Specification of the Gazetteer Service

Revision

1/15

[0.2 / 2.2.2]

Specification of the XXX Service – Document Control Page



Creator

Coraboeuf Damien, BRGM

Subject


Description

This document defines an abstract and platform independent formal specification of the Gazetteer Service.

Publisher


Contributor

Coraboeuf Damien, BRGM Comte Jérémy, BRGM

Date

2006-01-02

Type

Text

Format

application/msword

Identifier


Source

Not applicable

Language

en

Relation

none

Coverage


Rights

D3.4.2

Deliverable number

D3.4.4


WP3.4


2008-01-10


2008-01-10

Audience


Version number

0.2 / 2.2.2

Date

2006-01-02

Modified by

Comte Jérémy, BRGM

Comments Status

Draft WP leader accepted SP leader accepted Technical supervisor accepted

2/15

Specification of the XXX Service – Document Control Page

Quality checked Project coordinator accepted Action requested


3/15

Revision History


Date

Sections changed

Description

0.1 / 1.6

2006-01-02

all

Document created

0.2 / 2.2.2

2008-01-10

all

Added additional parameters to the service interface, some considerations about security issues, implementation issues and some minor reviews on data types. Modifications according template ver. 2.2.2

4/15


Table of Contents 1

Foreword .....................................................................................................................................................7

2

Conventions ................................................................................................................................................8

3

4

2.1

Abbreviations .......................................................................................................................................8

2.2


2.3

UML Notation .......................................................................................................................................8

2.4

Conformance........................................................................................................................................8

2.4.1


2.4.2


Overview and Architecture Outline..............................................................................................................9 3.1

Role and Scope and of the Gazetteer Service ....................................................................................9

3.2

Service Interface Specification Summary ..........................................................................................10

Context of the Gazetteer Service ..............................................................................................................11 4.1

Relations to Standards.......................................................................................................................11

4.1.1

OGC Gazetteer Service ..............................................................................................................11

4.1.2

ADL Gazetteer Protocol ..............................................................................................................11

4.1.3

Comparison between OGC and ADL Gazetteers.......................................................................12

4.1.4

Relation of Orchestra Gazetteer service to standards................................................................12

4.2

Relations to other OA and OAS Service Specifications.....................................................................12

4.3

Relations to ORCHESTRA Application Schemas..............................................................................12

4.4


4.5

Requirements.....................................................................................................................................12

4.5.1

Security Requirements ...............................................................................................................12

4.5.2

Reliability Requirements .............................................................................................................12

4.5.3

Relations to ORCHESTRA User and System Requirements.....................................................13

4.6

Service Interface Specification...........................................................................................................13

4.6.1

5

Specification of the Service Interface Operations.......................................................................13

4.7

Specification of extended Service Capabilities ..................................................................................14

4.8

Known Issues and Limitations ...........................................................................................................14

Appendix A: Abstract Test Suite (normative) ............................................................................................15

5/15


Tables Table 1: Summary of Service Operations ........................................................................................................10 Table 2: Interaction between related services..................................................................................................12 Table 3 Specification of OAS_Capabililites ......................................................................................................14

Diagrams Diagram 1: Class diagram of interface GazetteerService ................................................................................10 Diagram 2 - Class diagram of interface GazetteerService...............................................................................13 Diagram 3 - Class diagram for service capabilities ..........................................................................................14

6/15


1

Foreword This document is an abstract specification of the Gazetteer service and is based on the Template for the abstract Specification of ORCHESTRA Service Types version 2.2.2. It updates the specification version 0.1. The changes concerns all the sections by taking into account the new template version and some issues concerning security, service chain instance management. This document includes two annexes: Appendix A: Abstract Test Suite (normative) is mandatory

7/15

Tables and Diagrams

2

Conventions

2.1

Abbreviations The abbreviations used in this document are defined in chapter 3.1 of the Reference Model for the ORCHESTRA Architecture Version 2.0 (RM-OA) and in chapter 2.1 of the referenced interface type specifications.

2.2

Terms and definitions Terms and definitions necessary for understanding this document are defined in chapter 3.2 of the RMOA Glossary .

2.3


2.4 2.4.1


2.4.2


8/15

3 Overview and Architecture Outline

3 3.1

Overview and Architecture Outline Role and Scope and of the Gazetteer Service The Gazetteer Service allows to relate a geographic name (e.g. city, lake, region but also street) to a geographic location (i.e. a point, line, polygon or sets of these; might be also post codes = polygons). A client can provide a geographic name and is returned a location or a client can provide a location and is returned a geographic name. The Gazetteer Service is a feature access service and can also be transactional, allowing the extension and updates of the underlying gazetteer, e.g., by making request of geographic name updates or geometry updates. If this is the case, the gazetteer service also needs to include authorization.

Formally, a Gazetteer service is extending a Feature Access Service. The Gazetteer specific operations are performed though queries of the features. Query language must be able to: •

request against non spatial properties (already done in FAS)

•

request against spatial properties (already done in FAS)

•

request using thesaurus classes (extension to FAS)

•

request using some code schemes (extension to FAS)

Gazetteer entries (i.e. features) can be searched for like every feature using their properties (either spatial or not).

Typically, gazetteer instances are using dedicated feature types for their entries, specialized in rendering spatial locations and relationships between them. For example, the OGC gazetteer is using ISO 19112 schema and ADL is using another specialized format.

Thesaurus links between features are provided using some external thesauri, by accessing some Thesaurus Access services. Therefore, a Gazetteer Service instance must publish, in its capabilities, the list of accessible thesauri. Relationship between thesaurus terms should be language-neutral (i.e. A can be a synonym of B even if A and B are from different languages – see the Thesaurus Access Service description on this subject).

Gazetteer entries (i.e. features) can be searched for using some codes provided by external code schemes. A code schema is a set of codes, identified by a namespace. List of code schemas recognized by the Gazetteer Service must be published by its capabilities. Example: given the code scheme “FIPS 5-2”, a query looking for features that have code “06” in this scheme will return the state of California.

Both querying by thesaurus link or code schemes needs an extension of the query language to be used. Available compliant languages must be listed in the Gazetteer Service capabilities. Those languages need to support requests like: •

look for features belonging to a thesaurus term

•

look for features which are related / antonym / broader / … to a thesaurus term

•

look for features which have a given code in a given code scheme

9/15

3 Overview and Architecture Outline

3.2

Service Interface Specification Summary cd Gazetteer Serv ice - Ov erv iew RMOAService «interface» FeatureAccessService + + + + + + + + +

getCapabilities(OAS_GetCapabilitiesRequest) : OAS_MI_Service_Capabilities getFeatureType(OAS_Query) : list setFeatureType(list) : void createFeatureType(list) : void deleteFeatureType(OAS_Query) : void getFeatures(OAS_Query) : OAS_FeatureCollection setFeatures(OAS_Query, OAS_FeatureCollection) : OAS_String createFeatures(OAS_Query, OAS_FeatureCollection) : void deleteFeatures(OAS_Query) : void

«interface» GazetteerService

Diagram 1: Class diagram of interface GazetteerService

Operation n/a

Description The Gazetteer does not offer any supplementary operation. Table 1: Summary of Service Operations

10/15

4 Context of the Gazetteer Service

4

Context of the Gazetteer Service

4.1

Relations to Standards Two standards exist concerning gazetteer services: OGC and ADL.

4.1.1

OGC Gazetteer Service The OGC Gazetteer profile (WFS-G) is a document dating from September 2001, with version 0.0.9. No change has been done since. From OGC point of view, a gazetteer is a profile of WFS: •

It provides a new filter mechanism to request on relationships between features.

•

Feature types served by the WFS-G are based on ISO19112 (SI_LocationInstance).

WFS-G is an extension of WFS to support thesaurus links between features. But those relationships are limited to three kinds: broader, narrower and related. 4.1.2

ADL Gazetteer Protocol Alexandria Digital Library Gazetteer is a protocol for asking gazetteer data, independent from OGC but using some GML features. It defines a specific language for queries. It has capabilities for thesauri (classification) and relationships between features. A gazetteer entry is defined by a fixed set of attributes: •

identifier

•

zero or more codes

•

status (former, current, proposed)

•

one or more names

•

footprint (approximation of the location of the place)

•

zero or more classes (association with terms from vocabularies or thesauri)

•

relationships with other gazetteer entries

Those attributes may be modified by a primary qualifier, indicating the priority status of this attribute (names, footprints, status, and classes). This gazetteer entry description could be represented in Orchestra using a dedicated feature type.

ADL defines following operations for a Gazetteer service: •

getCapabilities – returns capabilities of the service (list of supported operations, the thesauri the gazetteer is using…)

•

query – returns reports for the gazetteer entries that match the query. Reports can be queried in standard or extended form. Geometry languages and query languages that are supported by the gazetteer are listed in its capabilities.

•

download – returns standard or extended reports for all entries in the gazetteer.

A port to XML/HTTP is provided by the ADL specifications.

Links with thesauri are provided through ADL Thesaurus protocol.

11/15

4.1.3

4 Context of the Gazetteer Service Comparison between OGC and ADL Gazetteers ADL Gazetteer is more mature that OGC Gazetteer specification but it does not rely on any related standard (ISO19112…). It has also no capability for transactions (adding and editing gazetteer entries). ADL Gazetteer offers a far better support for thesaurus links between features. Since WFS-G is extending WFS, it supports advanced features like querying against any attribute type. Both ADL and OGC offer capabilities of querying against spatial attributes, but set of spatial operators is richer in OGC.

4.1.4

Relation of Orchestra Gazetteer service to standards Neither of those standards is directly used as a basis for Orchestra Gazetteer Service. But concepts like thesauri links and code schemes issued from ADL are incorporated, using if necessary other Orchestra services. In particular, the Gazetteer Service is not responsible for dealing with thesauri but will delegate all searches for links to a Thesaurus Access Service. We have also seen that existing gazetteers are using dedicated schemas for the gazetteer entries, and not only “geographic locations”. Therefore, we can rely on Orchestra feature type model to create feature types that are specialized for the gazetteer (for example, on implementation side, such a feature type could be ISO 19112).

4.2

Relations to other OA and OAS Service Specifications Name

Service Type


OA

Service Operation Inheritance

Table 2: Interaction between related services

4.3

Relations to ORCHESTRA Application Schemas Gazetteer service instances shall rely on one or more dedicated feature types, as any instance of feature access service.

4.4

Relations to ongoing Initiatives and related Projects

4.5

Requirements

4.5.1

4.5.2

Security Requirements •

Which security considerations have to be made?

•

Are there any special requirements that go beyond the scope of the Authorization and the Authentication Service?


How to grant, provide, assure and grant reliability? (e.g. does this service support transactions (in the database sense)?)

•

How does Exception Handling work? Note: Exception Types shall be described in chapter Fehler! Verweisquelle konnte nicht gefunden werden..

•

Does this service depend on other services? If yes, briefly describe the behaviour if one of these services fails. (please refer also to chapter 4.2 if necessary)

12/15


4.5.3

4.6 4.6.1

Relations to ORCHESTRA User and System Requirements

Service Interface Specification Specification of the Service Interface Operations cd Gazetteer Serv ice - Ov erv iew RMOAService «interface» FeatureAccessService + + + + + + + + +

getCapabilities(OAS_GetCapabilitiesRequest) : OAS_MI_Service_Capabilities getFeatureType(OAS_Query) : list setFeatureType(list) : void createFeatureType(list) : void deleteFeatureType(OAS_Query) : void getFeatures(OAS_Query) : OAS_FeatureCollection setFeatures(OAS_Query, OAS_FeatureCollection) : OAS_String createFeatures(OAS_Query, OAS_FeatureCollection) : void deleteFeatures(OAS_Query) : void

«interface» GazetteerService

Diagram 2 - Class diagram of interface GazetteerService

The Gazetteer service is extending the Feature Access Service and does not provider any supplementary operation.

13/15


4.7

Specification of extended Service Capabilities cd Gazetteer Serv ice - Capabilities OAS_SchemaEntry ODAS_Capabilities OMAS_Capabilities «type» OAS_M I_Serv ice_SpecificCapabilities Is it the right to define that the Gazetteer service is supporting the given thesauri ? Or should we use a different type of link ?

RMOAService

«type» GazetteerServ iceCapabilities -

+thesaurus 0..*

codeSchem e: CharacterString [0..*]

«interface» ThesaurusAccessServ ice

Diagram 3 - Class diagram for service capabilities Name

Data Type

Description

thesaurus

ThesaurusAccessService

The service exposes which thesauri it is using.

codeScheme

CharacterString

Identifier or namespace for a code schema that can be used for queries.

Table 3 Specification of OAS_Capabililites

4.8

Known Issues and Limitations

14/15

4.6.1 Specification of the Service Interface Operations

5

Appendix A: Abstract Test Suite (normative) When creating an implementation specification of the Gazetteer Service, the “Rules for Implementation Specifications of ORCHESTRA Services” defined in chapter 9.2.2.3 and the “Rules for the Service Mapping to a given Platform” of the RM-OA shall be obeyed. In addition, the following tests shall be performed to ensure conformance of an implementation specification to the platform-independent specification of the Service Chain Access Service: 1. Syntactical Conformance •


•


•


•




Additional conformance checks that are specifically to the Service Chain Access Service are not required.

15/15




Specification of the Knowledge Base Interface

Revision

1/21

[1.0 / 1.1]

Specification of the Knowledge Base Interface – Document Control Page



Creator

Bügel, Ulrich

Subject


Description

This document defines an abstract and platform independent formal specification of a Knowledge Base interface.

Publisher


Fraunhofer IITB

Contributor Date

2007-08-17

Type

Text

Format

application/msword

Identifier


Source

Not applicable

Language

en-GB.

Relation

none

Coverage



D3.4.4


WP3.4



Version number

1.0 / 1.1

Date

2007-08-17

Modified by

Bügel, Ulrich

Fraunhofer IITB

Comments Status


2/21

Specification of the Knowledge Base Interface – Document Control Page



3/21

Specification of the Knowledge Base Interface – Revision History


Date

Sections changed

Description

0.1 / 2.03

2006-05-09

0.2 / 2.03

2006-07-28

0.3 / 2.03

2006-08-29

Minor corrections for D3.4.2

1.0 / 1.1

2007-08-17

Transformed from a Service Specification to an Interface Specification

all

Incorporated Review Comments of JRC

Incorporated Comments from JRC

4/21

Specification of the Knowledge Base Interface – Table of Contents

Table of Contents 1

Foreword .....................................................................................................................................................7

2

Conventions ................................................................................................................................................8 2.1

Abbreviations .......................................................................................................................................8

2.2


2.3

UML Notation .......................................................................................................................................8

2.4

Conformance........................................................................................................................................8

2.4.1 3


4

4.1


4.2


4.2.1

SPARQL .................................................................................................................................... 10

4.2.2

Jena ........................................................................................................................................... 10

4.2.3

Joseki......................................................................................................................................... 11

4.2.4

Sesame...................................................................................................................................... 11


Specification of the Knowledge Base Interface........................................................................................ 13 5.1

Specification of an OAS Profile of Parameter Types used by the Knowledge Base Interface ......... 14

5.2


5.2.1

Specification of the queryModel Operation................................................................................ 15

5.2.2

Specification of the updateModel Operation.............................................................................. 16

5.3


5.3.1

OA_KB_modelRef...................................................................................................................... 18

5.3.2

OA_KB_modelElement.............................................................................................................. 19

5.3.3

OA_KB_Result........................................................................................................................... 19

5.4 6

Role and Scope of the Knowledge Base Interface ..............................................................................9

Context of the Knowledge Base Interface................................................................................................ 10

4.3 5


Known Issues and Limitations .......................................................................................................... 20

Appendix A: UML Models (normative) ..................................................................................................... 21 6.1

XMI Model ......................................................................................................................................... 21

5/21

Specification of the Knowledge Base Interface – Tables and Diagrams

Tables Table 1: Summary of inherited Interface Operations................................................................................. 14 Table 2: Summary of additional Interface Operations ..................................................................................... 14 Table 3: Referenced OA Types ....................................................................................................................... 15 Table 4: Specification of the queryModel Operation ....................................................................................... 16 Table 5: Specification of the updateModel Operation ..................................................................................... 17 Table 7: Summary of additional OA Types...................................................................................................... 17

Diagrams Diagram 1: Class Diagram of the Knowledge Base Interface ......................................................................... 13 Diagram 2: Summary of types defined in the Knowledge Base Interface ....................................................... 18

6/21

Specification of the Knowledge Base Interface – UForeword

1

Foreword This document is an abstract specification of the Knowledge Base interface type and is based on the Template for the abstract Specification of ORCHESTRA Interface Types version 1.1. It replaces the specification version 0.3. A replacement of chapters was required due to the transformation of the document from a service specification to an interface specification. This document includes one mandatory annex: Appendix A: UML Models (normative).

7/21

Specification of the Knowledge Base Interface – UConventions

2

Conventions

2.1

Abbreviations The abbreviations used in this document are defined in chapter 3.1 of the Reference Model for the ORCHESTRA Architecture Version 2.1 (RM-OA), except for the following abbreviated terms: •

2.2

KB

Knowledge Base

Terms and definitions Terms and definitions necessary for understanding this document are defined in chapter 3.2 of the RMOA Glossary, except for the following terms: •

Knowledge Representation Model A model for the representation of information as modelled graphs.

2.3


2.4 2.4.1

Conformance Conformance to the OMM This abstract service interface specification is specified according to the rules of the ORCHESTRA Service Meta-model (OMM-Service) and follows the rules for ORCHESTRA Services as described in chapter 9.2 of the RM-OA.

8/21

Specification of the Knowledge Base Interface – Role and Scope of the Knowledge Base Interface

3

Overview and Architecture Outline The Knowledge Base Service provides facilities to access and update information available in a graphbased knowledge representation format, e.g. RDF graphs.

3.1

Role and Scope of the Knowledge Base Interface The Knowledge Base Interface provides access to a knowledge base in an OSN. The knowledge base can store identifiable units of knowledge, in the sequel referred to as “models”. A model has a uniform resource identifier (URI). The Knowledge Base Interface conveys query requests to models received via the OSN to the knowledge base’s local processing engine and returns the results to the OSI that requested them. The Knowledge Base Interface abstracts from existing languages for knowledge representation and querying, but it assumes that some concepts are common to most of them: -

Knowledge is represented as a graph, i.e. a number of nodes and edges.

-

The knowledge graph is divided into a number of sub-graphs, so called “models”.

-

Models are described by a number of basic elements constituting the model graph; these elements describe the nodes and the edges. Updates of a model can be performed by adding/deleting basic elements.

The Knowledge Base Interface provides operations to query and update models contained in the knowledge base. Future versions of this specification may comprise functions such as add/remove model. Queries are to be formulated in a query language that is compatible with the queried model. As opposed to the Feature Access Service, the result of such a request does not necessarily need to be a feature set: the service may deliver results of any format, from complete models down to boolean values. The Knowledge Base interface abstracts from the format of the result of queries, it depends on the model and the query language used. Update requests to a model contain the new elements, which are to be added to the model, and the elements to be deleted. In order to obtain information about models and query languages supported the getCapabilites operation of the interface Service Capabilities is to be used. The main difference of a knowledge base approach to conventional SQL databases is that a knowledge base is more flexible: models can be added or removed during run time and there is no fixed database schema. A knowledge base can have a schema defined through an ontology (e.g. RDFS or OWL as schema of an RDF knowledge base), but it does not necessarily need one.

4

9/21

Specification of the Knowledge Base Interface – Relations to Standards

Context of the Knowledge Base Interface In this chapter, the relations of this specification to international standards and ongoing initiatives shall be explicated.

4.1

Relations to Standards The Knowledge Base Interface does not rely on any existing languages for knowledge representation and – querying in particular, put it assumes that some concepts are common to most of them. In particular, it is assumed that -

Knowledge is represented as a graph, i.e. a number of nodes and edges. In RDF, for instance, statements have a representation “subject predicate object”, i.e. they are directed graphs with “subject” representing the start node, “predicate” representing the edge and “object” representing the end node of a statement.

-

The knowledge graph is divided into a number of sub-graphs, so called “models”. Models can be added to/removed completely from a knowledge base. To utilize a model, it not necessarily needs to be physically present in the knowledge base, it can just be referred to and physically be stored at any other location. A prerequisite for that is that models have a Uniform Resource Identifier (URI).

-

The knowledge graph of a model is described by a number of basic elements constituting the graph; these elements describe the nodes and the edges. In RDF for instance, a “statement” is such a basic element. Updates of a knowledge base can be performed by adding/deleting basic elements.

A number of knowledge representation and query languages are available. The abstract specification of the Knowledge Base Service in this document abstracts from concrete languages and platform specific issues. The mapping to concrete languages is to be done in the Implementation Specification. RDF is an example for a standard which fulfils the assumptions described above. In RDF, for instance, “statements” are the basic elements. SPARQL is a query language for RDF models. The SPARQL Protocol uses WSDL 2.0 to describe a means for conveying SPARQL queries to a SPARQL query processing service. The Knowledge Base Interface can partly be implemented by means of RDF storage and SPARQL queries, but other implementations are possible. The SPARQL protocol provides a standard to be used with high preference for implementation. However, in its current version, the SPARQL language only defines “query” operations, the “update” function is yet missing.

4.2 4.2.1

Relations to ongoing Initiatives and related Projects SPARQL SPARQL is developed by the W3C RDF Data Access Working Group. SPARQL is a standardized query language for RDF data: Reference: http://www.w3.org/TR/rdf-sparql-query/ The SPARQL Protocol uses WSDL 2.0 to describe a means for conveying SPARQL queries to a SPARQL query processing service and returning the query results to the entity that requested them. Reference: http://www.w3.org/TR/rdf-sparql-protocol/

4.2.2

Jena Reference: http://jena.sourceforge.net/ Jena is a Java framework for building Semantic Web applications. It provides a programmatic environment for RDF, RDFS and OWL, SPARQL and includes a rule-based inference engine.

10/21

Specification of the Knowledge Base Interface – Relations to ORCHESTRA Application Schemas Jena is open source and grown out of work with the HP Labs Semantic Web Programme. The Jena Framework includes: -

A RDF API

-

Reading and writing RDF in RDF/XML, N3 and N-Triples

-

An OWL API

-

In-memory and persistent storage

-

SPARQL query engine

Jena is a candidate for implementation of a Knowledge Base Interface. 4.2.3

Joseki Reference: http://jena.sourceforge.net/ Joseki is an HTTP and SOAP engine that supports the SPARQL Protocol and the SPARQL RDF Query language. Joseki Features: -

RDF Data from files and databases

-

HTTP (GET and POST) implementation of the SPARQL protocol

-

SOAP implementation of the SPARQL protocol

Joseki is a candidate for implementation of the SPARQL Protocol. 4.2.4

Sesame Reference: http://sourceforge.net/projects/sesame/ Sesame is an open source RDF database with support for RDF Schema inferencing and querying. Sesame Features:

4.3

-

can be deployed on top of a variety of storage systems (relational databases, in-memory, filesystems, keyword indexers, etc.)

-

flexible access API, which supports both local and remote (through HTTP or RMI) access

-

several query languages including SeRQL, RQL, RDQL and (in Sesame 2.x) SPARQL.

Relations to ORCHESTRA Application Schemas The Knowledge Base Interface Type Specification uses Basic and OA Types that are defined in the package OAS/Basic Types, OAS/OA Types and OAS-MI/OA-MI Types of the Information Viewpoint. •

CharacterString

•

Feature Type OA_Query, OA_Query_Language, OA_URI, OA_MimeType

The Knowledge Base Interface Type Specification uses OA-MI Types that are defined in the package OAS-MI/OA-MI Types of the Information Viewpoint. •

Service Capabilities OAS_MI_ServiceCapabilities, OAS_MI_ServiceSpecificCapabilities,

•

Knowledge Base Service Specific Capabilities OAS_MI_KB_SpecificCapabilities

11/21

Specification of the Knowledge Base Interface – Relations to ORCHESTRA Application Schemas The Knowledge Base Interface Type Specification defines new parameter types. •

OA_KB_modelRef, OA_KB_resultFormat, OA_KB_modelElement, OA_KB_modelElementSet

5

12/21

Specification of the Knowledge Base Interface – Relations to ORCHESTRA Application Schemas


cd Know ledge Base Interface «interface» OA_TransactionInterface

«interface» Know ledgeBaseInterface + + +

queryM odel(OA_KB_m odelRef, OA_Query) : OA_KB_result queryM odel(OA_KB_m odelRef, OA_Query, OA_M im eT ype) : OA_KB_result updateM odel(OA_KB_m odelRef, OA_KB_m odelElem entSet, OA_KB_m odelElem entSet) : void

Diagram 1: Class Diagram of the Knowledge Base Interface

This specification of the Knowledge Base Interface extends the following interfaces: •

The Transaction Interface of the OA Basic Service Specification

The Knowledge Base interface uses the following operations of inherited interfaces:

Interface Name Transaction Interface

Operation Name

Specialisation

createAcidTransaction

No

createBusinessTransaction

No

createSubAcidTransaction

No

createSubBusinessTransaction

No

setImplicitCommit

No

setRollbackOnFailure

No

setLockOwner

No

startTransaction

No

tryCommit

No

commitTransaction

No

13/21

Specification of the Knowledge Base Interface – Specification of an OAS Profile of Parameter Types used by the Knowledge Base Interface

abortTransaction

No

suspendTransaction

No

resumeTransaction

No

getActiveTransaction

No

addTransactions

No

Table 1: Summary of inherited Interface Operations Table 1 does not list optional operations that are not used by this service. The Knowledge Base interface defines the following additional operations:

Operation Name

Description

queryModel

Submits a query to a model stored in the knowledge base.

updateModel

Submits a request to add or delete elements of a model. Table 2: Summary of additional Interface Operations

5.1

Specification of an OAS Profile of Parameter Types used by the Knowledge Base Interface The following non basic types are used within this specification:

Name

Usage

from OAS

New

OA_KB_modelRef

I

OA_Types

Yes

OA_Query

I

OA_Types

No

OA_KB_modelElementSet

I

OA_Types

Yes

OA_MimeType

I

OA_Types

Yes

OA_KB_result

O

OA_Types

Yes

OA_No_Such_Model

E

OA_Types

Yes

OA_IllegalQuery

E

OA_Types

Yes

OA_UnknownResultFormat

E

OA_Types

Yes

OA_NoSuchElements

E

OA_Types

Yes

14/21

Specification of the Knowledge Base Interface – Specification of the Operations

OA_UnknownElementFormat

E

OA_Types

Yes


5.2


5.2.1

Specification of the queryModel Operation The mandatory queryModel operation submits a query to a model stored in the KB. The model to which the request is to be sent to is referenced by an URI. The query is formulated in a query language which must be compatible to the knowledge representation model used by the KB. The service conveys the request to the KB, which executes the query and composes the result in the required result format (parameter resultFormat). If the resultFormat parameter is not present, the result is delivered in a default format. The signatures of the operation is •

OA_KB_result queryModel (model, query, resultFormat) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_NoSuchModel, OA_IllegalQuery, OA_UnknownResultFormat

Overrides

not applicable

Preconditions

The knowledge base should contain a model to which the query can be addressed to.

Post conditions

none

Use

mandatory

Receives

Name

Type

Description

model

OA_KB_modelRef

mandatory

The model to which the query is to be conveyed to.

query

OA_Query

mandatory

The query formulated in a query language.

resultFormat

OA_MimeType

optional

The result format requested by the client.

Returns

Type

Description The result of the query in the requested result format.

OA_KB_result Throws

Use

Type OA_NoSuchModel

Cause The KB does not contain the model specified in the request.

15/21

Specification of the Knowledge Base Interface – Specification of the Operations

OA_IllegalQuery

The query contained in parameter “query” cannot be performed by the service (e.g. syntax error, query language incompatible to model).

OA_UnknownResultFormat

The requested result format cannot be handled by the service.

Table 4: Specification of the queryModel Operation 5.2.2

Specification of the updateModel Operation The optional updateModel operation submits an update request to a model stored in the KB. The model to which the request is to be sent to is referenced by an URI. The request contains the set of model elements to be added and the set of elements to be deleted. The service conveys the request to the KB, which executes the update request. The signatures of the operation is •

void updateModel (model, elementsToAdd, elementsToDelete) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_NoSuchModel, OA_NoSuchElements, OA_UnknownElementFormat

Overrides

not applicable

Preconditions

The KB should contain a model to which the update request can be addressed to.

Post conditions

none

Use

optional

Receives

Name

Type

Use

Description

model

OA_KB_modelRef

mandatory

The model to which the update request is to be conveyed to.

elementsToAdd


mandatory

The set of model elements to be added to the model.

mandatory

The set of model elements to be deleted from the model.

elementsToDelete

Returns


Type

Description

void Throws

Not applicable Type

Cause The knowledge base does not contain the model specified in the request.

OAS_NoSuchModel

16/21

Specification of the Knowledge Base Interface – Specification of Parameter Types

OAS_NoSuchElements

The elements listed in the elementsToDelete parameter are not part of the requested model.

OAS_UnknownElementFormat

The elements listed in the elementsToAdd or elementsToDelete parameters have a format that cannot be handled by the requested model.

Table 5: Specification of the updateModel Operation

5.3

Specification of Parameter Types This interface specification defines new OA Types.

Name

Usage

from OAS

New

OA_KB_modelRef

I

OA_Types

Yes


I

OA_Types

Yes

OA_Types

Yes

OA_Types

Yes

OA_KB_modelElement OA_KB_result

O

Table 6: Summary of additional OA Types

These new OA Types will become part of the OAS OA Types. This interface specification does not define any new OT Types. This interface specification does not introduce any new non-orchestra Types.

17/21

Specification of the Knowledge Base Interface – Specification of Parameter Types cd Know ledge Base Interface «enum eration» OA_KB_modelType + + + + + +

RDF: RDFS: OWL: DAM L+OIL: unknown: ...:

«type» OA_KB_modelRef + +

«DataT ype» OA_Query

KB_m odelURI: OA_URI type: OA_KB_m odelT ype

+ +

language: OA_QueryLanguage language: OA_QueryLanguage query: CharacterString query: CharacterString

«type» OA_KB_result

When a m odel is transferred, it is usually given as a sem i-structured docum ent with an xm l syntax. In special cases, it can be expressed as unstructured, plain text. M im e types could be application/rdf+xm l application/owl+xm l application/xm l plain/text

+ +

form at: OA_M im eT ype result: CharacterString

«type» OA_KB_modelElementSet +

elem entForm at: OA_M im eT ype

1..* «type» OA_KB_modelElement +

m odelElem ent: CharacterString

Diagram 2: Summary of types defined in the Knowledge Base Interface 5.3.1

OA_KB_modelRef cd Know ledge Base Interface «enum eration» OA_KB_modelType + + + + + +

RDF: RDFS: OWL: DAM L+OIL: unknown: ...:

«type» OA_KB_modelRef + +

KB_m odelURI: OA_URI type: OA_KB_m odelT ype

This OA_Type specifies a reference to a model in a KB. A KB contains knowledge that is represented as nodes and edges, a “knowledge graph”. A KB is assumed to contain a number of “models”, each model thereby contains a subgraph of the KB’s knowledge graph. Each model must be referable by an URI. In a distributed KB, external models can be referenced.

18/21

Specification of the Knowledge Base Interface – Specification of Parameter Types A knowledge graph can be composed according to the rules of a W3C standard, e.g. RDF, RDFS or OWL. If the type of the model is known, the type parameter of the modelRef may be set respectively. This type is used to refer to a model in query and update requests to the KB. 5.3.2

OA_KB_modelElement cd Know ledge Base Interface «type» OA_KB_modelElementSet +

elem entForm at: OA_M im eT ype

1..* «type» OA_KB_modelElement +

m odelElem ent: CharacterString

This OA_Type specifies an element of a model or a set of elements of a model, respectively. The graph of a model consists of a set of elements. Each element describes a part of the model graph. In update requests sent to the KB, the elements to be added rsp. delete must be referable. The transfer syntax of the model elements (parameter elementFormat) must be compatible the model type, e.g. an RDF model is composed of “RDF-Statements” and the elementType should thus be “application/rdf+xml”. This type is used to specify sets of model elements to be added or deleted in an update request. 5.3.3

OA_KB_Result cd Know ledge Base Interface

When a m odel is transferred, it is usually given as a sem i-structured docum ent with an xm l syntax. In special cases, it can be expressed as unstructured, plain text. M im e types could be application/rdf+xm l application/owl+xm l application/xm l plain/text

«type» OA_KB_result + +

form at: OA_M im eT ype result: CharacterString

This OA_Type specifies the result of a query request to a KB. The result is expressed as a new model in a transferable format. The format of a model can be expressed by a mime type, e.g. -

application/rdf+xml

-

application/owl+xml

-

application/xml

-

plain/text

19/21

Specification of the Knowledge Base Interface – Known Issues and Limitations When a model is transferred, it is usually given as a semi-structured document in XML syntax. In special cases, it can be expressed as unstructured, plain text. For instance, the model resulting from a query to a KB can deliver a boolean value. This can be expressed as a result string (containing “TRUE” rsp. “FALSE” as the string value). Alternatively, the result string can be encapsulated by an XML structure.

5.4

Known Issues and Limitations 1. As a restriction, the Knowledge Base Interface does not yet provide operations to add/delete complete models, just operations on models (query/update). The insertion of complete model is assumed to be performed via a local, administrative interface of the KB. The upload of complete models via the OSN may cause enormous workload, i.e. the models would have to be fragmented. This functionality may be of interest in future versions of this specification. 2. In the Implementation Specification, the KB Interface has to be mapped to a platform specific protocol. The SPARQL protocol provides a standard to be used with high preference for implementation. However, in its current version, the SPARQL language only defines “query” operations, the “update” function is yet missing.

20/21

Specification of the Knowledge Base Interface – UAppendix A: UML Models (normative)

6 6.1

Appendix A: UML Models (normative) XMI Model The XMI Models of this interface specification can be downloaded from the OGC Portal / ORCHESTRA website under the following URL: http://portal.opengeospatial.org/files/?artifact_id=23288

21/21




Specification of the Map and Diagram Service

Revision

1/24

[3.0 / 2.2]

Specification of the Map and Diagram Service – Document Control Page


Specification of the Map and Diagram Service

Creator


Subject


Description

This document defines an abstract and platform independent formal specification of the Map and Diagram interface.

Publisher


Contributor


ETH Zurich

Hugentobler Marco

ETH Zurich

ETH Zurich

Date

2007-08-28

Type

Text

Format

application/msword

Identifier


Source

Not applicable

Language

en-GB.

Relation

none

Coverage



D3.4.3


WP3.4


2007-09-30


2007-08-28

Audience


Version number

3.0 / 2.2

Date

2007-08-28

Modified by


Comments Status


2/24

ETH Zurich

Specification of the Map and Diagram Service – Document Control Page



3/24

Specification of the Map and Diagram Service – Revision History


Date

Sections changed

Description st

1.0 / 1.4

2005-09-8

all

1 release

1.1 / 1.4

2005-11-5

all

Corrections performed.

1.2 / 1.6

2005-12-02

all

Adapted to template v.1.6

1.3 / 1.6

2006-01-12

all

Internal review, modifications and general improvements

1.4 / 1.7

2006-02-13

all

Adapted to template v.1.7. Incorporates (some th of) the suggestions from the 12 SP3 meeting

1.5 / 1.7

2006-04-21

all

Introduction of extended SLD. General improvements.

2.0/2.0.4

2006-05-31

all

Map and Diagram Services are merged. Integration of draft Diagram Service Specifications v 1.0 in the Map Service Specifications v 1.5 for one harmonized Map and Diagram Service Specification. Adaptation to the usage of Basic Data Types. Refinements towards flexible usage of map definition documents – an extended version of SLD (Style Layer Descriptor) documents. New operations defined.

2.1/2.0.4

2006-06-20

all

Integration of comments from reviewers. Other comments still under evaluation.

2.2/2.0.4

2006-07-14

Section 6

Operation renamed to “getFeatureInfo” for OGC conformance.

2.3/2.0.4

2006-08-16

all

Integrated comments from reviewers. The symbolization modelled at the abstract level only by the mapAttributes parameter.

2.4/2.0.4

2007-01-16

all

Various operations renamed ORCHESTRA model.

3.0/2.2

2007-08-28

all

Final version of the specifications. Abstract Interface was extracted from the previous service specifications and documented separately.

4/24

according

to

Specification of the Map and Diagram Service – Table of Contents

Table of Contents 1

Foreword..................................................................................................................................................... 8

2

Conventions ................................................................................................................................................ 9 2.1

Abbreviations ....................................................................................................................................... 9

2.2


2.3

UML Notation....................................................................................................................................... 9

2.4

Conformance ....................................................................................................................................... 9

2.4.1


2.4.2


2.5 3

4

5

Used parts of other documents ........................................................................................................... 9


Role and Scope of the Map and Diagram Service ............................................................................ 10

3.2


Context of the Map and Diagram Service................................................................................................. 11 4.1


4.2


4.3


4.4


4.4.1


4.4.2


4.4.3


Requirements ........................................................................................................................................... 16 5.1


5.2


6

Specification of the Map and Diagram Interface....................................................................................... 16

7

Specification of the Service Specific Capabilities ..................................................................................... 17 7.1


8


9

Appendix B: UML Models (normative) ...................................................................................................... 23 9.1

XMI Model (mandatory) ..................................................................................................................... 23

9.2

Static UML Model (optional) .............................................................................................................. 23

5/24

Specification of the Map and Diagram Service – Table of Contents 9.3

Dynamic UML Model (optional) ......................................................................................................... 24

6/24

Specification of the Map and Diagram Service – Tables and Diagrams

Tables Table 1: Possible ORCHESTRA Services to be used by as remote sources ................................................. 13 Table 2: Sections of the service specific capabilities....................................................................................... 17 Table 3: Attributes of the service specific capabilities of section OA_MI_MS_Capabilities ............................ 17 Table 4: Attributes of the service specific capabilities of section OA_MI_OGC_Capabilities.......................... 18

Diagrams Diagram 1: Class Diagram of the Map and Diagram Service .......................................................................... 10 Diagram 2: Sequence Diagram of the getMap Operation referencing data available at remote sources ....... 12 Diagram 3: Overview Diagram of the Map and Diagram Service Capabilities ................................................ 19 Diagram 4: Diagram of the Map and Diagram Service Specific Capabilities Types........................................ 20

7/24

Specification of the Map and Diagram Service – Foreword

1

Foreword This document is an abstract specification of the Map and Diagram service and is based on the Template for the abstract Specification of ORCHESTRA Service Types version 2.2. It replaces any previous specifications of the Map and Diagram service. An update and refinement of chapters was required due to the separation of the service interface in its own document according to the latest version of the RM_OA. In addition the operations for loading styles and layers were eliminated in the Map Diagram Interface due to comments that such an administrative interface is too complicated for the time being, and that a balance between functionality and simplicity has to be achieved. This document includes two annexes: Appendix A: Abstract Test Suite (normative) is mandatory and Appendix B: UML Models (normative) is optional.

8/24

Specification of the Map and Diagram Service – Conventions

2

Conventions

2.1


2.2

- WMS

Web Map Service

- SLD

Styled Layer Descriptor

- SE

Symbology Encoding

- CRS

Coordinate Reference System

Terms and definitions Terms and definitions necessary for understanding this document are defined in chapter 3.2 of the RMOA Glossary. Please refer also to definitions contained in OGC 03-109r1 (OGC Web Map Service Interface), OGC 05-078 (Styled Layer Descriptor Profile of the Web Map Service Implementation Specification) and OGC 05-077r4 (Symbology Encoding Implementation Specification).

2.3


2.4 2.4.1


2.4.2


2.5

Used parts of other documents This document does not use parts of other documents. However, this specification assume that the reader has previous knowledge of OGC 03-109r1 (OGC Web Map Service Interface), OGC 05-078 (Styled Layer Descriptor Profile of the Web Map Service Implementation Specification) and OGC 05077r4 (Symbology Encoding Implementation Specification).

9/24

Specification of the Map and Diagram Service – Overview and Architecture Outline

3 3.1

Overview and Architecture Outline Role and Scope of the Map and Diagram Service

The Map and Diagram Service is a service that dynamically portrays geographic and statistical data using style definitions and symbolisation rules. Its main task is to produce maps and diagrams from geographic data (vector or raster) and/or statistical data (e.g. census data, result of a statistical analysis) as digital image files suitable for display on a computer screen. This service is able to create maps and diagrams based not only on data hosted on the server, but also on data provided by external services (e. g provided by Feature Access Services) or directly included in the request message as GML (sent as an optional part of the Styled Layer Definition). The main output of this service is an image document. The image document can be a map (visualization of geographic information and spatially referenced data), a diagram (visualization of statistical data) or a legend of a portrayed layer. Optionally, this service offers the possibility of querying information about the features portrayed in an image document or getting a comprehensive layer description (including Count, Minimum, Maximum, Sum, Mean, Standard Deviation, and Histogram for every attribute when appropriate). The output of these operations is an information document containing the requested information (when available). The maps and diagrams represent a visualisation of the data and they are not the data itself, thus they are generally rendered in a pictorial format such as PNG (recommended as default format), GIF or JPEG. Portrayal in vector-based graphical elements as Scalable Vector Graphics (SVG) or Web Computer Graphics Metafile (WebCGM) is also allowed if it is acceptable for the service provider. However usually it is desired that the original data can not be reconstructed from the portrayal. It is beyond of the scope of this service to provide a human interface like the geographic viewer in human interaction services. On the other side, other map service instances, a geographic viewer or even a web browser could act as a client to this service.

3.2

Service Specification Summary This service type specification of the Map and Diagram Service is comprised of the following interfaces that are defined in separate interface type specifications: •


•

The Map Diagram Interface Type

cd M ap and Diagram Serv ice MapDiagramInterface ServiceCapabilities «interface» M apDiagramService + + + + + + +

getCapabilities(request :OA_GetCapabilitiesRequest) : OA_GetCapabilitiesResponse getMap(GetMap :OA_GetMapType) : OA_GetMapResponse getDiagram(GetDiagram :OA_GetDiagramType) : OA_GetDiagramResponse getFeatureInfo(GetFeatureInfo :OA_GetFeatureInfoType) : OA_GetFeatureInfoResponse getLegendGraphic(GetLegendGraphic :OA_GetLegendGraphicType) : OA_GetLegendGraphicResponse getLayerDescription(GetLayerDescription :OA_GetLayerDescriptionType) : OA_GetLayerDescriptionResponse getStyle(GetStyle :OA_GetStyleType) : OA_GetStyleResponse

Diagram 1: Class Diagram of the Map and Diagram Service

10/24

Specification of the Map and Diagram Service – Context of the Map and Diagram Service

4

Context of the Map and Diagram Service

4.1

Relations to Standards Related standards are available from:

International Organisation for Standardisation: −

ISO/DIS 19128 – Web Map Service Interface (WMS)

−

ISO/CD 19136, ISO 19107, ISO 19108, ISO/PRF 19118, ISO/FDIS 19123 – Geography Markup Language

−

ISO/FDIS 19117 – Geographic Information - Portrayal

−

ISO/DIS 19119 – Geographic Information – Service Architecture

−

ISO/TS 19103 – Geographic information – Conceptual schema language

−

ISO 19125 – Geographic information – Simple Feature Access – Part 1: Common architecture

Open Geospatial Consortium: −

OGC 03-109r1 – Web Map Service Interface (WMS)

−

OGC 05-078 – Styled Layer Descriptor Profile of the Web Map Service Implementation Specification (SLD)

−

OGC 05-077r4 – Symbology Encoding Implementation Specifcation (SE)

−

OpenGIS Abstract Specification (AS) – Topic 12: OpenGIS Service Architecture

Adoption of standards: The Map and Diagram Service uses the existing standards as general guidelines and interoperability constraints. All the current work started from and is based on the above mentioned standards. The Map and Diagram Service uses specific capabilities types which are defined in the ISO/DIS 19128 standard. Methodology for the adoption of standards: All standards integrated by the Map and Diagram Service are to be platform neutral. For standards not available on the platform neutral level, only the relevant concepts are integrated. Modifications of the existing standards: Extensions to existing standards are necessary to fulfil the requirements for complex environmental data visualization (e.g. diagrams, diagram maps and choropleths). Therefore the WMS, SLD/ SE standards were extended towards a complete cartographic interface for advanced symbolization of features enabling distributed qualitative cartographical representations. Contribution to standards: Important extensions to OGC standards (mainly regarding thematic mapping) considered to be of interest also for OGC were sent to the appropriate working groups (DSS.WG, WMS.RWG, SLD.RWG). Appendix B of the Map and Diagram Service Abstract Interface Specification (http://portal.opengeospatial.org/files/?artifact_id=23466) contains the change requests (OGC 07-105 and OGC 07-106) submitted to September 2007 OGC TC Meeting in Boulder Colorado. No other active influence to standards is intended as ORCHESTRA deliverables are to be published in the public domain.

11/24


4.2

Relations to ongoing Initiatives and related Projects The INSPIRE technical discussions are monitored. INSPIRE efforts and interests converge more towards data harmonization and not towards portrayal harmonization. In this context the Map and Diagram Service is too complex compared with the requirements for a visualisation service as stated by the INSPIRE drafting teams. In the future, when interest in portrayal and portrayal harmonisation will probably arise, it is possible that the thematic extensions in combination with the getStyle operation defined by this service will provide a good starting point for portrayal harmonisation of geospatial data in Europe.

4.3

Relations to other ORCHESTRA Service Specifications The Map and Diagram Service supports symbolisation of geographical and tabular data available at remote sources (e.g. provided by other OA services: Feature Access Service and Source System Integration Service). The “getFeature” request is used for the communication with the remote services (e.g. Feature Access Service).

sd getM ap operation

Client/Service

«interface»

«interface»

M ap and Diagram Service

Rem ote Source [1..n]

getM ap

opt [FAS==T RUE] getFeatures

OA_Feature_Collection

OA_Im ageDocum ent (M ap or Diagram )

Diagram 2: Sequence Diagram of the getMap Operation referencing data available at remote sources

12/24


Name

Service Type

Service Operation


OAS

getFeatures

Source System Integration Service

OAS

getFeatures

Table 1: Possible ORCHESTRA Services to be used by as remote sources

As an example, a requestor accessing this service wants to create a map that shows the spatial distribution of the hazard zones (classified by the susceptibility level) with different colours. On top of this layer the requestor is interested to have other layers like the road network, the hydrological network, the urban areas and a diagram layer with the number of forest fires in each recorded point. The hazard zones data resides on an OA Feature Access Service, the data for the hydrological network on an OA Source System Integration Service, and other layers are available on the server. The requestor now invokes a getMap operation by passing a styled layer descriptor document (SLD), which defines the location of the data and the symbolization of each layer. The response of the service will be a map provided in the requested format. Observation: the requestor could be also a non-ORCHESTRA service (e.g. a decision support service for risk management), as long as the ORCHESTRA interface is used.

4.4

4.4.1

Relations to ORCHESTRA User and System Requirements

Fulfilment of ORCHESTRA User Requirements The Map and Diagram Service contributes to the following ORCHESTRA User Requirements: [HLUR-2] Multi-language capabilities are an important concern Explanation: Maps and diagrams have, in general, no language barrier as they are graphical representations. The service will render map or diagram feature labels in a generic manner. The data sources saved on the server should have labels in different languages and it is the responsibility of the user to request the labels in an appropriate language corresponding to his output expectations. [HLUR-4] Scenario and simulation tools are important and are extensively used in risk assessment Explanation: For scenario and simulation tools, maps are one of the concerned inputs. These maps could be provided by the service. [HLUR-6] It is important to empower the end user so that they can access the information they require anywhere and on any device Explanation: The main output of this service is an image document with the characteristics specified by the user. In this way it is possible to create maps and diagrams adapted for the visualisation on any device (including mobile devices). [HLUR-7] Be useful for end-users so that they want to adopt the system Explanation: Maps and diagrams, that are required in many processes, can be generated dynamically by this service. [HLUR-8] Provide something new that is not currently possible

13/24

Specification of the Map and Diagram Service – Context of the Map and Diagram Service Explanation: This service will offer many advantages in comparison with current WMS implementations considering: -

thematic map generation

-

availability of complete cartographic interface for advanced feature symbolization

[HLUR-10] Be backwards-compatible so that data/tools from existing systems can be used Explanation: This service encourages compatibility with existing WMS clients. [HLUR-12] Facilitate multi-scale analyses Explanation: The service could be of use for visual data analysis and exploratory data visualization. [HLUR-16] Allow the easy compilation of data from different sources Explanation: The service could be of use for visual data analysis and exploratory data visualization. Additionally, the specific user requirements defined for the service functionality are entirely fulfilled (plot features on a map, overlay layers, draw diagrams).

4.4.2

Fulfilment of the Requirements for the OSN and the OA The Map and Diagram Service fulfils the requirements for the OSN and the OA (RM-OA Annex A.2) by adhering to the following Architectural Principles: •

Rigorous Definition and Use of Concepts and Standards: Relevant concepts from available standards (ISO and OGC) are incorporated in the service definition.

•

Loosely Coupled Components This service is specified with the goal of openness, providing an open interface and allowing the addition of new data sources and styles.

•

Technology Independence The service is specified in an abstract way and does not impose specific technologies. The specifications have to be adapted to a certain technology for the implementation.

•

Evolutionary Development – Design for Change: This service does not impose specific implementations, thus newly developed technologies can be used for the implementation. In addition, one implemented with a certain technology, the service is built in a way which makes it extensible without having to modify the existing code (adding of new data sources, new styles and symbology definitions).

•

Component Architecture Independence: The service does not impose any architectural patterns on other components or services.

•

Generic Infrastructure: The service provides an interface which is independent of the specific application domain.

•

Self-describing Components: The service is self-describing by means of the getCapabilities operation.

14/24

Specification of the Map and Diagram Service – Context of the Map and Diagram Service 4.4.3

Contribution to the ORCHESTRA Development Dimensions The Map and Diagram Service contributes the following research dimensions (RM-OA Annex A.1): •

Semantic interoperability: Not applicable

•

Interpretation: This service allows the integration of different data sources for the purpose of data visualization and interpretation.

•

Navigation / Search Paradigms: Not directly applicable, although it enables clients to interactively allow visual data exploration.

•

Collaboration: Collaboration across organizational borders is enhanced by providing means to create cross-border and collaborative maps.

•

Collaboration Methods: For collaboration of services it is essential that the capabilities of each service are available and can be exchanged using various schemas and formats.

•

Business Process / Workflow Support: The portrayal of geographical features is needed in different steps of the workflow: at the beginning for exploratory data visualization, in the middle for visual data verification and at the end for mapbased decision support.

•

Thematic Domain Interaction: The service interface is not bound to a specific thematic domain and therefore does not impose restrictions to the interaction of services from different thematic domains.

•

Scale: The service is scalable and depends only of the underlying hardware and network resources.

•

Overall System Adaptability: The adaptability of the service is high as the service supports extended cartographic interfaces responsible for the complexity and the quality of the resulted map or diagram. It is also adaptable in the sense of adding of new data sources, new styles and symbology definitions in a flexible way.

15/24

Specification of the Map and Diagram Service – Requirements

5 5.1

Requirements Security Requirements The Map and Diagram Service has no requirements beyond the scope of the Authentication and Authorisation Service. Security considerations can be made regarding user access. An instance of the Authentication and Authorisation Service may be required in order to give controlled access to restricted information that are being portrayed in the form of maps or diagrams.

5.2

Reliability Requirements The Map and Diagram Service has no special reliability requirements, since it delivers a portrayal of the data and not the data itself. Furthermore, this portrayal is usually delivered to a geographic client for an immediate visualisation. However, if a data layer to be portrayed is based on an external data source (e.g. Feature Access Service), and this remote data source fails, than the Map and Diagram Service will issue a “LayerNotFound” service exception.

6

Specification of the Map and Diagram Interface Please refer to the Map and Diagram Abstract Interface Specification.

16/24

Specification of the Map and Diagram Service –

7

Specification of the Service Specific Capabilities As part of ORCHESTRA D3.3.2 a meta-information schema for services is defined acting as a default OAS-MI for service capabilities. OA_MI_CapabilitiesDocument includes both the common capabilities and the service specific capabilities. While the common capabilities are defined in the specification of the Service Capabilities Interface, the specific capabilities have to be specialized in each service specification. The schema for service specific capabilities defined here is explicitly divided into the following schema sections:

Section Name OA_MI_MS_Capabilities

Section Contents Section containing the complete specific capabilities. Section containing OGC WMS Capabilities as defined by ISO 19128.

OGCCapabilities

If only this section is requested by a getCapabilities operation then in this case information about diagrams and supported SLD and GML version shall be provided inside the section "_ExtendedCapabilities" of the WMS Capabilities. Table 2: Sections of the service specific capabilities

Definition

Data Type


OGCCapabilities

OGC Capabilities defined for the WMS are already defining the layer properties that a map server need to advertise. Furthermore the use of the WMS Capabilities defined format enables compatibility with existing WMS Clients and Parsers.

OA_MI_OGC_ Capabilities

mandatory

Diagram

List of preconfigured diagrams available at the server.

OA_MI_MS_Di agram_Layer

0..*

GMLSupport

GML Input supported or not.

Boolean

0..1

SLDSupport

SLD support is present or not.

Boolean

0..1

GML_Version

It lists a supported GML Version

CharacterString

0..*

GML_Schema

Link to a supported GML Schema

OA_URI

0..*

SLD_Version

It lists a supported SLD Version

CharacterString

0..*

SLD_Schema

Link to a supported SLD Schema

OA_URI

0..*

Name

Table 3: Attributes of the service specific capabilities of section OA_MI_MS_Capabilities

17/24


Name

Definition

Data Type


Version

Version of the OGC WMS Capabilities.

CharacterString

mandatory

SchemaLocation

URI pointing to a schema defining the OGC WMS Capabilities.

OA_URI

mandatory

Content

Content of an OGC WMS Capabilities Document

WMS_Capabili ties_Document

mandatory

Table 4: Attributes of the service specific capabilities of section OA_MI_OGC_Capabilities

cd SpecificCapabilitiesTypes «type» WM S_Capabilities_Document

WMS_Capabilities_Document represents and OGC WMS Capabilities Document.

cd SpecificCapabilitiesTypes «type» OA_M I_M S_Diagram_Layer + + + + +

Nam e: CharacterString T itle: CharacterString [0..1] Abstract: CharacterString [0..1] Style: OA_M I_M S_Style [1..*] Queriable: Boolean [0..1]

OA_MI_MS_Diagram_Layer describes existing diagrams hosted on the server. Each diagram layer advertises also which styles it has associated.

cd SpecificCapabilitiesTypes «type» OA_M I_M S_Style + + +

Nam e: CharacterString T itle: CharacterString [0..1] Abstract: CharacterString [0..1]

OA_MI_MS_Style names a style hosted on the server.

18/24


cd Capabilities «i nterface» ServiceCapabilities +

getCapabil ities(OA_GetCapabil itiesRequest) : OA_GetCapabil itiesResponse

«type» OA_GetCapabilitiesRequest + + +

«type» OA_GetCapabilitiesResponse

acceptForm ats: OA_M im eT ype [0..*] {ordered} acceptSpecVersions: CharacterString [0..*] {ordered} secti ons: OA_Capabi li ti esSections [0..1]

+ + + +

capabi li tySections: Bi nary form at: OA_M i m eT ype schem aNam e: OA_Capabi li ti esSchem a version: CharacterStri ng

«type» OA_CapabilitiesSections + +

schem aNam e: OA_Capabil itiesSchem a [0..1] schem aSections: CharacterString [0..*] = al l

0..* 0..1

Possi ble schem as are e.g.: OAS_M I_Services ISO19119 OWS_Com m on_1.0 OWL-S_1.1 WSM O_Groundi ng ...

«type» OA_CapabilitiesSchema +

identi fi er: OA_URI

OA_MI OA_MI_Property «T ype» OA_M I_Serv ice

1 0..1

1 0..1

OA_MI_Secti onContentBase

«type» OA_M I_Serv ice_SpecificCapabilities

«T ype» OA_M I_CoreElements + + + + + + + + + + + + + + + +

For schem a OAS_M I_Servi ces the val ue of capabi li tySections shall be structured according to type OA_M I_Service_Capabil ities

avai labl eSecti ons: CharacterStri ng [1..*] dataT ype: CharacterStri ng [0..1] description: CharacterStri ng serviceDescri ption: Locali sedCharacterString [0..1] docum entation: OA_URI serviceNam e: CharacterStri ng id: CharacterStri ng [0..1] serviceSpecVersi on: CharacterString language: CharacterStri ng serviceT ype: OA_Servi ceT ype [1..*] nam e: CharacterStri ng publi cationDate: Date serviceSpecVersi on: CharacterString [0..1] serviceT ype: OA_Servi ceT ype [0..*] url : OA_URI [0..1] serviceDocum entati on: OA_URI

«type» OA_M I_M S_Capabilities + + + + + + + +

OGCCapabi li ti es: OA_M I_OGC_Capabil ities Di agram : OA_M I_M S_Di agram _Layer [0..*] GM LSupport: Boolean [0..1] SLDSupport: Bool ean [0..1] GM L_Versi on: CharacterString [0..*] GM L_Schem a: OA_URI [0..*] SLD_Version: CharacterStri ng [0..*] SLD_Schem a: OA_URI [0..*]

T he use of WM S Capabil ities Docum ent facil i tate parseabi li ty of the OA conform Capabi li ti es Docum ent by exi sti ng OGC parsers whi ch in turns faci li tates com patibi li ty with exi sting WM S Standards. T he other com ponents of the OA_M I_M S_Capabi li ti es shall be al so present i nsi de the secti on "_ExtendedCapabi li ti es" of the WM S Capabi li ti es.

Diagram 3: Overview Diagram of the Map and Diagram Service Capabilities

19/24


cd SpecificCapabilitiesTypes OA_MI_Service_SpecificCapabilities «type» OA_M I_M S_Capabilities + + + + + + + +

OGCCapabilities: OA_M I_OGC_Capabilities Diagram : OA_M I_M S_Diagram _Layer [0..*] GM LSupport: Boolean [0..1] SLDSupport: Boolean [0..1] GM L_Version: CharacterString [0..*] GM L_Schem a: OA_URI [0..*] SLD_Version: CharacterString [0..*] SLD_Schem a: OA_URI [0..*]

T he use of WM S Capabilities Docum ent facilitate parseability of the OA conform Capabilities Docum ent by existing OGC parsers which in turns facilitates com patibility with existing WM S Standards. T he other com ponents of the OA_M I_M S_Capabilities shall be also present inside the section "_ExtendedCapabilities" of the WM S Capabilities.

«type» OA_M I_OGC_Capabilities + + +

Version: CharacterString Schem aLocation: OA_URI Content: WM S_Capabilities_Docum ent

«type» OA_M I_M S_Diagram_Layer + + + + +


«type» OA_M I_M S_Style + + +

«type» WM S_Capabilities_Document


Diagram 4: Diagram of the Map and Diagram Service Specific Capabilities Types

20/24

Specification of the Map and Diagram Service – Known Issues and Limitations

7.1

Known Issues and Limitations There are no known issues and limitations at the abstract service interface level. At the platform mapping level, it may be possible that the mapping of this interface to SOAP may differ from the future SOAP mappings defined for OGC Web Services. To minimize the possible differences the OGC document OGC-04-050r1 “WMS Change Request: Support for WSDL & SOAP” was taken into consideration. However, as the SOAP mapping defined in the above mentioned document leaves several things unspecified, the SOAP interface of the Map and Diagram Service goes further and specifies the input and output types for each operation messages as UML and XML Schema types. Another issue linked with the SOAP platform mapping of the interface lies in the return of the image document. The image document can be attached to the response message (e.g. SOAP with attachments) or it can be sent as reference (URI to the rendered image document on the server). Our recommended approach is to send the URI of the rendered image to overcome the problems and limitations of the SOAP attachments.

21/24

Specification of the Map and Diagram Service – Appendix A: Abstract Test Suite (normative)

8

Appendix A: Abstract Test Suite (normative) When creating an implementation specification of the Map and Diagram Service, the “Rules for Implementation Specifications of ORCHESTRA Services” defined in chapter 9.2.2.3 and the “Rules for the Service Mapping to a given Platform” of the RM-OA shall be obeyed. In addition, the following tests shall be performed to ensure conformance of an implementation specification to the platform-independent specification of the Map and Diagram Service: 1. Syntactical Conformance •


•


•


•




Additional conformance checks that are specifically to the Map and Diagram Service are not required.

22/24

Specification of the Map and Diagram Service – Appendix B: UML Models (normative)

9


9.1

XMI Model (mandatory) The XMI Models of this interface specification can be downloaded from the OGC Portal under the following URL: http://portal.opengeospatial.org/files/?artifact_id=23464

9.2

Static UML Model (optional)

cd M ap and Diagram Serv ice MapDiagramInterface ServiceCapabilities «interface» M apDiagramService + + + + + + +

getCapabilities(request :OA_GetCapabilitiesRequest) : OA_GetCapabilitiesResponse getMap(GetMap :OA_GetMapType) : OA_GetMapResponse getDiagram(GetDiagram :OA_GetDiagramType) : OA_GetDiagramResponse getFeatureInfo(GetFeatureInfo :OA_GetFeatureInfoType) : OA_GetFeatureInfoResponse getLegendGraphic(GetLegendGraphic :OA_GetLegendGraphicType) : OA_GetLegendGraphicResponse getLayerDescription(GetLayerDescription :OA_GetLayerDescriptionType) : OA_GetLayerDescriptionResponse getStyle(GetStyle :OA_GetStyleType) : OA_GetStyleResponse

cd SpecificCapabilitiesTypes OA_MI_Service_SpecificCapabilities «type» OA_M I_M S_Capabilities + + + + + + + +

OGCCapabilities: OA_M I_OGC_Capabilities Diagram : OA_M I_M S_Diagram _Layer [0..*] GM LSupport: Boolean [0..1] SLDSupport: Boolean [0..1] GM L_Version: CharacterString [0..*] GM L_Schem a: OA_URI [0..*] SLD_Version: CharacterString [0..*] SLD_Schem a: OA_URI [0..*]

T he use of WM S Capabilities Docum ent facilitate parseability of the OA conform Capabilities Docum ent by existing OGC parsers which in turns facilitates com patibility with existing WM S Standards. T he other com ponents of the OA_M I_M S_Capabilities shall be also present inside the section "_ExtendedCapabilities" of the WM S Capabilities.

«type» OA_M I_OGC_Capabilities + + +

Version: CharacterString Schem aLocation: OA_URI Content: WM S_Capabilities_Docum ent

«type» OA_M I_M S_Diagram_Layer + + + + +


«type» OA_M I_M S_Style + + +


«type» WM S_Capabilities_Document

23/24

Specification of the Map and Diagram Service – Appendix B: UML Models (normative) cd Types «type» OA_GetM apType + + + + + + + +

Layers: OA_LayersT ype [0..1] Styles: OA_StylesT ype [0..1] CRS: CharacterString BoundingBox: OA_BoundingBoxT ype GM L: CharacterString [0..1] SLD: CharacterString [0..1] Dim ension: OA_Dim ensionT ype [0..1] Output: OA_GraphicOutputT ype

«type» OA_GetM apResponse +

Return: OA_URI

«type» OA_GraphicOutputType + + + + + +

Form at: CharacterString Width: Integer Height: Integer T ransparent: Boolean [0..1] BGcolor: CharacterString [0..1] Opacity: Integer [0..1]

«type» OA_BoundingBoxType «type» OA_GetDiagramType + + + + + +

Diagram : CharacterString Style: CharacterString GM L: CharacterString [0..1] SLD: CharacterString [0..1] Dim ension: OA_Dim ensionT ype [0..1] Output: OA_GraphicOutputT ype

«type» OA_GetDiagramResponse +

QueryLayer: CharacterString I: Integer J: Integer FeatureCount: Integer [0..1] = 1 GetM ap: OA_GetM apT ype

«type» OA_GetFeatureInfoResponse + +

Layer: CharacterString Style: CharacterString [0..1] Rule: CharacterString [0..1] Scale: CharacterString [0..1] Output: OA_GraphicOutputT ype GetM ap: OA_GetM apT ype [0..1]

Layer: CharacterString

Return: CharacterString Schem a: OA_URI [0..1]

+

Return: OA_URI

9.3

Style: CharacterString Layer: CharacterString [0..1]

Style: CharacterString [1..*]

«type» OA_DimensionType + +

Nam e: CharacterString Value: CharacterString

«type» OA_GetLayerDescriptionResponse + +


«type» OA_GetStyleType + +

Layer: CharacterString [1..*]

«type» OA_StylesType

«type» OA_GetLegendGraphicResponse

«type» OA_GetLayerDescriptionType +

+

+

«type» OA_GetLegendGraphicType + + + + + +

m inx: Real m axx: Real m iny: Real m axy: Real CRS: CharacterString [0..1]

«type» OA_LayersType

«type» OA_GetFeatureInfoType + + + + +

Return: OA_URI

+ + + + +

«type» OA_GetStyleResponse + +


Dynamic UML Model (optional) The getCapabilities should be the first operation to be invoked. The getFeatureInfo operation should be invoked after a successful getMap or getDiagram operation.

24/24




Specification of the OA Basic Service

Revision

1/48

[1.0 / 2.0.4]

Specification of the OA Basic Service – Document Control Page


Specification of the OA Basic Service

Creator

Schmieder, Martin

Subject


Description

This document defines an abstract and platform independent formal interface specification of the OA Basic Service.

Publisher


Contributor

Usländer, Thomas

Date

2006-05-16

Type

Text

Format

application/msword

Identifier


Source

Not applicable

Language

en-GB.

Relation

none

Coverage


Fraunhofer IITB

Fraunhofer IITB


D3.4.3


WP3.4


2006-xx-xx


2006-xx-xx

Audience


Version number

1.0 / 2.0.4

Date

2006-05-24

Modified by

Schmieder, Martin

Fraunhofer IITB

Comments Status


2/48

Specification of the OA Basic Service – Document Control Page



3/48

Specification of the OA Basic Service – Revision History


Date

Sections changed

Description st

0.1

2005-11-03

all

1 draft release

0.2 / 1.6

2005-11-30

all

Adapted to template revision 1.6, corrections

0.3 / 1.6

2005-12-13

all

Chapter 3.3 Relations to ORCHESTRA User and System Requirements provided Operation getCapabilities changed: refer to only one schema in the request, include only one capabilities document in the response Entry “serviceSpecific” removed from OAS_CapabilitiesSchema Comments by EIG integrated

0.4 / 1.6

2005-12-14

4.2, 4.3.3

Reference to D3.2.2 replaced by D3.3.2

0.5 / 1.6

2005-12-22

all

Comments by ARCS integrated Chapter “Points for further discussion” added.

0.6 / 1.7

2006-02-07

all

Adapted to template revision 1.7

0.7 / 1.7

2006-02-09

all

Integration of Asynchronous Operation Support Interface renaming it Asynchronous Interaction Interface. Comments upon that interface by ARCS, ATOS, EIG considered.

0.8 / 1.7

2006-02-24

all

Comments by ARCS considered. Synchronous Interaction Interface added. Asynchronous Interaction Interface operation invoke renamed to invokeAsync.

1.0 / 2.0.4

2006-05-24

all

Adapted to template revision 2.0.4 and usage of Basic Data Types and OA Types. Renaming of RM-OA Service into OA Basic Service.

4/48

Specification of the OA Basic Service – Table of Contents

Table of Contents 1

Foreword..................................................................................................................................................... 9

2

Overview and Architecture Outline ............................................................................................................. 9 2.1

3

4

5

6

Role and Scope of the OA Basic Service............................................................................................ 9

2.1.1

The Service Capabilities Interface ............................................................................................... 9

2.1.2

The Synchronous Interaction Interface ........................................................................................ 9

2.1.3

The Asynchronous Interaction Interface ...................................................................................... 9

2.2

Service Capabilities Interface Specification Summary...................................................................... 10

2.3

Synchronous Interaction Interface Specification Summary............................................................... 11

2.4

Asynchronous Interaction Interface Specification Summary............................................................. 11

Context of the OA Basic Service .............................................................................................................. 13 3.1


3.2


3.3


3.4


3.5


3.5.1


3.5.2


3.5.3


Requirements ........................................................................................................................................... 16 4.1


4.2


Conventions .............................................................................................................................................. 17 5.1

Abbreviations ..................................................................................................................................... 17

5.2


5.3

UML Notation..................................................................................................................................... 17

5.4

Conformance ..................................................................................................................................... 17

5.4.1


5.4.2


Service Capabilities Interface Specification.............................................................................................. 18 6.1

Specification of an OAS Profile of Parameter Types used by the Interface...................................... 18

6.2

Specification of the Interface Operations .......................................................................................... 18

6.2.1

Specification of the getCapabilities Operation ........................................................................... 18

5/48

Specification of the OA Basic Service – Table of Contents 6.3


6.4


6.4.1

OA_GetCapabilitiesRequest ...................................................................................................... 21

6.4.2

OA_CapabilitiesSections............................................................................................................ 22

6.4.3

OA_CapabilitiesSchema ............................................................................................................ 23

6.4.4

OA_CapabilitiesDocument ......................................................................................................... 23

6.4.5

OA_VersionNegotiationFailed.................................................................................................... 24

6.4.6

OA_UnsupportedSchema .......................................................................................................... 24

6.5 7


Synchronous Interaction Interface Specification ...................................................................................... 26 7.1


7.2


7.2.1 7.3


7.4


7.4.1

OA_OperationRequest ............................................................................................................... 30

7.4.2

OA_OperationResponse ............................................................................................................ 30

7.4.3

OA_SyncOperationUnsupported................................................................................................ 30

7.5 8

Specification of the invoke Operation......................................................................................... 27


Asynchronous Interaction Interface Specification .................................................................................... 32 8.1


8.2


8.2.1

Specification of the invokeAsync Operation............................................................................... 34

8.2.2

Specification of the abort Operation........................................................................................... 36

8.2.3

Specification of the notify Operation .......................................................................................... 38

8.3


8.4


8.4.1

OA_OperationRequest ............................................................................................................... 40

8.4.2

OA_OperationResponse ............................................................................................................ 40

8.4.3

OA_Notification .......................................................................................................................... 40

8.4.4

OA_InvokeID .............................................................................................................................. 40

8.4.5

OA_AsyncOperationUnsupported.............................................................................................. 41

8.4.6

OA_AbortNotPossible ................................................................................................................ 41

8.4.7

OA_InvalidState ......................................................................................................................... 41

8.5


8.5.1

Role of the NotificationCallback Interface .................................................................................. 42

6/48

Specification of the OA Basic Service – Table of Contents 9

Predefined Exception Types for all ORCHESTRA Services .................................................................... 44 9.1

OA_AbstractException ...................................................................................................................... 44

9.2

OA_MissingParameterValue ............................................................................................................. 45

9.3

OA_InvalidPermission ....................................................................................................................... 45

9.4

OA_InvalidParameterValue ............................................................................................................... 45

9.5

OA_UnsupportedOperation ............................................................................................................... 45

9.6

OA_InternalError ............................................................................................................................... 45

9.6.1 9.7

OA_CodeLocation ...................................................................................................................... 46

OA_NoApplicableCode...................................................................................................................... 46

10 Appendix A: Abstract Test Suite (normative)............................................................................................ 47 11 Appendix B: UML Models (normative) ...................................................................................................... 48 11.1

Static Model ................................................................................................................................... 48

11.2

Dynamic Model .............................................................................................................................. 48

7/48

Specification of the OA Basic Service – Tables and Diagrams

Tables Table 1: Summary of Service Capabilities Interface Operations ..................................................................... 10 Table 2: Summary of Synchronous Interaction Interface Operations.............................................................. 11 Table 3: Summary of Asynchronous Interaction Interface Operations ............................................................ 11 Table 4: Summary of Notification Callback Interface Operations .................................................................... 12 Table 5: Referenced OA Types ....................................................................................................................... 18 Table 6: Specification of the getCapabilities Operation ................................................................................... 19 Table 7: Referenced OA Types ....................................................................................................................... 27 Table 8: Specification of the invoke Operation ................................................................................................ 28 Table 9: Referenced OA Types ....................................................................................................................... 34 Table 10: Specification of the invokeAsync Operation .................................................................................... 35 Table 11: Specification of the abort Operation ................................................................................................ 36 Table 12: Specification of the notify Operation ................................................................................................ 38 Table 13: Predefined exception types ............................................................................................................. 44

Diagrams Diagram 1: Class Diagram of the Service Capabilities Interface..................................................................... 10 Diagram 2: Class Diagram of the Synchronous Interaction Interface.............................................................. 11 Diagram 3: Class Diagram of the Asynchronous Interaction Interface............................................................ 11 Diagram 4: Operations of Service Capabilities Interface ................................................................................. 18 Diagram 5: OA Types of Service Capabilities Interface................................................................................... 20 Diagram 6: Exception Types of Service Capabilities Interface........................................................................ 24 Diagram 7: Synchronous Operation Execution................................................................................................ 26 Diagram 8: Operations of Synchronous Interaction Interface.......................................................................... 27 Diagram 9: OA Types of Synchronous Interaction Interface ........................................................................... 29 Diagram 10: Exception Types of Synchronous Interaction Interface............................................................... 30 Diagram 11: Synchronous versus Asynchronous Operation Execution .......................................................... 32 Diagram 12: Asynchronous Operation Execution with multiple Notifications .................................................. 33 Diagram 13: Operations of Asynchronous Interaction Interface...................................................................... 34 Diagram 14: OA Types of Asynchronous Interaction Interface ....................................................................... 39 Diagram 15: Exception Types of Asynchronous Interaction Interface............................................................. 41 Diagram 16: Example of service-side NotificationCallback usage .................................................................. 43 Diagram 17: Class diagram of the predefined exception types ....................................................................... 45

8/48

Specification of the OA Basic Service – Foreword

1

Foreword This document is an abstract specification of the OA Basic Service and is based on the Template for the abstract Specification of ORCHESTRA Services version 2.0.4. It updates the specification version 0.8 of the former RM-OA Service. An update of all chapters was required due to the adoption to the new template structure, usage of Basic Data Types and OA Types and the new name of the service (OA Basic Service instead of RM-OA Service). This document includes two annexes: Appendix A: Abstract Test Suite (normative) is mandatory and Appendix B: UML Models (normative) is optional.

2


2.1

Role and Scope of the OA Basic Service The OA Basic Service provides descriptions of those functions for which a common architectural approach is required for all ORCHESTRA Services. It does so by defining abstract interfaces which may be extended or adapted according to the context of a specific ORCHESTRA Service. In addition the OA Basic Service specifies predefined exception types to be used by all ORCHESTRA Services. Due to the role of the OA Basic Service of providing abstract interfaces for all ORCHESTRA Services, there will be no direct OSI of the OA Basic Service but an implementation of the specified interfaces as part of other OSIs. The OA Basic Service provides the functionality through a series of interfaces which are introduced in the following subchapters.

2.1.1

The Service Capabilities Interface The objective of this interface is to define a uniform way to get a self-description of an OSI by means of so-called capabilities. The capabilities form service meta-information which can be used for various purposes like e.g. service discovery and service invocation. This interface is a mandatory interface and shall be implemented by all ORCHESTRA Services.

2.1.2

The Synchronous Interaction Interface The objective of this interface is to define a uniform way to request for synchronous execution of a service operation. Synchronous execution of an operation means that the client requests operation execution and then waits until the operation provider has finished operation execution and returns a response. Such a response may either contain an operation result value (which also may be empty) or may be an indication of a failure which is modeled as exception. By means of such a generic interface a service is able to offer operations for which no dedicated operation interface is available. The set of available operations may not be known at design time when specifying a service interface. Consider for example a service providing access to some source system. The underlying source system and its operations may not be known until runtime. Apart from dynamically adding new operations to this interface, another possible mechanism is to dynamically invoke operations by means of a generic interaction interface. The Synchronous Interaction Interface supports the latter type of a source system integration model. Besides the Synchronous Interaction Interface, the OA Basic Service defines a similar interface for asynchronous interaction (see below).

2.1.3

The Asynchronous Interaction Interface The objective of this interface is to define a uniform way to request for asynchronous execution of a

9/48

Specification of the OA Basic Service – Overview and Architecture Outline service operation. When a client calls an operation provided by an OSI it is often sufficient and convenient to execute the operation synchronously. However, for operations which are time-consuming or periodically deliver results asynchronous execution is sometimes necessary. Asynchronous execution of an operation means that the client requests operation execution but does not wait until the operation has finished. Instead, the client may execute other tasks while the operation is running. However, in most cases the client wants to get notified when the operation terminates in order to get its results. In addition, when executing an operation asynchronously the client should be able to abort operation execution. Asynchronous operation execution is not restricted to a single notification indicating that execution has terminated. A series of notifications may inform the client periodically about the status or progress of execution. An example may be an operation which allows a client to observe a sensor. Invoking the operation means to register the client to receive measurement values later on. Then periodically the asynchronously executing operation generates a notification containing the currently observed measurement value of the sensor and sends it to the client. This continues until observation finishes due to an abort by the client or a time-out. In the latter case an additional final notification may signal to the client that no more notifications will follow.

2.2

Service Capabilities Interface Specification Summary

Diagram 1: Class Diagram of the Service Capabilities Interface The Service Capabilities interface defines the following operations:

Operation Name

getCapabilities (see 6.2.1)

Description Informs the client of the capabilities of an OSI. This operation takes into account that in addition to capabilities that are common to all ORCHESTRA Services an ORCHESTRA Service may provide a specific set of capabilities. Furthermore, this operation allows the capabilities to be delivered according to different service metainformation schemas.

Table 1: Summary of Service Capabilities Interface Operations

10/48

Specification of the OA Basic Service – Overview and Architecture Outline

2.3

Synchronous Interaction Interface Specification Summary

Diagram 2: Class Diagram of the Synchronous Interaction Interface The Synchronous Interaction interface defines the following operations:

Operation Name invoke

Description Executes an operation synchronously and returns the operation response.

(see 7.2.1)

Table 2: Summary of Synchronous Interaction Interface Operations

2.4

Asynchronous Interaction Interface Specification Summary

Diagram 3: Class Diagram of the Asynchronous Interaction Interface As illustrated by the diagram this interface is accompanied by a callback interface used to receive notifications resulting from asynchronous operation execution. Therefore the table of interface operations is split into two tables. The Asynchronous Interaction interface defines the following operations:

Operation Name invokeAsync (see 8.2.1) abort (see 8.2.2)

Description Starts asynchronous execution of an operation. The invokeAsync operation returns immediately with an identifier (invocation ID) representing the asynchronous execution. In order to receive notifications a reference to a callback interface can be provided. Aborts execution of a previously invoked asynchronous operation identified by its invocation ID.

Table 3: Summary of Asynchronous Interaction Interface Operations

11/48

Specification of the OA Basic Service – Overview and Architecture Outline The Notification Callback interface defines the following operations:

Operation Name notify (see 8.2.3)

Description Passes a notification to the callback interface provider.

Table 4: Summary of Notification Callback Interface Operations

12/48

Specification of the OA Basic Service – Context of the OA Basic Service

3

Context of the OA Basic Service

3.1

Relations to Standards •

OGC Web Services Common Specification (OGC 05-008): usage of concepts and definitions

The getCapabilities operation of the Service Capabilities Interface is designed such that it is backward compatible with the concepts of the getCapabilities operation as defined in the OGC Web Services Common Specification (OGC 05-008). The idea is that the usage of the meta-information schema defined in that OGC standard is just one possibility how the service capabilities may look like.

3.2

Relations to other ORCHESTRA Service Specifications The OA Basic Service provides abstract interfaces for all ORCHESTRA Services. This means that all operations of this service can be inherited and all concepts described herein can be applied by the ORCHESTRA Services. In addition the capabilities returned by the getCapabilities operation form meta-information about a service which can be published in a catalogue and can be used by clients to discover and invoke services. So there is a relationship to the catalogue service.

3.3

Relations to ORCHESTRA Application Schemas The OA Basic Service specification uses Basic and OA Types that are defined in the package OAS/Basic Types, OAS/OA Types and OAS-MI/OA-MI Types of the Information Viewpoint. The OA Basic Service specification defines new parameter types. These parameter types are defined the in the package OAS/OA Types of the Information Viewpoint. Exception types are defined in the package OA Types/Exception Types of the Information Viewpoint.

3.4

Relations to ongoing Initiatives and related Projects The OA Basic Service has indirect relations to other initiatives and projects as the Service Capabilities Interface is intended to be inherited by all other ORCHESTRA Services. Thus, the question of compatibility with existing service specifications of related initiatives and projects is the crucial issue here.

3.5 3.5.1

Relations to ORCHESTRA User and System Requirements Fulfilment of ORCHESTRA User Requirements The OA Basic Service has indirect relations to the ORCHESTRA User Requirements as it provides abstract interfaces for all ORCHESTRA Services for those functions for which a common architectural approach is required. The following ORCHESTRA User Requirements are directly related to availability and usage of meta-information about services and data: [HLUR-1] Semantic interoperability is important, beginning with consistency across risk domain glossaries. [HLUR-2] Multi-language capabilities are an important concern. [HLUR-3] Important meta-data for risk assessment information is its quality and validity (data provenance). [HLUR-15] Allow the easy searching for data from different sources. [HLUR-16] Allow the easy compilation of data from different sources. Such meta-information about services and supported data is made available by means of the Service

13/48

Specification of the OA Basic Service – Context of the OA Basic Service Capability Interface of the OA Basic Service which has to be provided by all ORCHESTRA Services. As meta-information about a service and its supported data (service capabilities) can be asked at runtime, a navigation and search application (e.g. a catalogue service) can work with up-to-date information. 3.5.2

Fulfilment of the Requirements for the OSN and the OA The OA Basic Service fulfils the requirements for the OSN and the OA (RM-OA Annex A.2) by adhering to the following Architectural Principles:

3.5.3

•

Rigorous Definition and Use of Concepts and Standards: The getCapabilities operation of the Service Capabilities Interface is designed such that it is backward compatible with the concepts of the OGC Web Services Common Specification (OGC 05-008). Furthermore, the structure of meta-information provided by this operation follows existing well-known schemas like ISO 19119, OWL-S, and WSMO.

•

Loosely Coupled Components: Loose coupling implies the use of mediation to permit existing components to be interconnected. In order to perform mediation meta-information about a component must be available. The Service Capabilities Interface is designed to provide this information in various formats.

•

Technology Independence: The specification of ORCHESTRA Services is done on a level which is technology independent.

•

Evolutionary Development - Design for Change: The getCapabilities operation of the Service Capabilities Interface does not impose restrictions to the structure and format of the provided meta-information. The list of possible schemas is kept open. In addition, the definition of exception types is not restrictive but provides a framework to be adapted and extended by each service specification.

•

Component Architecture Independence: not directly applicable to the OA Basic Service.

•

Generic Infrastructure: The OA Basic Service is generic i.e. independent of the application domain.

•

Self-describing Components: The OA Basic Service provides an interface which allows for the self-description of services by means of the getCapabilities operation.

Contribution to the ORCHESTRA Development Dimensions The OA Basic Service contributes the following research dimensions (RM-OA Annex A.1): •

Semantic interoperability: The Service Capabilities Interface allows retrieving the capabilities of a service. These capabilities form meta-information about the service. The capabilities and thus the meta-information can be structured according to various schemas including schemas which allow relating the metainformation to ontological concepts. The availability of ontology-based meta-information is a basis for semantic interoperability.

•

Interpretation: not directly applicable to the OA Basic Service.

•

Navigation / Search Paradigms: As stated above the getCapabilities operation contributes to the demand that an OSN supports semantic integration by allowing to formulate capabilities according to ontological concepts. Furthermore, as these capabilities can be asked at runtime, a navigation and search application (e.g. a catalogue service) can work with up-to-date information.

•

Collaboration: not directly applicable to the OA Basic Service.

14/48

Specification of the OA Basic Service – Context of the OA Basic Service •

Collaboration Methods: For collaboration of services it is essential that the capabilities of each service are available and can be exchanged using various schemas and formats.

•

Business Process / Workflow Support: not directly applicable to the OA Basic Service.

•

Thematic Domain Interaction: The OA Basic Service is not bound to a specific thematic domain and therefore does not impose restrictions to the interaction of services from different thematic domains.

•

Scale: not directly applicable to the OA Basic Service

•

Overall System Adaptability: By means of (semantic) meta-information as provided by the Service Capabilities Interface mappings and transformations can be performed which are needed in order to build more adaptable and generic systems.

15/48

Specification of the OA Basic Service – Requirements

4 4.1

Requirements Security Requirements The OA Basic Service has no requirements beyond the scope of the Authentication and Authorization Service.

4.2

Reliability Requirements The OA Basic Service has no special reliability requirements.

16/48

Specification of the OA Basic Service – Conventions

5

Conventions

5.1

Abbreviations The abbreviations used in this document are defined in chapter 3.1 of the RM-OA.

5.2


5.3


5.4 5.4.1

Conformance Conformance to the OMM This abstract service interface specification is specified according to the rules of the ORCHESTRA Reference Model and follows the Rules for ORCHESTRA Services as described in chapter 9.2 of the RMOA. The extended service capabilities are be modelled according to the rules provided by D3.3.2.

5.4.2


17/48

Specification of the OA Basic Service – Service Capabilities Interface Specification

6

Service Capabilities Interface Specification

6.1

Specification of an OAS Profile of Parameter Types used by the Interface The following non basic types are used within this interface specification:

Name

Usage

from OAS

New


I

OA Types

Yes


O

OA Types

Yes


E


Yes


E


Yes


E


No


E


No

OA_NoApplicableCode

E


No

OA_InternalError

E


No


6.2

Specification of the Interface Operations The following diagram gives an overview about the operations of the Service Capabilities Interface.

Diagram 4: Operations of Service Capabilities Interface

6.2.1

Specification of the getCapabilities Operation The mandatory getCapabilities operation informs the client of the capabilities of an ORCHESTRA Service Instance (OSI). This operation takes into account that in addition to capabilities that are common to all ORCHESTRA Services an ORCHESTRA Service may provide a specific set of capabilities. Furthermore, this operation allows the capabilities to be delivered according to different service meta-

18/48

Specification of the OA Basic Service – Specification of the getCapabilities Operation information schemas. A service meta-information document is returned to the requesting client, either complete or including selected parts according to the given sections in the request.

Overrides

not applicable

Preconditions

none

Post conditions

Service meta-information document returned to requesting client, either complete or including selected parts according to the given sections in the request

Use

mandatory

Receives

Name

request

Type

Use


Returns

Type

Specifies the parts of the meta-information to be returned. If absent, all parts shall be returned using the default schema. Description

Service capabilities of the specific OSI for the specific ORCHESTRA Service.

OA_CapabilitiesDocument Throws

optional

Description

Type

Cause





OA_NoApplicableCode


OA_InternalError



List of versions in acceptSpecVersions parameter value in the getCapabilities request did not include any version supported by the OSI.


The sections parameter in the getCapabilities request referred to a schema unsupported by the OSI.

Table 6: Specification of the getCapabilities Operation

19/48

Specification of the OA Basic Service – Specification of extended Service Capabilities

6.3

Specification of extended Service Capabilities As part of ORCHESTRA D3.3.2 a meta-information schema for services is defined acting as a default OAS-MI for service capabilities. OA_CapabilitiesDocument includes both the common capabilities and the service specific capabilities. While the common capabilities are further refined in D3.3.2 the specific capabilities have to be specialized in each service specification.

6.4

Specification of additional Types The Service Capabilities Interface defines new OA Types which will become part of the OAS “OA Types”. Exception types will become part of the OAS “OA Types/Exception Types”. This interface specification does not define any new OT Types and does not introduce any new nonORCHESTRA Types. The following diagram gives an overview about the OA Types used by the interface operations. They are described in the following sections.

Diagram 5: OA Types of Service Capabilities Interface

20/48

Specification of the OA Basic Service – Specification of additional Types

6.4.1

OA_GetCapabilitiesRequest The OA_GetCapabilitiesRequest type is used to specify the parts of the meta-information to be returned in the getCapabilities operation. It consists of the following elements: •

acceptSpecVersions: Optional parameter containing a prioritized sequence of zero or more specification versions of the ORCHESTRA service accepted by the client, with the preferred versions listed first. The meaning of this parameter is described in detail in subsection 6.4.1.1 below.

•

sections: Optional parameter containing the names of requested sections in the complete set of meta-information elements. The structure of this parameter is defined in the parameter type OA_CapabilitiesSections. The meaning of this parameter is described in detail in subsection 6.4.1.2 below.

•

acceptFormats: Optional parameter containing a prioritized sequence of zero or more response formats desired by the caller, with preferred formats listed first. The formats are to be expressed in terms of MIME types, e.g. “text/xml”. The meaning of this parameter is described in detail in subsection 6.4.1.3 below.

Note: The attributes of the OA_GetCapabilitiesRequest listed here are derived from OGC 05-008. The GetCapabilities request defined in OGC 05-008 include two additional parameters which are mandatory: “service” (specifying the service type) and “request” (specifying the operation name). However, these two parameters are not considered here, because the necessity to include these parameters is considered to be dependent of the chosen service platform, thus it is out of scope of this platform independent service specification. 6.4.1.1

acceptSpecVersions parameter and version negotiation (derived from OGC 05-008)

Each revision of an ORCHESTRA Implementation Specification (OIS) shall specify a version number, which enables interacting clients and servers to agree on which version of the specification they are conforming to. A version number shall contain three non-negative integers separated by decimal points, in the form “x.y.z”. Note: This structure of a version number is an initial approach taken from OGC 05-008. It could be replaced by a more general approach if necessary. Through the evolution of specifications, each ORCHESTRA service will have a number of versions defined for it, each with a different version number. Each OIS shall have its own sequence of version numbers; the version numbers of different services are independent and therefore may overlap. There may be gaps in the numerical sequence, and some numbers may denote draft versions. Servers and their clients need not support all defined versions, but are encouraged to support multiple versions. Version negotiation is performed using the optional acceptSpecVersions parameter in the getCapabilities operation request. The value of this parameter is a sequence of OIS version numbers that the client supports, in order of client preference. The sequence may be empty which is equivalent to the absence of the acceptSpecVersions parameter. An OSI, upon receiving a getCapabilities request with the acceptSpecVersions parameter present containing a non-empty sequence of version numbers, shall scan through this list and find the first version number that it supports. It shall then return a service meta-information document conforming to that version of the specification, and containing that value of the version parameter. If the list does not contain any version number that the server supports, the server shall return an exception of type OA_VersionNegotiationFailed. An OSI, upon receiving a getCapabilities request without the acceptSpecVersions parameter or with an empty sequence of version numbers, shall return a service meta-information document that is compliant

21/48

Specification of the OA Basic Service – Specification of additional Types to the highest version that the server supports. To ensure backward compatibility, clients shall also be prepared to accept an unknown response, i.e. a response containing a version number which is not supported by the client, and treat this situation as an indication that version negotiation has failed. 6.4.1.2

sections parameter (extension of OGC 05-008)

The value of the optional sections parameter specifies the sections within a service meta-information document that shall be returned according to a specified schema. The value of the sections parameter is structured as specified in the type OA_CapabilitiesSections which is described in detail in 6.4.2. It specifies section names in the context of a schema. The schemaName parameter uses the ORCHESTRA OAS-MI for services as the default meta-information schema which includes both the common capabilities and the service specific capabilities. Other allowed schema names may be standard service meta-information schemas from ISO, OGC (ISO 19115/19119) and the Semantic Web community (e.g. OWL-S and WSMO). Client implementation of the sections parameter is optional. When any server receives a getCapabilities operation request without this parameter, it shall return the complete service meta-information document of the default schema. This is considered to be an initial approach which is chosen for its simplicity. Server implementation of the sections parameter is optional. When a server does not implement this parameter, it shall ignore this parameter if present in a getCapabilities operation request, and shall return the complete service meta-information document of the default schema. Thus it shall react in the same way as if this parameter was not present in the request. If the sections parameter refers to a schema that the server does not support, the server shall return an exception of type OA_UnsupportedSchema. 6.4.1.3

acceptFormats parameter (derived form OGC 05-008)

The optional acceptFormats parameter can be used by a client to attempt to negotiate a getCapabilities operation response format. When included in an operation request, this parameter shall contain a list of the alternative MIME types that the client wants to be returned, listed in the client's preferred order. There shall be a default MIME type which is always an implicit last option, but can be explicitly included. Alternative formats might reduce the size of the transferred message, thus reducing the communication time and load. When a server implements the acceptFormats parameter and receives a value for it, the server shall return the capabilities document in the format of the first MIME type in this list that it is capable of returning. When not received or not implemented, the server shall return the capabilities document in the default format, using the default MIME type. All clients and servers shall implement the default MIME type for the getCapabilities operation. Since the default MIME type is always an implicit last option, the server always has an implemented MIME type to use to return a capabilities document to the client. Server and client implementation of this parameter is optional. The default MIME type is not defined in this platform-neutral specification. An appropriate default format will be specified in the context of an implementation specification. Up to now this document does not specify any alternative format, but the acceptFormats parameter is included to provide flexibility to allow experimentation and allow other specifications to identify allowed alternative format(s). A specific OIS that expects to interoperably use this acceptFormats parameter shall thus identify the alternative format(s) that can be used (or that shall be implemented by servers). 6.4.2

OA_CapabilitiesSections The OA_CapabilitiesSections type is used to specify the sections of the meta-information to be returned in the getCapabilities operation. In order to support different schemas for service meta-information, the client may specify a schema name and relative to the schema the sections of meta-information.

22/48

Specification of the OA Basic Service – Specification of additional Types It consists of the following elements: •

schemaName: Optional parameter that specifies the schema for service meta-information according to which the capabilities shall be described. It is an entry of type OA_CapabilitiesSchema. The default value is “OAS_MI_Services” as defined in section 6.4.3

•

schemaSections: Unordered list of zero or more names of requested sections within the selected schema. If the list is empty, all available sections shall be returned. The order in which the sections are included in the response is independent of the order of the section names in the request. The sections appear in the resulting meta-information document in an order which may be determined by the underlying schema.

Note: A simple list of section names is considered sufficient here as an initial approach. It could be replaced by a more general approach (using e.g. a certain query language) if necessary. 6.4.3

OA_CapabilitiesSchema The OA_CapabilitiesSchema type specifies a schema for service meta-information by providing its URI. Examples of possible schemas are:

6.4.4

•

OAS_MI_Services: the capabilities are structured according to the OAS-MI for Services as defined in ORCHESTRA D3.3.2 (intended to be attached to the RM-OA document in future). This includes both the common capabilities and the service specific capabilities as expressed by the aggregation type OA_MI_Service_Capabilities defined in that schema.

•

ISO19119: the capabilities are structured according to ISO 19119.

•

OWS_Common_1.0: the capabilities are structured according to the OGC Web Services Common Specification (OGC 05-008).

•

OWL-S_1.1: the capabilities are structured according to OWL-S Version 1.1.

•

WSMO_Grounding: the capabilities are structured according to the WSMO Grounding Specification.

•

… (other schemas may be added)

OA_CapabilitiesDocument The delivery of a result of type OA_CapabilitiesDocument shall be the normal response to a client from performing the getCapabilities operation. It shall contain the service capabilities of the specific OSI for the specific ORCHESTRA Service. The capabilities are delivered as value of the capabilitiesSections parameter whose format is as requested by the acceptFormats parameter in the request. Its schema and containing sections is as requested by the sections parameter in the request. The OA_CapabilitiesDocument consists of the following elements: •

version: Version number of the specification to which the delivered service meta-information document is conform.

•

schemaName: Schema according to which the capabilities are returned. The value is the same as the one contained in the sections parameter of the request. If not explicitly included in the request, the value indicates the default schema.

•

format: MIME type of the format in which the capabilities are returned as value of the capabilitySections parameter. This format is either one of the formats of the acceptFormats parameter of the request or the default format.

•

capabilitySections: capabilities as meta-information document of type Binary which is internally structured according to the indicated format and the indicated schema. It is either complete or includes only selected parts according to the given sections in the request. By knowing its in-

23/48

Specification of the OA Basic Service – Specification of additional Types ternal structure, the receiving client shall be able to parse the document and to identify and interpret the containing sections. The client shall be prepared to handle a meta-information document which may contain additional sections not explicitly selected in the request. It may for example ignore these sections. 6.4.5

OA_VersionNegotiationFailed An exception of type OA_VersionNegotiationFailed indicates that the list of versions in acceptSpecVersions parameter value in the getCapabilities request did not include any version supported by the OSI. The versions supported by the OSI shall be indicated.

6.4.6

OA_UnsupportedSchema An exception of type OA_UnsupportedSchema indicates that the sections parameter in the getCapabilities request referred to a schema unsupported by the OSI. The supported schemas shall be indicated.

Diagram 6: Exception Types of Service Capabilities Interface

24/48

Specification of the OA Basic Service – Known Issues and Limitations

6.5

Known Issues and Limitations The getCapabilities operation is designed such that it is backward compatible with the concepts of the getCapabilities operation as defined in the OGC Web Services Common Specification (OGC 05-008). The idea is that the usage of the meta-information schema defined in that OGC standard is just one possibility how the service capabilities may look like.

25/48

Specification of the OA Basic Service – Synchronous Interaction Interface Specification

7

Synchronous Interaction Interface Specification By providing the Synchronous Interaction Interface a service offers a uniform way to let a client request for synchronous execution of an operation. It consists of a single operation invoke to execute a certain operation indicated by its operation name. The following simple diagram shows the usage of this interface. The client wraps the operation request into an invoke message which it sends to an entity providing the interface SynchronousInteraction. The client waits while the OSI internally executes the operation. The operation response is wrapped into the response message of the invoke operation and sent to the client.

Diagram 7: Synchronous Operation Execution

7.1


Name

Usage

from OAS

New

OA_OperationRequest

I

OA Types

Yes


O

OA Types

Yes

OA_OperationResult

O

OA Types

Yes

OA_OperationFailure

O

OA Types

Yes


E


E


No


E


No


26/48

Yes

Specification of the OA Basic Service – Synchronous Interaction Interface Specification

OA_NoApplicableCode

E


No

OA_InternalError

E


No


7.2

Specification of the Interface Operations The following diagram gives an overview about the operations of the Synchronous Interaction Interface.

Diagram 8: Operations of Synchronous Interaction Interface

7.2.1

Specification of the invoke Operation The mandatory invoke operation executes an operation synchronously. The invoke operation waits until the underlying operation returns and delivers its response. Such a response may either contain the operation result value (which also may be empty) or may be an indication of a failure which is modeled as exception. Any exception thrown by the invoke operation signals that starting the underlying operation failed. Especially if the OA_OperationRequest parameter contains an invalid operation name, the invoke operation throws an OA_InvalidParameterValue exception. If the operation name is valid but synchronous execution of that operation is not supported, the invoke operation throws an OA_SyncOperationUnsupported exception. Any exception thrown by the underlying operation does not lead to an exception of the invoke operation but is delivered as OA_OperationFailure which is a subtype of OA_OperationResponse.

Overrides

not applicable

Preconditions

none

Post conditions

Requested operation was executed synchronously.

Use

mandatory

Receives

Name

Type

Use

27/48

Description

Specification of the OA Basic Service – Specification of the invoke Operation

request

OA_OperationRequest

Returns

mandatory

Type

Description Contains the result value of the executed operation or an exception thrown by that operation.

OA_OperationResponse Throws

Specifies the operation to be executed synchronously. Contains its name and input parameters.

Type

Cause





OA_NoApplicableCode


OA_InternalError



Synchronous execution of the specified operation is not supported.

Table 8: Specification of the invoke Operation

28/48


7.3

Specification of extended Service Capabilities A service providing the Synchronous Interaction Interface shall indicate in its service capabilities which operations can be executed by means of the invoke operation. For this purpose, the general description of an operation (which is part of the common service capabilities) shall be extended for the invoke operation. The extension consists of a list of the operations which are supported by means of the invoke operation. This includes also the input and output parameters of each such operation.

7.4

Specification of additional Types The Synchronous Interaction Interface defines new OA Types which will become part of the OAS “OA Types”. Exception types will become part of the OAS “OA Types/Exception Types”. This interface specification does not define any new OT Types and does not introduce any new nonORCHESTRA Types. The following diagram gives an overview about the OA Types used by the interface operations. They are described in the following sections.

Diagram 9: OA Types of Synchronous Interaction Interface

29/48


7.4.1

OA_OperationRequest The OA_OperationRequest type is used to specify an operation to be executed. In the context of the invoke operation this type is used to specify the operation to be executed synchronously. It consists of the operation name and a list of operation parameters.

7.4.2

OA_OperationResponse The OA_OperationResponse type contains the response to an operation request. It may either contain an operation result value (which also may be empty) or may be an indication of a failure which is modeled as exception. Therefore, OA_OperationResponse is an abstract type with the following two derived types.

7.4.2.1

OA_OperationResult

The OA_OperationResult type contains the result (return value) of an operation execution. This is considered to be the normal response to an operation request. It consists of an attribute result whose type is operation dependent and which is absent if the operation has an empty result. 7.4.2.2

OA_OperationFailure

The OA_OperationFailure type contains the exception thrown by an operation execution. This is considered to be the failure response to an operation request. It consists of an attribute failure whose type is OA_AbstractException. 7.4.3

OA_SyncOperationUnsupported An exception of type OA_SyncOperationUnsupported indicates that synchronous execution of an operation is not supported. The name of the operation shall be indicated.

Diagram 10: Exception Types of Synchronous Interaction Interface

30/48


7.5

Known Issues and Limitations None.

31/48

Specification of the OA Basic Service – Asynchronous Interaction Interface Specification

8

Asynchronous Interaction Interface Specification By providing the Asynchronous Interaction Interface a service offers a uniform way to let a client request for asynchronous execution of an operation. It basically consists of two operations: An operation invokeAsync to start a certain operation and an operation abort to cancel its execution. In order to allow the executing service instance to deliver operation responses, an entity must be referenced in the call of invokeAsync which provides a simple callback interface consisting of a single notify operation. The service instance calls the notify operation of that entity (“notified entity”) to deliver any notifications resulting from asynchronous operation execution. Note: This specification does not make assumptions about the notified entity. It may be an entity which is part of the client allowing the client to directly process the received notifications. For simplicity the following diagrams illustrate this. However, the entity may also be part of the service instance or may be a separate instance. See chapter 8.5 for a discussion of this issue. For each call of invokeAsync a different entity may be used. The following diagram shows synchronous and asynchronous operation execution. In the upper part a synchronous operation execution is illustrated which basically consists of an operation request sent from a client to a service instance (OSI) and a corresponding response sent back to the client. Below the asynchronous execution is illustrated. Here the client wraps the operation request into an invokeAsync message which it sends to an entity providing the interface AsynchronousInteraction. This entity immediately returns an invokeID to the waiting client. The client continues while the OSI internally executes the operation. The operation response is wrapped into a notify message which is then sent to an entity providing the interface NotificationCallback. A reference to that entity was present in the invokeAsync message. The notification attribute moreFollows=false indicates that no further notifications will follow and thus the operation has finished.

Diagram 11: Synchronous versus Asynchronous Operation Execution

32/48


The following diagram shows that asynchronous operation execution is not restricted to a single notification. This example shows an operation which produces a series of responses. An example may be an operation which observes a sensor. Periodically the operation generates a response containing the currently observed measurement value of the sensor. Each response is wrapped into a notification and sent to the NotificationCallback interface provider. The notification attribute moreFollows=true indicates that further notifications may follow. In this example, the client after some time aborts the operation using its invokeID.

Diagram 12: Asynchronous Operation Execution with multiple Notifications

8.1


Name

Usage

from OAS

New

OA_OperationRequest

I

OA Types

Yes


I

OA Types

Yes

OA_OperationResult

I

OA Types

Yes

OA_OperationFailure

I

OA Types

Yes

OA_Notification

I

OA Types

Yes

33/48


OA_OperationResponse Notification

I

OA_InvokeID

I, O


E

OA_AbortNotPossible

OA Types

Yes

OA Types

Yes


Yes

E


Yes

OA_InvalidState

E


Yes


E


No


E


No

OA_NoApplicableCode

E


No

OA_InternalError

E


No


8.2

Specification of the Interface Operations The following diagram gives an overview about the operations of the Asynchronous Interaction Interface.

Diagram 13: Operations of Asynchronous Interaction Interface

8.2.1

Specification of the invokeAsync Operation The mandatory invokeAsync operation starts asynchronous execution of an operation. The invokeAsync operation returns immediately. It returns an identifier to the caller (invocation ID) which represents the asynchronous execution. In order to allow the executing service instance to deliver notifications, an entity must be referenced in the call of invokeAsync which provides a callback interface. The service instance calls the notify operation of that entity to deliver notifications resulting from asynchronous operation execution. If no such entity is referenced, notifications will not be delivered which may be sufficient in certain cases. Any exception thrown by the invokeAsync operation signals that starting the asynchronous execution failed. Especially if the OA_OperationRequest parameter contains an invalid operation name, the invokeAsync operation throws an OA_InvalidParameterValue exception. If the operation name is valid but asynchronous execution of that operation is not supported, the invokeAsync operation throws an

34/48

Specification of the OA Basic Service – Specification of the invokeAsync Operation OA_AsyncOperationUnsupported exception. Any exception thrown by the asynchronously executing operation does not lead to an exception of the invokeAsync operation but is delivered to the provider of the callback interface. See the description of the notify operation.

Overrides

not applicable

Preconditions

none

Post conditions

Requested operation is executed asynchronously.

Use

mandatory

Receives

Name

request

callback

Type

OA_OperationRequest

NotificationCallback

Returns

Type

Description

mandatory

Specifies the operation to be executed asynchronously. Contains its name and input parameters.

optional

Reference to a callback interface used to receive notifications. If absent, notifications will not be received. Description

OA_InvokeID Throws

Use

Identifies the asynchronous execution. Type

Cause





OA_NoApplicableCode


OA_InternalError



Asynchronous execution of the specified operation is not supported.

Table 10: Specification of the invokeAsync Operation

35/48

Specification of the OA Basic Service – Specification of the abort Operation

8.2.2

Specification of the abort Operation The mandatory abort operation aborts execution of a previously invoked asynchronous operation identified by its invocation ID which was returned when calling the invokeAsync operation. An exception indicates that it is not possible to abort the operation. If the operation has terminated in the meantime (by itself or due to a previous abort) the abort operation may either throw an OA_InvalidParameterValue exception or an OA_InvalidState exception. This is implementation-dependent: If the information that the operation has already terminated is still available, the abort operation may throw an OA_InvalidState exception. Otherwise, an OA_InvalidParameterValue exception indicates that the invocation ID is no longer referring to an existing operation invocation.

Overrides

not applicable

Preconditions

none

Post conditions

Identified asynchronous operation is no longer executing.

Use

mandatory

Receives

Name invokeID

Type

Use

OA_InvokeID

Returns

mandatory

Description Identifies the asynchronous execution to abort.

Type

Description

Type

Cause

void Throws





OA_NoApplicableCode


OA_InternalError


OA_UnsupportedOperation

The abort operation is not supported.

OA_AbortNotPossible

The asynchronously executing operation is still running and can currently not be aborted.

OA_InvalidState

The asynchronously executed operation is no longer running.

Table 11: Specification of the abort Operation

36/48

Specification of the OA Basic Service – Specification of the abort Operation This specification does not explicitly forbid that a client aborts an operation which was not invoked by that client. A client having information about an invocation ID may be allowed to abort the operation. Any restrictions are out of scope of this specification.

37/48

Specification of the OA Basic Service – Specification of the notify Operation

8.2.3

Specification of the notify Operation During or at the end of an asynchronous execution of an operation, notify is called to deliver a notification to the provider of the NotificationCallback interface (“notified entity”). That entity was referenced in the corresponding call of invokeAsync for that operation. A notification may contain the operation’s return value, an exception thrown by the operation or any other contents dependent on the operation, e.g. execution progress information. The notification contains the invocation ID to identify the related asynchronous operation execution.

Overrides

not applicable

Preconditions

Asynchronous operation execution was started.

Post conditions

none

Use

mandatory

Receives

Name notification

Type

Use

OA_Notification

Returns

mandatory

Description Delivered Notification

Type

Description

Type

Cause

void Throws





OA_NoApplicableCode


OA_InternalError


Table 12: Specification of the notify Operation

38/48


8.3

Specification of extended Service Capabilities A service providing the Synchronous Interaction Interface shall indicate in its service capabilities which operations can be executed by means of the invokeAsync operation. For this purpose, the general description of an operation (which is part of the common service capabilities) shall be extended for the invokeAsync operation. The extension consists of a list of the operations which are supported by means of the invokeAsync operation. This includes also the input and output parameters of each such operation.

8.4

Specification of additional Types The Asynchronous Interaction Interface defines new OA Types which will become part of the OAS “OA Types”. Exception types will become part of the OAS “OA Types/Exception Types”. This interface specification does not define any new OT Types and does not introduce any new nonORCHESTRA Types. The following diagram gives an overview about the OA Types used by the interface operations. They are described in the following sections.

Diagram 14: OA Types of Asynchronous Interaction Interface

39/48


8.4.1

OA_OperationRequest The OA_OperationRequest type is used to specify an operation to be executed. In the context of the invokeAsync operation this type is used to specify the operation to be executed asynchronously. It consists of the operation name and a list of operation parameters.

8.4.2

OA_OperationResponse The OA_OperationResponse type contains the response to an operation request. It may either contain an operation result value (which also may be empty) or may be an indication of a failure which is modeled as exception. Therefore, OA_OperationResponse is an abstract type with the following two derived types.

8.4.2.1

OA_OperationResult

The OA_OperationResult type contains the result (return value) of an operation execution. This is considered to be the normal response to an operation request. It consists of an attribute result whose type is operation dependent and which is absent if the operation has an empty result. 8.4.2.2

OA_OperationFailure

The OA_OperationFailure type contains the exception thrown by an operation execution. This is considered to be the failure response to an operation request. It consists of an attribute failure whose type is OA_AbstractException. 8.4.3

OA_Notification The OA_Notification type represents a notification which is input to the notify operation during or at the end of an asynchronous operation execution. It consists of the following attributes: •

invokeID: identifies the asynchronous operation execution by means of the invocation ID which was returned when calling the invokeAsync operation.

•

moreFollows: A value of true signals to the notified entity that this operation execution may produce further notifications. A value of false signals to the notified entity that this operation execution will not produce any further notification.

•

sequenceCounter: an optional counter whose value is incremented with each notification related to the same invocation ID.

The fact that various types of notifications are possible dependent of the executing operation is expressed by defining OA_Notification to be an abstract type. The exact information to be carried in the notification is part of corresponding sub types. As most important sub type OA_OperationResponseNotification is predefined (see below) to carry the operation response (either being a return value or an exception). An example of another notification type would be an execution progress indication. 8.4.3.1

OA_OperationResponseNotification

The OA_OperationResponseNotification type is an extension of OA_Notification to include an OA_OperationResponse value. This notification type is therefore used to deliver an operation response to the notified entity. 8.4.4

OA_InvokeID Identifier of an asynchronous operation invocation (invocation ID). When the invokeAsync operation is called to start an asynchronous operation execution, an invocation ID is allocated by the called instance and returned to the caller. It is then used to uniquely identify this operation execution in subsequent

40/48

Specification of the OA Basic Service – Specification of additional Types calls of the abort or notify operations. The internal structure of this identifier is platform specific and thus not specified here. There must be a one-to-one mapping between an invocation ID and a corresponding operation execution inside the OSN. This also implies that an ID should never be reused once the corresponding asynchronous operation execution has finished. 8.4.5

OA_AsyncOperationUnsupported An exception of type OA_AsyncOperationUnsupported indicates that asynchronous execution of an operation is not supported. The name of the operation shall be indicated.

8.4.6

OA_AbortNotPossible An exception of type OA_AbortNotPossible indicates that the asynchronously executing operation is still running and can currently not be aborted by means of the abort operation.

8.4.7

OA_InvalidState An exception of type OA_InvalidState indicates that an operation referring to an asynchronous operation execution is not possible due to the state of that execution.

Diagram 15: Exception Types of Asynchronous Interaction Interface

41/48


8.5

Known Issues and Limitations The Asynchronous Interaction Interface described here is kept simple to focus on the general mechanism. It could of course be extended. Possible extensions could for example be: •

an additional optional input parameter of the invokeAsync operation by which the caller can specify that the asynchronous execution shall start at a given time. If unspecified execution can start immediately or at a point in time chosen by the operation provider.

•

an additional optional input parameter of the invokeAsync operation by which the caller can specify a maximum amount of time for processing the asynchronous operation.

•

additional operations suspend and resume which are optionally supported. Each operation takes the invocation ID as input parameter. By means of these operations a client can temporarily stop operation execution and continue it later on.

These extensions could be considered in future versions of this specification. 8.5.1

Role of the NotificationCallback Interface There was a discussion about the role of the NotificationCallback Interface during which it was stated that such an interface would not be suitable to pass notifications to end-user applications e.g. due to firewalls. The concern was that in order to receive notifications a client must provide such an interface which would mean that it had to implement server functionality which may not always be feasible. It was therefore proposed to add an additional operation to the Asynchronous Interaction Interface which allows a client to pick up notifications in case that it can not provide a callback interface. This operation could e.g. be called periodically by the client (polling). However, the discussion shows a misunderstanding of the NotificationCallback interface. This specification only defines the interface and its notify operation as a way for a service instance to deliver a notification to the provider of that interface (“notified entity”). It does not make any assumptions about that entity. Especially it is not meant that the notified entity always resides on the client-side where it may be hidden behind some kind of firewall. The following list gives some ideas how a notified entity may look like: •

It may indeed be part of the client program which allows that client to directly process a received notification by implementing the notify operation in an appropriate way. Of course this would mean that the client is reachable like a service instance which could be possible or not.

•

It may be a separate OSI which collects incoming notifications from various services and sends them to interested instances by means of a certain communication channel, e.g. e-mail.

•

A more realistic scenario may be an entity which is part of the instance which provides the Asynchronous Interaction Interface (or is again an independent OSI). That entity simply manages a notification queue. The notify operation puts the notification into the queue. An additional interface operation (dequeue) can be used by any connected client to pick up a queued notification identified by its invocation ID. This would be a solution for clients which are not able to play the role of notified entities. This example is illustrated in the following diagram.

42/48


Diagram 16: Example of service-side NotificationCallback usage The point is that the specification already is flexible enough to handle various cases. Each call of the invokeAsync operation may even choose a different notified entity. On the other hand, following the proposal of the discussion and adding an operation to the interface to let the client actively request for a notification would impose already a certain implementation. Such an operation could be part of a dedicated interface which may be derived from the NotificationCallback Interface.

43/48

Specification of the OA Basic Service – Predefined Exception Types for all ORCHESTRA Services

9

Predefined Exception Types for all ORCHESTRA Services The OA Basic Service defines some exception types to be used by all ORCHESTRA Services if adequate. These exception types will become part of the OAS “OA Types/Exception Types”. They are listed in the following table and described in the following subchapters.

Name OA_AbstractException

Usage

from OAS

New

E


Yes

E


Yes


E


Yes

OA_NoApplicableCode

E


Yes

OA_InternalError

E


Yes

OA_CodeLocation

E


Yes

OA_InvalidPermission

E


Yes

OA_UnsupportedOperation

E


Yes


Table 13: Predefined exception types

9.1

OA_AbstractException The OA_AbstractException type specifies the basic structure of an exception that may result from an operation request of an ORCHESTRA Service. It is an abstract exception from which any exception of an ORCHESTRA Service inherits. It consists of the following elements: •

message: human-readable specification of the exception. The message may be retrieved by the getMessage operation allowing the client to specify in which language the message should be delivered. The default language is English. The underlying mechanism necessary to retrieve the message in a given language is out of scope of this specification.

•

cause: optional reference to another exception as a possible cause for the exception.

Note: The presence of an operation like e.g. getMessage as part of an exception type is still platformneutral. It just indicates that it shall be possible to call the operation referring to an instance of the exception type. This does not determine how the operation might be implemented. Any exception type of an ORCHESTRA Service shall be derived from OA_AbstractException. The following diagram illustrates how the predefined exception types are derived from the abstract exception type.

44/48

Specification of the OA Basic Service – Predefined Exception Types for all ORCHESTRA Services

Diagram 17: Class diagram of the predefined exception types

9.2

OA_MissingParameterValue An operation request does not include a value of a mandatory parameter. The name of the parameter shall be indicated.

9.3

OA_InvalidPermission The exception indicates an invalid permission to perform a requested operation. The ORCHESTRA Service type and the operation name shall be indicated.

9.4

OA_InvalidParameterValue An operation request contains an invalid parameter value. The name and the value of the parameter shall be indicated.

9.5

OA_UnsupportedOperation A requested operation is not supported. The ORCHESTRA Service type and the operation name shall be indicated.

9.6

OA_InternalError A problem occurred in the runtime environment (e.g. out of memory). Optionally, an OSI may deliver the source code information as specified in OA_CodeLocation in order to analyse the error. Multiple OA_CodeLocation values can be included in order to represent some kind of “stack trace”. If multiple locations are present, they form a list. The order of the locations in the list shall be reverse to

45/48

Specification of the OA Basic Service – Predefined Exception Types for all ORCHESTRA Services the order in which these locations have been reached when executing the code. Thus the first location in the list shall be the one where the error occurred. 9.6.1

OA_CodeLocation This type provides information on source code level that may be relevant to analyse an exception due to an internal error. It contains the following attributes:

9.7

•

serviceType: specifies the service type to which the internal error corresponds

•

operationName: specifies the name of the operation in which the error occurred

•

sourceFileName: specifies the name of the source file in which the error occurred

•

lineNumber: specifies the line number in the source file in which the error occurred

OA_NoApplicableCode No other basic or service-specific exception type applies to this exception.

46/48

Specification of the OA Basic Service – Appendix A: Abstract Test Suite (normative)

10

Appendix A: Abstract Test Suite (normative) When creating an implementation specification of the OA Basic Service, the “Rules for Implementation Specifications of ORCHESTRA Services” defined in chapter 9.2.2.3 and the “Rules for the Service Mapping to a given Platform” of the RM-OA shall be obeyed. In addition, the following tests shall be performed to ensure conformance of an implementation specification to the platform-independent specification of the OA Basic Service: 1. Syntactical Conformance •


•


•


•




Additional conformance checks that are specifically to the OA Basic Service are not required.

47/48

Specification of the OA Basic Service – Appendix B: UML Models (normative)

11 Appendix B: UML Models (normative) 11.1 Static Model 11.2 Dynamic Model

48/48




Specification of the Ontology Access Service Interface .

Revision

1/33

[2.1 / 1.2]

Specification of the Ontology Access Service Interface – Document Control Page


Specification of the Ontology Access Service Interface

Creator


Subject


Description

This document defines an abstract and platform independent formal specification of the Ontology Access interface.

Publisher


Contributor


ETH Zurich

Isenegger, Daniel

ETH Zurich

Hilbring, Désirée

Fraunhofer IITB

ETH Zurich

Date

2008-05-19

Type

Text

Format

application/msword

Identifier


Source

Not applicable

Language

en-GB.

Relation

none

Coverage



D3.4.4


WP3.4


2007-09-30


2007-08-28

Audience


Version number

2.0 / 1.2

Date

2008-05-19

Modified by

Hilbring, Désirée

Fraunhofer IITB

Comments Status

Draft WP leader accepted SP leader accepted Technical supervisor accepted

2/33

Specification of the Ontology Access Service Interface – Document Control Page

Quality checked Project coordinator accepted Action requested


3/33

Specification of the Ontology Access Service Interface – Revision History


Date

Sections changed

Description

0.1 / 2.0.4

2006-10-31

all

1st major release based on the draft originally created by BRGM; added the getABox /getTbox operations. All sections completed.

0.2 / 2.0.4

2006-10-3

all

2nd release; general improvements; type definitions; operations redefinitions (getTaxonomy, getABoxVocabulary, getTBoxVocabulary)

0.3 / 2.0.4

2006-11-10

all

Realignment with original RM-OA service description. Renaming of getTaxonomy operation to parseOntology. Other minor changes.

0.4 / 2.0.4

2006-11-16

all

Incorporated comments from reviewers.

0.5 / 2.0.4

2006-12-18

all

General improvements. Redesign of the Ontology type and other non-primitive types.

1.0 / 2.0.4

2007-01-18

all

Incorporated feedback from RM_OA. First mature specification.

1.1 / 2.0.4

2007-06-18

all

Incorporated decisions SP3/Plenary Meeting.

2.0/1.2

2007-08-28

all

Final version of the specifications. Previous Ontology Access Service Specifications were separated in two documents: Ontology Access Abstract Interface Specification Ontology Access Abstract Services Specification.

2.1/1.2

2008-05-19

Section 5

Implementation experience in Semantic Catalogue shows that Ontology Access Service interface is useful without operation parseOntology. Thus, parseOntology is set optional.

from

the

Paris

Inclusion of information about specific interface capabilities Fixing some cut and paste errors in type description section. Elimintation of duplicate parameter table.

4/33

Specification of the Ontology Access Service Interface – Table of Contents

Table of Contents 1

Foreword .....................................................................................................................................................8

2

Conventions ................................................................................................................................................9 2.1

Abbreviations .......................................................................................................................................9

2.2

Terms and definitions ...........................................................................................................................9

2.3

UML Notation .......................................................................................................................................9

2.4

Conformance ........................................................................................................................................9

2.4.1


3

Role and Scope of the Ontology Access Interface ...................................................................................10

4

Context of the Ontology Access Interface .................................................................................................11

5

4.1

Relations to Standards .......................................................................................................................11

4.2


4.3

Relations to ORCHESTRA Application Schemas ..............................................................................12

Specification of the Ontology Access Interface .........................................................................................13 5.1

Specification of an OAS Profile of Parameter Types used by the Ontology Access Interface ..........14

5.2


5.2.1

Specification of the getOntology Operation ................................................................................15

5.2.2

Specification of the setOntology Operation ................................................................................16

5.2.3

Specification of the deleteOntology Operation ...........................................................................17

5.2.4

Specification of the parseOntology Operation ............................................................................18

5.2.5

Specification of the getTBoxStatements Operation ....................................................................20

5.2.6

Specification of the getABoxStatements Operation....................................................................21

5.3


5.3.1

OA_GetOntologyRequest ...........................................................................................................25

5.3.2

OA_SetOntologyRequest ...........................................................................................................25

5.3.3

OA_DeleteOntologyRequest ......................................................................................................25

5.3.4

OA_ParseOntologyRequest .......................................................................................................26

5.3.5

OA_GetTBoxStatementsType ....................................................................................................26

5.3.6

OA_GetABoxStatementsType ....................................................................................................26

5.3.7

OA_Ontology ..............................................................................................................................27

5.3.8

OA_OntologyStatementsType ....................................................................................................27

5.3.9

OA_GetOntologyResponse ........................................................................................................27

5.3.10

OA_SetOntologyResponse.........................................................................................................28

5/33

Specification of the Ontology Access Service Interface – Table of Contents 5.3.11

OA_DeleteOntologyResponse....................................................................................................28

5.3.12

OA_ParseOntologyResponse.....................................................................................................28

5.3.13

OA_GetTBoxStatementsResponse ............................................................................................28

5.3.14

OA_GetABoxStatementsResponse ............................................................................................29

5.4

Specification of the Service specific Capabilities ...............................................................................30

5.5

Specification of additional OA Types .................................................................................................31

5.5.1

OA_OntASCapabilities ...............................................................................................................31

5.5.2

OA_MI_OntologyInfo ..................................................................................................................31

5.6 6

Known Issues and Limitations ...........................................................................................................31

Appendix A: UML Models (normative) ......................................................................................................32 6.1

XMI Model (mandatory)......................................................................................................................32

6.2

Static UML Model (optional) ...............................................................................................................32

6/33

Specification of the Ontology Access Service Interface – Tables and Diagrams

Tables Table 1: Summary of additional Service Operations ........................................................................................13 Table 2: Referenced OA Types ........................................................................................................................14 Table 3: Specification of the getOntology Operation ........................................................................................16 Table 4: Specification of the setOntology Operation ........................................................................................17 Table 5: Specification of the deleteOntology Operation ...................................................................................18 Table 6: Specification of the parseOntology Operation ....................................................................................19 Table 7: Specification of the getTBoxVocabulary Operation............................................................................21 Table 8: Specification of the getABoxVocabulary Operation ...........................................................................23 Table 28: Sections of the service specific capabilities .....................................................................................30 Table 29: Attributes of the service specific capabilities of section OntASCapabilities .....................................30

Diagrams Diagram 1: Class Diagram of the Map Diagram Interface ...............................................................................13 Diagram 2: Summary of OA Types defined in the Ontology Access Interface ................................................25 Diagram 3: Class diagram for capabilities ........................................................................................................31

7/33

Specification of the Ontology Access Service Interface – Foreword

1

Foreword This document is an abstract specification of the Ontology Access interface type and is based on the Template for the abstract Specification of ORCHESTRA Interface Types version 1.2. It replaces any previous specifications of the Ontology Access Interface. An update and refinement of chapters was required due to the requirements to separate previous Ontology Access Service Specifications in two documents: Ontology Access Abstract Interface Specification Ontology Access Abstract Services Specification. This interface specification is integral part of the Ontology Access Service Specification and it is to be considered accordingly. This document assumes also that the reader already possesses at least basic knowledge about what ontologies are and about the terminology used in this field.

This document includes the mandatory annex: Appendix A: UML Models (normative).

8/33

Specification of the Ontology Access Service Interface – Conventions

2

Conventions

2.1


2.2

- OWL

Web Ontology Language

- WSML

Web Service Modeling Language


2.3


2.4 2.4.1


9/33

Specification of the Ontology Access Service Interface – Role and Scope of the Ontology Access Interface

3

Role and Scope of the Ontology Access Interface

The Ontology Access Service supports the read access to a logical ontology and to export, import and delete, a complete specification of a logical ontology into an ontology store. It also provides a high-level view to the content of the ontology, allowing the client to get information about the taxonomy (classes and properties) defined by any stored ontology and to extract TBox and ABox statements for human/machine interpretation. The Ontology Access Service is independent of any ontology technology, like the ontology language (e.g. OWL). However, the current version of the Ontology Access Service ignores ontological classes that are implicitly defined by rules of description logics (and only the explicit taxonomy is considered). Some typical usages of this service are: •

Getting a list of the ontologies this service is providing access to;

•

Retrieving a partially or fully a stored ontology;

•

Storing and deleting available ontology entries;

•

Getting high-level information about ontology, such as the list of concepts and properties, the TBox and optionally ABox statements.

This interface does not provide: •

Creating ontologies – this interface defines interoperable the storage and management of ontologies, but it doesn’t provide any tool to create ontology structures. This is the purpose of dedicated tools (like Protégé) and methodologies (as the one defined in deliverable D2.3.2).

•

Inferencing – this is the responsibility for the Inferencing Interface. However ontologies used for the inferencing process may be accessed using the Ontology Access Service.

•

Management of knowledge bases – this is beyond the purpose of this interface. The Ontology Access Service may be used to help for an external creation of a knowledge base (using “getTBoxVocabulary” and “getABoxVocabulary” operations to extract statements), but is not able to store, search and manage huge knowledge bases.

•

Remote editing of ontologies – it is assumed that the client, once it is getting the ontology from this service, will use specialized tools or API (like Protégé or Jena API) to deal with the ontology structure and editing. Calling operations on a remote service to work with ontologies (like for example introducing new concepts and properties or updating existing ones) doesn’t seem reasonable in terms of architecture or usability.

10/33

Specification of the Ontology Access Service Interface – Context of the Ontology Access Interface

4

Context of the Ontology Access Interface

4.1

Relations to Standards Related standards: Not applicable. Standards for a service interface to access ontologies are not available. These specifications are the first attempt for such an ontology management interface/service standard. Related ontology languages/formats/technologies The Ontology Access Service does not rely on any existing ontology language in particular, put it assumes that some concepts, like “Classes”, “Properties” and “Individuals” are common to most of them. As to the date of writing this document, only ontology languages/formats/technologies are available for describing ontologies. −

OWL

Defined by W3C, it is an extension of the RDF language. Many tools and API are available to deal with it but is missing very important points like spatial or literal operators. −

WSML

Currently proposed to the W3C, it is oriented to the service choreography & orchestration, but can be used to define data ontologies as well. It proposes ontologies based on literal, but not yet on spatial data. Tools are not as mature as the ones created for OWL. −

SPARQL

SPARQL is developed by the W3C RDF Data Access Working Group. SPARQL is a standardized query language for RDF data: The SPARQL Protocol uses WSDL 2.0 to describe a means for conveying SPARQL queries to a SPARQL query processing service and returning the query results to the entity that requested them. −

Jena

Jena is a Java framework for building Semantic Web applications. It provides a programmatic environment for RDF, RDFS, OWL, SPARQL and includes a rule-based inference engine. The Jena Framework includes an OWL and RDF API, reading and writing RDF in RDF/XML, N3 and NTriples, in-memory and persistent storage and a SPARQL query engine −

Joseki

Joseki is an HTTP and SOAP engine that supports the SPARQL Protocol and the SPARQL RDF Query language. Joseki supports RDF Data from files and databases, HTTP (GET and POST) implementation of the SPARQL protocol and a SOAP implementation of the SPARQL protocol −

Sesame

Sesame is an open source RDF database with support for RDF Schema inferencing and querying. Sesame can be deployed on top of a variety of storage systems (relational databases, in-memory, filesystems, keyword indexers, etc.), it offers a flexible access API, which supports both local and remote (through HTTP or RMI) access and supports several query languages including SeRQL, RQL, RDQL and (in Sesame 2.x) SPARQL.

Please refer to ORCHESTRA deliverable D2.3.2 for more details about these technologies.

11/33

Specification of the Ontology Access Service Interface – Context of the Ontology Access Interface Adoption of standards: Not applicable. For this specification, ontologies are represented in an abstract manner. It is the responsibility of a specific implementation to support for an existing ontology language (e.g. OWL). The supported ontology languages will be advertised in the service capabilities. Methodology for the adoption of standards: Not applicable. Modifications of the existing standards: Not applicable. Contribution to standards: The Ontology Access Service Interface was presented at the July 2007 OGC TC Meeting in Paris. ORCHESTRA deliverables are published in the public domain so this specification can be standardised also by OGC/ISO if desired.

4.2

Relations to ongoing Initiatives and related Projects There are no immediate relations to ongoing Initiatives and related Projects. However the INSPIRE technical discussions are monitored. INSPIRE efforts and interests converge towards data harmonization of the geospatial data in Europe. Data mappings could be stored in ontologies that are managed by an Ontology Access Service and thus available in an interoperable manner for everyone interested. In addition, if in the future portrayal harmonisation may be considered as a first step in data harmonisation, then portrayal rules and ontologies can be made available also through an Ontology Access Service Instance.

4.3

Relations to ORCHESTRA Application Schemas The Ontology Access Interface Type Specification uses Basic and OA Types that are defined in the package OAS/Basic Types, OAS/OA Types and OAS-MI/OA-MI Types of the Information Viewpoint. The Ontology Access Type Specification uses OA-MI Types that are defined in the package OASMI/OA-MI Types of the Information Viewpoint.

12/33

Specification of the Ontology Access Service Interface – Specification of the Ontology Access Interface

5

Specification of the Ontology Access Interface cd Interface «interface» Ontology Access + + + + + +

getOntology(GetOntology :OA_GetOntologyType) : OA_GetOntologyResponse setOntology(SetOntology :OA_SetOntologyType) : OA_SetOntologyResponse deleteOntology(DeleteOntology :OA_DeleteOntologyType) : OA_DeleteOntologyResponse parseOntology(ParseOntology :OA_ParseOntologyType) : OA_ParseOntologyResponse getTBoxStatements(GetTBoxVocabulary :OA_GetTBoxStatementsType) : OA_GetTBoxStatementsResponse getABoxStatements(GetABoxVocabulary :OA_GetABoxStatementsType) : OA_GetABoxStatementsResponse

Diagram 1: Class Diagram of the Map Diagram Interface The Ontology Access Interface defines the following operations:

Operation Name

Use

Description

getOntology

mandatory

Retrieves an existing ontology from the ontology store.

setOntology

mandatory

Stores a new ontology in the ontology store, if the ontology format is supported. The operation confirms the success of the operation by sending back to the client a Boolean “TRUE”.

deleteOntology

mandatory

Removes an existing ontology from the ontology store. The operation confirms the success of the operation by sending back to the client a Boolean “TRUE”.

parseOntology

optional

Given an ontology or a part (selection) of an ontology, it returns the hierarchy of classes (concepts) and properties that are defined by this ontology (a high-level view of the ontology). The format of the result could be, for example basic XHTML (without CSS) that is suitable for both direct display or further machine processing.

getTBoxStatements

optional

Given an ontology or a part (selection) of an ontology, it returns a list of TBox statements ready to be used for creating a Knowledge Base.

getABoxStatements

optional

Given an ontology or a part (selection) of an ontology, this optional operation returns a list of ABox statements ready to be used for creating a Knowledge Base.


13/33


5.1

Specification of an OAS Profile of Parameter Types used by the Ontology Access Interface The following non basic types are used within this specification: Name

Usage

from OAS

New

OA_GetOntologyType

I

OA_Types

Yes

OA_SetOntologyType

I

OA_Types

Yes

OA_DeleteOntologyType

I

OA_Types

Yes

OA_ParseOntologyType

I

OA_Types

Yes

OA_GetTBoxStatementsType

I

OA_Types

Yes

OA_GetABoxStatementsType

I

OA_Types

Yes

I,O

OA_Types

Yes

OA_Query

I

OA_Types

No

OA_OntologyStatementsType

O

OA_Types

Yes

OA_GetOntologyResponse

O

OA_Types

Yes

OA_SetOntologyResponse

O

OA_Types

Yes

OA_DeleteOntologyResponse

O

OA_Types

Yes

OA_ParseOntologyResponse

O

OA_Types

Yes

OA_GetTBoxStatementsResponse

O

OA_Types

Yes

OA_GetABoxStatementsResponse

O

OA_Types

Yes

OA_OntologyNotDefined

E

OA_Types

Yes

OA_InvalidOntology

E

OA_Types

Yes

OA_InvalidFormat

E

OA_Types

No

OA_Ontology


14/33


5.2

5.2.1

Specification of the Operations

Specification of the getOntology Operation The mandatory getOntology operation retrieves an available ontology from the ontology store (at the server) and returns it to the user. The signature of the operation is: •

OA_GetOntologyResponse () throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_OntologyNotDefined, OA_InvalidFormat

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

mandatory

Receives

Name

GetOntology

Type

OA_GetOntologyRequest

Returns

Type

Description

mandatory

Parameter specifying the name of the ontology to be retrieved and optionally the format in which the ontology is returned. Default format is OWL. Description

Contains an OA_Ontology type with the requested ontology.

OA_GetOntologyResponse Throws

Use

Type

Cause


Operation request contains an invalid parameter value. Returns the name of the parameter with invalid value.


Operation request does not include a parameter value. Returns the name of the missing parameter.

OA_NoApplicableCode


OA_InternalError

A problem occurred in the runtime environment (e.g. out of memory).

15/33



Operation request is for an ontology not offered by the server.

OA_InvalidFormat

Operation request contains a Format not offered by the server.

Table 3: Specification of the getOntology Operation

5.2.2

Specification of the setOntology Operation The mandatory setOntology operation loads an user-created ontology in an ontology store at the server. If the name of the ontology already exists in the ontology store, then the existing ontology will be replaced with the new one (acts as an update operation). The signature of the operation is: •

OA_SetOntologyResponse () throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_InvalidOntology, OA_InvalidFormat

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

mandatory

Receives

Name

SetOntology

Returns

Type

OA_SetOntologyRequest

Type

Description

mandatory

Parameter specifying the name and the ontology to be stored. The type OA_Ontology (used by the OA_SetOntologyRequest) is used to define the ontology. Description

Contains a Boolean “TRUE” if the operation completed successfully. The confirmation protocol is necessary in order for the client to detect and correct network transmission errors.

OA_SetOntologyResponse

Throws

Use

Type

Cause Operation request contains an invalid parameter value. Returns the name of the parameter with invalid value.


16/33




OA_NoApplicableCode


OA_InternalError


OA_InvalidOntology

Operation request contains an ontology that can not be imported by the server (invalid).

OA_InvalidFormat


Table 4: Specification of the setOntology Operation

5.2.3

Specification of the deleteOntology Operation The mandatory deleteOntology operation deletes an available ontology from the ontology store (at the server). If the name of the ontology does not exist in the ontology store, then an exception is thrown. The signature of the operation is: •

OA_DeleteOntologyResponse () throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_OntologyNotDefined

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

mandatory

Receives

Returns

Name

Type

Use

Description

DeleteOntology

OA_DeleteOntologyRequest

mandatory

Parameter specifying the name of the ontology to be deleted.

Type

Description

17/33


Contains a Boolean “TRUE” if the operation completed successfully. The confirmation protocol is necessary in order for the client to detect and correct network transmission errors.

OA_DeleteOntologyResponse

Throws

Type





OA_NoApplicableCode


OA_InternalError




Table 5: Specification of the deleteOntology Operation

5.2.4

Specification of the parseOntology Operation The optional parseOntology operation returns the hierarchy of classes (concepts) and properties that are defined by a specific ontology or portion of an ontology. The ontology itself can be one of the already stored ontologies (and so only the identification is required) or it can be sent as parameter. Additionally the user can specify a query string that will instruct the service to select and use only a specific portion of the ontology and can specify the output format. This operation shall be used by a client that just needs a high-level view of the content of an ontology (details about classes and properties are not returned), e.g. to check the content of the ontologies available at the server. Clients that need to interact more deeply with an ontology, shall retrieve the ontology and then use dedicated tools (like Protégé or Jena API). The signature of the operation is: •

OA_ParseOntologyResponse () throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_OntologyNotDefined, OA_InvalidQuery, OA_InvalidOntology, OA_InvalidFormat

18/33


Overrides

not applicable

Preconditions

none

Post conditions

none

Use

optional

Receives

Name

ParseOntology

Type

OA_ParseOntologyRequest

Returns

Type

Description

mandatory

Parameter specifying the name of the ontology to be used, the ontology itself (optional), a query (optional) and the format (optional) in which the ontology is returned. Description

Contains a document (default format XHTML) to be displayed or further processed.

OA_ParseOntologyResponse Throws

Use

Type





OA_NoApplicableCode


OA_InternalError




OA_InvalidQuery

Operation request contains a Query not understood by the server.

OA_InvalidOntology


OA_InvalidFormat


Table 6: Specification of the parseOntology Operation

19/33


5.2.5

Specification of the getTBoxStatements Operation The mandatory getTBoxStatements operation returns a list of TBox statements (TBox Vocabulary) extracted from a specific ontology or portion of an ontology. The ontology itself can be one of the already stored ontologies (and so only the identification is required) or it can be sent as parameter. Additionally the user can specify a query string that will instruct the service to select and use only a specific portion of the ontology. This operation could be used to extracting the necessary information from an ontology for populating a Knowledge Base. The signature of the operation is: •

OA_GetTBoxStatementsResponse () throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_OntologyNotDefined, OA_InvalidQuery, OA_InvalidOntology, OA_InvalidFormat

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

mandatory

Receives

Name

GetTBoxStatements

Returns

Type

OA_GetTBoxStatementsType

Type

Description

mandatory

Parameter specifying the name of the ontology to be used, the ontology itself (optional), a query (optional) and the format (optional) in which the ontology is returned.

Description

OA_ GetTBoxStatementsResponse Throws

Use

Type

Contains a list of the requested statements. Cause

20/33


Operation request contains an invalid parameter value. Returns the name of the parameter with invalid value.




OA_NoApplicableCode


OA_InternalError




OA_InvalidQuery


OA_InvalidOntology


OA_InvalidFormat


Table 7: Specification of the getTBoxStatements Operation

5.2.6

Specification of the getABoxStatements Operation The optional getABoxStatements operation returns a list of ABox statements (ABox Vocabulary) extracted from a specific ontology or portion of an ontology. The ontology itself can be one of the already stored ontologies (and so only the identification is required) or it can be sent as parameter. Additionally the user can specify a query string that will instruct the service to select and use only a specific portion of the ontology. This operation could be used to extracting the necessary information from an ontology for populating a Knowledge Base. Considering the increased difficulty of extracting the ABox Vocabulary, this operation is defined as optional.

21/33

Specification of the Ontology Access Service Interface – Specification of the getABoxStatements Operation The signature of the operation is: •

OA_GetABoxStatementsResponse () throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_OntologyNotDefined, OA_InvalidQuery, OA_InvalidOntology, OA_InvalidFormat

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

optional

Receives

Name

GetABoxStatements

Type

OA_GetABoxStatementsType

Returns

Type

Description

mandatory


Description

OA_ GetABoxStatementsResponse Throws

Use

Type

Contains a list of the requested statements. Cause Operation request contains an invalid parameter value. Returns the name of the parameter with invalid value.





OA_NoApplicableCode

22/33

Specification of the Ontology Access Service Interface – Specification of the getABoxStatements Operation

OA_InternalError




OA_InvalidQuery


OA_InvalidOntology


OA_InvalidFormat


Table 8: Specification of the getABoxStatements Operation

23/33

Specification of the Ontology Access Service Interface – Specification of Parameter Types

5.3

Specification of Parameter Types These OA Types are part of the OAS “OA Types”. This interface specification does not define any new OT Types. This interface specification does not introduce any new non-orchestra Types.

cd OAS Types «DataType» Ontology Access Serv ice Types:: OA_SetOntologyResponse

«DataType» Ontology Access Serv ice Types:: OA_SetOntologyRequest

+

+ +

Inserted: Boolean

Ontology: OA_Ontology Name: CharacterString

«DataType» Ontology Access Serv ice Types:: OA_DeleteOntologyRequest

«DataType» Ontology Access Serv ice Types:: OA_DeleteOntologyResponse

+

+

Name: CharacterString

«DataType» Ontology Access Serv ice Types: :OA_GetOntologyRequest + +

Name: CharacterString Format: CharacterString [0..1]

+

+ +

Name: CharacterString Ontology: OA_Ontology [0..1] Query: OA_Query [0..1] Format: CharacterString [0..1]

«DataType» Ontology Access Serv ice Types:: OA_MI_OntAS_Capabilities +

OntologyNames: CharacterString [0..*]

Return: CharacterString Schema: CharacterString [0..1]

«DataType» Ontology Access Serv ice Types:: OA_GetTBoxStatementsResponse +

Return: OA_OntologyStatementsType «DataType» Ontology Access Serv ice Types:: OA_OntologyStatementsType +

«DataType» Ontology Access Serv ice Types: :OA_GetABoxStatementsType + + + +


0..*

Ontology: OA_Ontology

+ + + +

«DataType» Ontology Access Serv ice Types: :OA_GetTBoxStatementsType

Format: CharacterString InternationalLanguageCode: CharacterString [0..1] Content: CharacterString

1

«DataType» Ontology Access Serv ice Types:: OA_GetOntologyResponse

«DataType» Ontology Access Serv ice Types:: OA_ParseOntologyResponse

+ + + +

1 + + +

Deleted: Boolean

«DataType» Ontology Access Serv ice Types: :OA_ParseOntologyRequest name: CharacterString Ontology: OA_Ontology [0..1] Query: OA_Query [0..1] Format: CharacterString [0..1]

«DataType» Ontology Access Serv ice Types::OA_Ontology

«DataType» Ontology Access Serv ice Types:: OA_GetABoxStatementsResponse +

Return: OA_OntologyStatementsType

24/33

Statement: CharacterString [0..*]

Specification of the Ontology Access Service Interface – Specification of Parameter Types Diagram 2: Summary of OA Types defined in the Ontology Access Interface

5.3.1

OA_GetOntologyRequest cd OAS Types «DataType» Ontology Access Serv ice Types: :OA_GetOntologyRequest + +


Parameter specifying the name of the ontology to be retrieved and optionally the format in which the ontology is returned. Default format is OWL. 5.3.2

OA_SetOntologyRequest cd OAS Types «DataType» Ontology Access Serv ice Types:: OA_SetOntologyRequest + +


Parameter specifying the name and the ontology to be stored. The type OA_Ontology (used by the OA_SetOntologyType) is used to define the ontology contains the content of an ontology, its format and optionally the code of the international language in case the ontology is in another language than GB English. 5.3.3

OA_DeleteOntologyRequest cd OAS Types «DataType» Ontology Access Serv ice Types:: OA_DeleteOntologyRequest +


Parameter specifying the name of the ontology to be deleted.

25/33

Specification of the Ontology Access Service Interface – Specification of Parameter Types 5.3.4

OA_ParseOntologyRequest cd OAS Types «DataType» Ontology Access Serv ice Types: :OA_ParseOntologyRequest + + + +

name: CharacterString Ontology: OA_Ontology [0..1] Query: OA_Query [0..1] Format: CharacterString [0..1]


5.3.5

OA_GetTBoxStatementsType cd OAS Types «DataType» Ontology Access Serv ice Types: :OA_GetTBoxStatementsType + + + +


Parameter specifying the name of the ontology to be used, the ontology itself (optional), a query (optional) and the format (optional) in which the ontology is returned. 5.3.6

OA_GetABoxStatementsType cd OAS Types «DataType» Ontology Access Serv ice Types: :OA_GetABoxStatementsType + + + +



26/33

Specification of the Ontology Access Service Interface – Specification of Parameter Types 5.3.7

OA_Ontology cd OAS Types «DataType» Ontology Access Serv ice Types::OA_Ontology + + +


Type representing a concrete Ontology (content).

5.3.8

OA_OntologyStatementsType cd OAS Types «DataType» Ontology Access Serv ice Types:: OA_OntologyStatementsType +


Defines a list of CharacterString statements.

5.3.9

OA_GetOntologyResponse cd OAS Types «DataType» Ontology Access Serv ice Types:: OA_GetOntologyResponse +


Contains an OA_Ontology type with the requested ontology.

27/33

Specification of the Ontology Access Service Interface – Specification of Parameter Types 5.3.10 OA_SetOntologyResponse cd OAS Types «DataType» Ontology Access Serv ice Types:: OA_SetOntologyResponse +

Inserted: Boolean

Parameter specifying an acknowledgment if the given ontology was added. 5.3.11 OA_DeleteOntologyResponse cd OAS Types «DataType» Ontology Access Serv ice Types:: OA_DeleteOntologyResponse +

Deleted: Boolean

Parameter specifying an acknowledgment if the given ontology was deleted. 5.3.12 OA_ParseOntologyResponse cd OAS Types «DataType» Ontology Access Serv ice Types:: OA_ParseOntologyResponse + +


Contains a document (default format XHTML) to be displayed or further processed.

5.3.13 OA_GetTBoxStatementsResponse cd OAS Types «DataType» Ontology Access Serv ice Types:: OA_GetTBoxStatementsResponse +


28/33

Specification of the Ontology Access Service Interface – Specification of Parameter Types Contains a list of the requested statements.

5.3.14 OA_GetABoxStatementsResponse cd OAS Types «DataType» Ontology Access Serv ice Types:: OA_GetABoxStatementsResponse +


Contains a list of the requested statements.

29/33

Specification of the Ontology Access Service Interface – Specification of the Service specific Capabilities

5.4

Specification of the Service specific Capabilities As part of ORCHESTRA D3.3.2 a meta-information schema for services is defined acting as a default OAS-MI for service capabilities. OA_MI_CapabilitiesDocument includes both the common capabilities and the service specific capabilities. While the common capabilities are defined in the specification of the Service Capabilities Interface, the specific capabilities have to be specialized in each service or interface specification. The schema for interface specific capabilities defined here is explicitly divided into the following schema sections:

Section Name

Section Contents Includes information about the specific capabilities of the OntologyAccessInterface including information about the available and activated ontologies.

OntASCapabilities

Table 9: Sections of the service specific capabilities Name

Definition

Data Type


availableOntology

available ontologies in ontology store

OA_MI_Ontolo gyInfo

0..*

format

format of ontologies

CharacterString

1..*

activeOntology

active ontologies in ontology store

OA_MI_Ontolo gyInfo

0..1

Table 10: Attributes of the service specific capabilities of section OntASCapabilities cd OAS-MI-OntAS OA_MI_SectionContentBase «Type» AS-MI Serv ice Specific OntAS:: OA_MI_OntASCapabilities + + +

availableOntology: OA_MI_OntologyInfo [0..*] format: CharacterString [1..*] activeOntology: OA_MI_OntologyInfo [0..1]

0..* «Type» AS-MI Serv ice Specific OntAS::OA_MI_OntologyInfo + + +

comment: CharacterString [0..1] name: CharacterString internationalLanguageCode: CharacterString [0..1]

30/33

Specification of the Ontology Access Service Interface – Specification of additional OA Types Diagram 3: Class diagram for capabilities

5.5

Specification of additional OA Types This service specification does define any new OA Types. These new OA Types will become part of the OAS “OA Types”. This service specification does not define any new OT Types. This service specification does not introduce any new non-orchestra Types. This subchapter holds types used for the interface specific capabilities of the Ontology Access Interface.

5.5.1

OA_OntASCapabilities

Holds interface specific capabilities of Ontology Access Interface: •

availableOntology: available ontologies

•

format: format of ontologies

•

activeOntology: active ontologies

5.5.2

OA_MI_OntologyInfo

Type for defining the meta-information and query languages the catalogue is able to handle.

5.6

•

comment (optional) – description of ontology

•

name (mandatory) – name of ontology

•

internationalLanguageCode (optional)

Known Issues and Limitations The extraction of ABox statements from an ontology is inherently difficult because it requires the processing of individuals from an ontology and not just classes. Therefore the getABoxVocabulary is an optional operation. The usage of the set/deleteOntology operations is conditioned by a functional UAA framework.

31/33

Specification of the Ontology Access Service Interface – Appendix A: UML Models (normative)

6

Appendix A: UML Models (normative)

6.1

XMI Model (mandatory) The XMI Models of this interface specification can be downloaded from the OGC Portal under the following URL: to be defined for SANY

6.2

Static UML Model (optional)

cd Interface «Interface» Ontology Access Serv ice Types::OntologyAccess + + + + + +

setOntology(OA_SetOntologyRequest) : OA_GetOntologyResponse getOntology(OA_GetOntologyRequest) : OA_GetOntologyResponse deleteOntology(OA_DeleteOntologyRequest) : OA_DeleteOntologyResponse parseOntology(OA_ParseOntologyRequest) : OA_ParseOntologyResponse getTBoxStatement(OA_GetTBoxStatementsType) : OA_GetTBoxStatementsResponse getABoxStatement(OA_GetABoxStatementsType) : OA_GetABoxStatementsResponse

cd Exceptions «DataType» Ontology Access Serv ice Exceptions:: OA_Inv alidFormat

«DataType» Ontology Access Serv ice Exceptions:: OA_IllegalQuery

«DataType» Ontology Access Serv ice Exceptions:: OA_Inv alidOntology

32/33

«DataType» Ontology Access Serv ice Exceptions:: OA_OntologyNotDefined

Specification of the Ontology Access Service Interface – Appendix A: UML Models (normative) cd OAS Types «DataType» Ontology Access Serv ice Types:: OA_SetOntologyResponse

«DataType» Ontology Access Serv ice Types:: OA_SetOntologyRequest

+

+ +

Inserted: Boolean


«DataType» Ontology Access Serv ice Types:: OA_DeleteOntologyRequest

«DataType» Ontology Access Serv ice Types:: OA_DeleteOntologyResponse

+

+


«DataType» Ontology Access Serv ice Types: :OA_GetOntologyRequest + +


+

+ +


«DataType» Ontology Access Serv ice Types:: OA_MI_OntAS_Capabilities +

OntologyNames: CharacterString [0..*]


«DataType» Ontology Access Serv ice Types:: OA_GetTBoxStatementsResponse +

Return: OA_OntologyStatementsType «DataType» Ontology Access Serv ice Types:: OA_OntologyStatementsType +

«DataType» Ontology Access Serv ice Types: :OA_GetABoxStatementsType + + + +


0..*


+ + + +

«DataType» Ontology Access Serv ice Types: :OA_GetTBoxStatementsType


1

«DataType» Ontology Access Serv ice Types:: OA_GetOntologyResponse

«DataType» Ontology Access Serv ice Types:: OA_ParseOntologyResponse

+ + + +

1 + + +

Deleted: Boolean

«DataType» Ontology Access Serv ice Types: :OA_ParseOntologyRequest name: CharacterString Ontology: OA_Ontology [0..1] Query: OA_Query [0..1] Format: CharacterString [0..1]

«DataType» Ontology Access Serv ice Types::OA_Ontology

«DataType» Ontology Access Serv ice Types:: OA_GetABoxStatementsResponse +


33/33





Specification of the Schema Mapping Service

Revision

1/28

[1.1 / 2.2.2]

Specification of the Schema Mapping Service – Document Control Page


Specification of the Schema Mapping Service

Creator

Lutz, Michael

Subject


Description

This document defines an abstract and platform independent formal interface specification of the Schema Mapping Service.

Publisher


Contributor

Friis-Christensen, Anders

Joint Research Centre – IES

Cao, Hong


Quaglia, Angelo


Joint Research Centre - IES

Date

2007-11-07

Type

Text

Format

application/msword

Identifier


Source

Not applicable

Language

en-GB.

Relation

none

Coverage



D3.4.4


WP3.4


2007-10-31


2007-xx-xx

Audience


Version number

1.2 / 2.2.2

Date

2007-11-07

Modified by

Friis-Christensen, Anders

Comments

adapted to new template

Status


2/28


Specification of the Schema Mapping Service – Document Control Page



3/28

Specification of the Schema Mapping Service – Revision History


Date

Sections changed

Description

0.7 / 2.0

2006-05-15

all

Created a new version of the specification incorporating some of the material from version 0.6 (http://portal.opengeospatial.org/files/?artifact_id=14025)

0.8 / 2.0

2006-07-21

1, 2, 3, 6, 7 (new)

Split up interface into schema mapping and schema mapping repository interfaces; added concat operation; minor editorial edits

0.9 / 2.0.6

2006-08-08

1, 4.1, 4.5.1, 6.2.2, 7.2

Updated to template v2.0.6, included EIG’s comments

1.0 / 2.0.6

2007

1.1 / 2.2.2

2007-10-16

all

Adapted to new template structure; included changes proposed in the implementation specification of the FAS-X (Section 7); renamed concat operation to concatFeatures to be consistent with the naming of the mapFeatures operation (Section 6.2); included references to XMI models in Annex B; moved the intended usage of the interfaces into Annex B (dynamic model); made createMapping and deleteMapping operations of SMR interface optional (in analogy to FAS)

1.2 / 2.2.2

2007-11-07

6.4, 7.4

Changed the description of the capabilities to match the model

4/28

Specification of the Schema Mapping Service – Table of Contents

Table of Contents 1

Foreword .....................................................................................................................................................8

2

Conventions ................................................................................................................................................8

3

2.1

Abbreviations .......................................................................................................................................8

2.2


2.3

UML Notation .......................................................................................................................................8

2.4

Conformance........................................................................................................................................8

2.4.1


2.4.2



3.1.1

The Schema Mapping Interface....................................................................................................9

3.1.2

The Schema Mapping Repository Interface .................................................................................9

3.2 4

5

6

Role and Scope of the Schema Mapping Service ...............................................................................9

Service Specification Summary ...........................................................................................................9

Context of the Schema Mapping Service................................................................................................. 10 4.1


4.2


4.3


4.4

Relations to other ORCHESTRA Service Specifications.................................................................. 11

Requirements ........................................................................................................................................... 11 5.1

Security Requirements...................................................................................................................... 11

5.2

Reliability Requirements ................................................................................................................... 11

Specification of the Schema Mapping Interface....................................................................................... 12 6.1

Specification of an OAS Profile of Parameter Types used by the Schema Mapping Interface ........ 12

6.2


6.2.1

Specification of the mapFeatures Operation ............................................................................. 13

6.2.2

Specification of the concatFeatures Operation.......................................................................... 14

6.3


6.3.1 6.4 7

OA_FeatureCollectionSequence ............................................................................................... 15

Specification of the Service specific Capabilities.............................................................................. 16

Specification of the Schema Mapping Repository Interface .................................................................... 16 7.1

Specification of an OAS Profile of Parameter Types used by the Schema Mapping Repository

5/28

Specification of the Schema Mapping Service – Table of Contents Interface ....................................................................................................................................................... 17 7.2


7.2.1

Specification of the getMapping Operation................................................................................ 18

7.2.2

Specification of the createMapping Operation........................................................................... 19

7.2.3

Specification of the deleteMapping Operation........................................................................... 20

7.2.4

Specification of the setMapping Operation................................................................................ 21

7.3


7.3.1

OA_MappingDescCollection...................................................................................................... 22

7.3.2

OA_MappingDescriptor & OA_UniqueID................................................................................... 22

7.3.3

OA_SchemaMappingLanguage................................................................................................. 22

7.4

Specification of the Service specific Capabilities.............................................................................. 22

8

Known Issues and Limitations.................................................................................................................. 23

9

References ............................................................................................................................................... 23

10 Appendix A: Abstract Test Suite (normative) ........................................................................................... 25 11 Appendix B: UML Models (normative) ..................................................................................................... 26 11.1

XMI Model ..................................................................................................................................... 26

11.2

Dynamic Model.............................................................................................................................. 26

6/28

Specification of the Schema Mapping Service – Tables and Diagrams

Tables Table 1: Summary of additional Service Operations ....................................................................................... 12 Table 2: Referenced OA Types ....................................................................................................................... 13 Table 3: Sections of the service specific capabilities ...................................................................................... 16 Table 4: Attributes of the service specific capabilities of section SupportedSchemaMappingLanguages...... 16 Table 5: Summary of additional Service Operations ....................................................................................... 17 Table 6: Referenced OA Types ....................................................................................................................... 18 Table 7: Specification of the createMapping Operation .................................................................................. 20 Table 8: Sections of the service specific capabilities ...................................................................................... 23 Table 9: Attributes of the service specific capabilities of section RegisteredMappings .................................. 23 Table 10: Attributes of the service specific capabilities of section SupportedSchemaMappingLanguages.... 23 Table 11: Attributes of the service specific capabilities of section SupportedQueryLanguages............... Error! Bookmark not defined.

Diagrams Diagram 1: Class Diagram of the two interfaces of the Schema Mapping Service......................................... 10 Diagram 2: Class Diagram of the Schema Mapping Interface ........................................................................ 12 Diagram 3: Class diagram for the OA types used in the Schema Mapping and Schema Mapping Repository interfaces .................................................................................................................................................. 15 Diagram 4: Class Diagram of the Schema MappingRepository Interface....................................................... 16

7/28

Specification of the Schema Mapping Service – Foreword

1

Foreword This document is an abstract specification of the Schema Mapping service and is based on the Template for the abstract Specification of ORCHESTRA Services version 2.2. It replaces the specification version 1.0. The update of all chapters was required to adapt the specification to the new template. Also, chapter 7 was updated to accommodate the changes proposed in the implementation specification of the Translating Feature Access Service (FAS-X), which implements the Schema Mapping Repository Interface. Note: In version 0.7, the editorship was transferred to JRC-IES. This has involved a complete revision of the specification. As at the same time, the specification had to be adapted to the new template, a new specification document was created from scratch for this version (rather than adapting the previous version 0.6). This document includes two annexes: Appendix A: Abstract Test Suite (normative) is mandatory and Appendix B: UML Models (normative) is optional.

2

Conventions

2.1


2.2

•

CSL

Conceptual Schema Language

•

FAS-X

Translating Feature Access Service

•

WFS

Web Feature Service


2.3


2.4 2.4.1


8/28

Specification of the Schema Mapping Service – Overview and Architecture Outline 2.4.2


3


3.1

Role and Scope of the Schema Mapping Service The Schema Mapping Service provides functionality that is related to the mapping of features from a source into a target schema. It provides this functionality through two interfaces which are introduced in the following subchapters. For the possible usage and combination of these interfaces, see Annex B (Section 10.2).

3.1.1

The Schema Mapping Interface The main (and hence mandatory) functionality of this interface is to execute a schema mapping. We consider a schema mapping to be “the definition of an automated transformation of each instance of a data structure A into an instance of a data structure B that preserves the intended meaning of the original information” (Doerr, 2004, our emphasis). This is the main difference to the Processing Service, which also transforms data from one schema to another one, but usually changes the semantics of the information. Note: The preservation of the intended meaning has ultimately to be judged by the application domain expert. The service takes a feature collection and a description of the mapping from the source to the target schema as input and returns the features in the target schema. A schema mapping is described by •

an identifier that is unique to the Schema Mapping Service instance;

•

descriptions of the source and target feature types;

•

the schema mapping language used to describe the mapping; and

•

a reference to the actual mapping.

The Schema Mapping Service can be used to (1) directly map from one application schema to another one, or (2) to map from an application schema to a common (or community) schema (or vice versa). The latter can be used to perform an indirect mapping between two application schemas through the community schema. The mapping of features might also require that several feature collections are combined. In order to support this, an (optional) concatenation operation is also included in the interface. The description of the schema mapping is required as an input. It is outside the scope of the Schema Mapping Service to automatically derive a mapping between two application schemas. 3.1.2

The Schema Mapping Repository Interface This interface supports repository functionality for mappings between source and target feature types. For this, operations for the creation (registration), retrieval, updating and deletion of schema mapping descriptions are foreseen.

3.2

Service Specification Summary This service type specification of the Schema Mapping Service is comprised of the following interfaces

9/28

Specification of the Schema Mapping Service – Context of the Schema Mapping Service that are defined in separate interface type specifications: •


The following interfaces are specified as integral part of this service in chapter 6 and 7: •

The Schema Mapping Interface Type

•

The Schema Mapping Repository Interface Type

class Schema Mapping «interface» SchemaMapping + +

concatFeatures(fc :OA_FeatureCollectionSequence) : OA_FeatureCollection mapFeatures(fc :OA_FeatureCollection, m :OA_MappingDescriptor) : OA_FeatureCollection

class Schema Mapping Repository «interface» SchemaMappingRepository + + + +

createMapping(source :OA_FeatureDescriptor, target :OA_FeatureDescriptor, lang :OA_SchemaMappingLanguage, mapping :OA_URI) : OA_MappingDescriptor deleteMapping(q :OA_Query) : void getMapping(q :OA_Query) : OA_MappingDescCollection setMapping(id :OA_UniqueID, m :OA_MappingDescriptor) : void

Diagram 1: Class Diagram of the two interfaces of the Schema Mapping Service

4 4.1

Context of the Schema Mapping Service Relations to Standards As the Schema Mapping Service maps data from one schema to another it is related to existing standard conceptual schema languages, e.g. •

The Unified Modeling Language (UML), see the UML 2.0 specification at http://www.uml.org/

•

XML Schema, see XML 1.0 specifications at http://www.w3.org/TR/xmlschema-1/ (Structures) and http://www.w3.org/TR/xmlschema-2/ (Datatypes)

•

The Web Ontology Language http://www.w3.org/2004/OWL/

•

The RDF (Resource Description Framework) Vocabulary Description Language 1.0: RDF Schema (RDFS), see the RDFS 1.0 W3C Recommendation at http://www.w3.org/TR/rdfschema/

(OWL),

see

the

W3C

Recommendation

at

The mappings used by the specification are specified using a schema mapping language. Relevant standards in this area are: •

XSL Transformations (XSLT), http://www.w3.org/TR/xslt/

•

XML Query (XQuery) and the XML selection and an expression language (XPath), see the XQuery 1.0 and XPath 2.0 W3C Candidate Recommendations at http://www.w3.org/XML/Query/

see

the

XSLT

10/28

1.0

W3C

Recommendation

at

Specification of the Schema Mapping Service – Requirements •

4.2

The SPARQL Query Language for RDF (SPARQL), see the W3C Candidate Recommendation at http://www.w3.org/TR/rdf-sparql-query/

Relations to ORCHESTRA Application Schemas The Schema Mapping Service specification uses Basic and OA Types that are defined in the package OAS/Basic Types, OAS/OA Types and OAS-MI/OA-MI Types of the Information Viewpoint. The OA Basic Service specification defines new parameter types. These parameter types are defined the in the package OAS/OA Types of the Information Viewpoint. Exception types are defined in the package OA Types/Exception Types of the Information Viewpoint.

4.3

Relations to ongoing Initiatives and related Projects The Schema Mapping Service has no immediate relation to ongoing projects.

4.4

Relations to other ORCHESTRA Service Specifications The Schema Mapping Service is related to the Feature Access Service, which will usually provide the features to be mapped to the target schema. Both services could be combined in a complex service that acts as a “translating” FAS (cf. translating WFS (Woodsford 2005)), i.e. a service that provides features in the schema given by the requester. Such a service should also provide a mapping of the FAS query from the target (requester) schema to the source (data) schema. Whether or how such a mapping could be supported by the Schema Mapping Service, is an open research issue. A FAS could also be used to implement the “mapping registry” functionality (create, get, set, delete mapping) of the Schema Mapping Service. The mapping rules between source and target schemas required for transforming a feature collection have to be provided by the requester. These mapping rules could be semi-automatically created using information on the semantics of data sources. For this task, the Ontology and Inference Services could be used.

5 5.1

Requirements Security Requirements The Schema Mapping Service has no requirements beyond the scope of the Authentication and Authorization Service.

5.2

Reliability Requirements The Schema Mapping Service has no special reliability requirements.

11/28

Specification of the Schema Mapping Service – Specification of the Schema Mapping Interface

6

Specification of the Schema Mapping Interface class Schema Mapping «interface» SchemaMapping + +

concatFeatures(fc :OA_FeatureCollectionSequence) : OA_FeatureCollection mapFeatures(fc :OA_FeatureCollection, m :OA_MappingDescriptor) : OA_FeatureCollection

Diagram 2: Class Diagram of the Schema Mapping Interface The Schema Mapping interface defines the following operations:

Operation Name

Description

mapFeatures

maps a feature collection to a target schema

concatFeatures

concatenates several feature collections Table 1: Summary of additional Service Operations

6.1

Specification of an OAS Profile of Parameter Types used by the Schema Mapping Interface The following non basic types are used within this specification:

Name OA_FeatureCollectionSequence

Usage I

from OAS

New

Schema Mapping Interface Types

Yes


I&O

Feature Access Service Types

No


I


No

OA_MappingDescriptor

I

Schema Mapping Repository Interface Types

No

OA_SchemaMappingLanguage

I


No

OA_UniqueID

I


No

OA_URI

I

OA Basic Service Types

No


E

OA Basic Service Exceptions

No


E


No

12/28


OA_NoApplicableCode

E


No

OA_InternalError

E


No

OA_FeaturesIncompatibleWithSchema

E

Schema Mapping Interface Type Exceptions

Yes


6.2


6.2.1

Specification of the mapFeatures Operation The mandatory mapFeatures operation maps a given feature collection into a target schema using the given mapping. The signatures of the operation is OA_FeatureCollection mapFeatures (fc: OA_FeaureCollection, m: OA_MappingDescriptor) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_FeaturesIncompatibleWithSchema

Overrides

not applicable

Preconditions

The feature type of the given feature collection must be the source feature type of the given mapping.

Post conditions

None

Use

Mandatory

Receives

Returns

Name

Type

Description

fc

OA_FeaureCollection

mandatory

The feature collection containing the features that are to be mapped.

m


mandatory

A mapping descriptor that defines the mapping to the target schema

Type

Description The feature collection mapped into the target feature type.

OA_FeatureCollection Throws

Use

Type



13/28


6.2.2



OA_NoApplicableCode


OA_InternalError


OA_FeaturesIncompatibleWithSchema

The features of the feature collection are not consistent with the schema of the source feature descriptor

Specification of the concatFeatures Operation The optional concatFeatures operation concatenates the given feature collections. It can be used in cases where several feature collections have to be mapped into a common schema and the result should be a single feature collection. For example, national data on forest fires from European Union Member States have to be mapped to a common European schema and combined into a single feature collection for further analysis or reporting. The signatures of the operation is OA_FeatureCollection concatFeatures (fc: OA_FeatureCollectionSequence) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError

Overrides

not applicable

Preconditions

None

Post conditions

None

Use

Optional

Receives

Name fc

Returns

Type

Use

OA_FeatureCollectionSequence Type

The feature collections that are to be concatenated. Description

One feature collection containing all features that were part of the input feature collections.

OA_FeatureCollection Throws

mandatory

Description

Type

Cause





14/28


6.3

OA_NoApplicableCode


OA_InternalError


Specification of Parameter Types This interface specification defines one new OA Type. This new OA Type will become part of the OAS “Schema Mapping Interface Types”. Diagram 3 shows all types used in the Schema Mapping and Schema Mapping Repository interfaces as well as the relationships between them. The type OA_MappingDescriptor and all associated types are described in Section 7.3. This interface specification does not define any new OT Types. This interface specification does not introduce any new non-orchestra Types.

class Schema Mapping Service Types «type» OA_MappingDescCollection +

«type» OA_UniqueID

mappingDesc: OA_MappingDescriptor [1..*]

«type» OA_FeatureCollectionSequence -

«use»

+id

fc: OA_FeatureCollection [2..*]

1 «use»

«type» OA_MappingDescriptor +

«type» OA_FeatureCollection

mapping: OA_URI +schemaMappingLanguage

1

«CodeList» OA_SchemaMappingLanguage +source

1

1

+target

«use»

«type» OA_FeatureDescriptor # #

+ + +

SPARQL: XQuery: XSLT:

description: CharacterString name: CharacterString «type,DataType» OA_URI

1

+ +

1 «type» OA_SchemaDescriptor + + + +

«type» OA_Query Language: OA_QueryLanguage Query: CharacterString

«use»

encoding: OA_Encoding purpose: CharacterString schemaName: CharacterString SchemaReference: OA_URI

Diagram 3: Class diagram for the OA types used in the Schema Mapping and Schema Mapping Repository interfaces 6.3.1

OA_FeatureCollectionSequence The OA_FeatureCollectionSequence type is a collection of two or more OA_FeatureCollection ele-

15/28

Specification of the Schema Mapping Service – Specification of the Schema Mapping Repository Interface ments.

6.4

Specification of the Service specific Capabilities As part of ORCHESTRA D3.3.2 a meta-information schema for services is defined acting as a default OAS-MI for service capabilities. OA_MI_CapabilitiesDocument includes both the common capabilities and the service specific capabilities. While the common capabilities are defined in the specification of the Service Capabilities Interface, the specific capabilities have to be specialized in each service specification. The schema for service specific capabilities defined here is provided in the following schema section:

Section Name

Section Contents

OA_MI_SM_Capabilities

The capabilities for the schema mapping interface.

Table 3: Sections of the service specific capabilities Definition

Data Type


The schema mapping languages that are supported by the service i.e. that can be used in schema mapping descriptor used by the mapFeatures operation


1..* / mandatory

Name

SupportedSchemaMappingLanguage

Table 4: Attributes of the service specific capabilities of section SupportedSchemaMappingLanguages

7

Specification of the Schema Mapping Repository Interface

class Schema Mapping Repository «interface» SchemaMappingRepository + + + +

createMapping(source :OA_FeatureDescriptor, target :OA_FeatureDescriptor, lang :OA_SchemaMappingLanguage, mapping :OA_URI) : OA_MappingDescriptor deleteMapping(q :OA_Query) : void getMapping(q :OA_Query) : OA_MappingDescCollection setMapping(id :OA_UniqueID, m :OA_MappingDescriptor) : void

Diagram 4: Class Diagram of the Schema MappingRepository Interface The Schema Mapping Repository interface defines the following operations:

Operation Name

Description

getMapping

returns a (list of) mapping(s) matching a given query

createMapping

creates and registers a new mapping

16/28

Specification of the Schema Mapping Service – Specification of the Schema Mapping Repository Interface

deleteMapping

deletes all mapping matching a given query

setMapping

updates a specific mapping Table 5: Summary of additional Service Operations

7.1

Specification of an OAS Profile of Parameter Types used by the Schema Mapping Repository Interface The following non basic types are used within this specification:

Name

Usage

from OAS


I


Yes


O


Yes

OA_MappingDescCollection

O


Yes

OA_UniqueID

I


Yes


I


No

OA_URI

I


No

OA_Query

I


No


E


No


E


No

OA_NoApplicableCode

E


No

OA_InternalError

E


No

OA_IllegalQuery

E

OA Feature Access Service Exceptions

No

OA_MappingDoesNotExist

E

Schema Mapping Repository Interface Exceptions

Yes

OA_MappingDuplication

E


Yes

OA_TargetFeatureDescNotFound

E


Yes

OA_SourceFeatureDescNotFound

E


Yes

17/28

New

Specification of the Schema Mapping Service – Specification of the Schema Mapping Repository Interface Table 6: Referenced OA Types

7.2


7.2.1

Specification of the getMapping Operation The mandatory getMapping operation returns all mappings registered with this service instance that are identified by the given query. Example queries include but are not limited to: •

all mappings that map one or several source to one or several target feature type(s);

•

a specific mapping identified by its ID;

•

all mappings that use map from or to a feature type specified in a specific CSL;

•

all mappings that use a specific schema mapping language.

If the query does not match any mappings an empty collection is returned. The signatures of the operation is OA_MappingDescCollection getMapping (query: OA_Query) throws OA_InvalidParameterValue, OA_NoApplicableCode, OA_InternalError, OA_IllegalQuery

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

mandatory

Receives

Name query

Returns

Type

Use

OA_Query

mandatory

Type

A query that identifies the mappings to be returned. Description

A collection of mapping descriptions containing meta information (name etc) as well as the mapping between the feature types.

OA_MappingDescCollection

Throws

Description

Type

Cause





18/28


7.2.2

OA_NoApplicableCode


OA_InternalError


OA_IllegalQuery

Operation request does not contain a valid query.

Specification of the createMapping Operation The optional createMapping operation creates and registers a mapping between a source and target feature type with this service instance. The signatures of the operation is OA_MappingDescriptor createMapping (source:OA_FeatureDescriptor, target: OA_FeatureDescriptor, lang: OA_SchemaMappingLanguage, mapping: OA_ResourceLocator) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_MappingDuplication, OA_TargetFeatureDescNotFound, OA_SourceFeatureDescNotFound

Overrides

not applicable

Preconditions

None

Post conditions

The given mapping has been registered with the service instance.

Use

optional

Receives

Returns

Name

Type

Description

source


mandatory

Description of the source feature type for the mapping

target


mandatory

Description of the target feature type for the mapping

lang


mandatory

The schema mapping language used

mapping

OA_ResourceLocator

mandatory

A reference to the mapping

Type

Description The operation returns the complete mapping descriptor (including its ID) that has been registered with the service


Throws

Use

Type



19/28




OA_NoApplicableCode


OA_InternalError


OA_MappingDuplication

The mapping descriptor of the input source and target feature descriptor has been created previously.

OA_TargetFeatureDescNotFound

The input source feature descriptor has not been created.

OA_SourceFeatureDescNotFound

The input target feature descriptor has not been created.

Table 7: Specification of the createMapping Operation 7.2.3

Specification of the deleteMapping Operation The optional deleteMapping operation deletes all mappings registered with this service that are identified by the given query. The signatures of the operation is void getMapping (query: OA_Query) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_IllegalQuery

Overrides

not applicable

Preconditions

none

Post conditions

The mappings matching the query have been deleted.

Use

optional

Receives

Name query

Returns

Type

Use

OA_Query

mandatory

Description A query that identifies the mappings to be returned.

Type

Description

Type

Cause

void Throws



20/28


7.2.4



OA_NoApplicableCode


OA_InternalError


OA_IllegalQuery

Operation request does not contain a valid query.

Specification of the setMapping Operation The optional setMapping operation updates a specific mapping identified by its ID. Note. We cannot envision a situation in which multiple mappings would be updated (to the same mapping) at the same time. Thus, this operation does not allow using general queries to identify the mappings to be updated (as does the getMapping operation). The signatures of the operation is void setMapping (id: OA_UniqueID, mapping: OA_MappingDescriptor) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_MappingDoesNotExist

Overrides

not applicable

Preconditions

The given mapping is registered with the service.

Post conditions

The identified mapping has been updated.

Use

optional

Receives

Name

Type

Use

Description

id

OA_UniqueID

mandatory

The ID of the mapping to be updated.

mapping


mandatory

A mapping descriptor that defines the updated mapping

Returns

Type

Description

Type

Cause

void Throws





21/28


OA_NoApplicableCode


OA_InternalError


OA_MappingDoesNotExist

7.3

No mapping with the given ID is registered with the service.

Specification of Parameter Types This interface specification defines four new OA Types. These new OA Types will become part of the OAS “Schema Mapping Repository Interface Types”. Diagram 3 shows all types used in the Schema Mapping and Schema Mapping Repository interfaces as well as the relationships between them. This interface specification does not define any new OT Types. This interface specification does not introduce any new non-orchestra Types.

7.3.1

OA_MappingDescCollection The OA_MappingDescCollection type is a collection of one or more OA_MappingDescriptor elements.

7.3.2

OA_MappingDescriptor & OA_UniqueID The OA_MappingDescriptor type contains the following information about a specific schema mapping:

7.3.3

•

id – an identifier that is unique within the scope of a schema mapping instance (OA_UniqueID).

•

source – an OA_FeatureDescriptor describing the source feature type of the mapping.

•

target – an OA_FeatureDescriptor describing the target feature type of the mapping.

•

mapping – a reference to the actual mapping

•

mapping_language – a value from the OA_SchemaMappingLanguage code list.

OA_SchemaMappingLanguage The OA_SchemaMappingLanguage type provides a code list of schema mapping languages that can be used to specify schema mappings.

7.4

Specification of the Service specific Capabilities As part of ORCHESTRA D3.3.2 a meta-information schema for services is defined acting as a default OAS-MI for service capabilities. OA_MI_CapabilitiesDocument includes both the common capabilities and the service specific capabilities. While the common capabilities are defined in the specification of the Service Capabilities Interface, the specific capabilities have to be specialized in each service specification. The schema for service specific capabilities defined here is provided in the following schema section:

22/28

Specification of the Schema Mapping Service – Known Issues and Limitations

Section Name

Section Contents The service specific capabilities for the schema mapping repository.

OA_MI_SMR_Capabilities

Table 8: Sections of the service specific capabilities Definition

Data Type


SupportedSchemaMappingLanguage

A list of schema mapping languages that are supported by the service.


1..* / mandatory

QueryLanguage

A list of query languages that are supported by the service.

OA_QueryLanguage

1..* / mandatory

Mappings

A list of the mappings (and the source and target feature types) that are registered with the service.

OA_RegisteredMappings

0..* / mandatory

Name

Table 9: Attributes of the service specific capabilities of section OA_MI_SMR_Capabilities Name

Definition

Data Type


source

the name of the source feature type

CharacterString

1 / mandatory

target

the name of the target feature type

CharacterString

1 / mandatory

SchemaMappingLanguage

the schema language


1 / mandatory

Table 10: Attributes of the type OA_RegisteredMappings The rationale behind providing a list of mappings registered with the service in the capabilities is to provide a requester with an easy means to discover whether or not the service offers mappings for a specific source or target feature type.

8


9

References Doerr, Martin (2004): Semantic interoperability: Theoretical Considerations. Technical Report 345, Institute of Computer Science, Foundation for Research and Technology, Crete, Greece, October 2004.

23/28

Specification of the Schema Mapping Service – References Woodsford, Peter A. (2005): NMCA’s and the Internet II – eDelivery and Feature Serving: Report on Joint EuroSDR/EuroGeographics Workshop, Presentation at 11th EC-GI & GIS Workshop, ESDI: Setting the Framework, Alghero, Sardinia, 29th June - 1st July 2005. Available from: http://www.ecgis.org/Workshops/11ec-gis/presentations/19woodsford.pdf

24/28

Specification of the Schema Mapping Service – Appendix A: Abstract Test Suite (normative)

Appendix A: Abstract Test Suite (normative) When creating an implementation specification of the Schema Mapping Service, the “Rules for Implementation Specifications of ORCHESTRA Services” defined in chapter 9.2.2.3 and the “Rules for the Service Mapping to a given Platform” of the RM-OA shall be obeyed. In addition, the following tests shall be performed to ensure conformance of an implementation specification to the platform-independent specification of the Schema Mapping Service: 1. Syntactical Conformance •


•


•


•




Additional conformance checks that are specifically to the Schema Mapping Service are not required.

25/28

Specification of the Schema Mapping Service – Appendix B: UML Models (normative)

10 Appendix B: UML Models (normative) 10.1 XMI Model The XMI Models of this service specification can be downloaded from the OGC Portal under the following URL: http://portal.opengeospatial.org/index.php?m=projects&a=view&project_id=140&tab=2&artifact_id=22239

The XMI Model contains only the parameters specified in this service specification. Additional parameters used by this service can be found in the XMI Models of the following interface or service specifications: •


•

The Feature Access Service Type

•

The OA Basic Service Type

10.2 Dynamic Model The interfaces described in this specification can be used in service implementations in different ways: •

A service that only implements the schema mapping interface can be used to map feature collections in arbitrary schemas to a target schema using a mapping description that is provided by the requester (Figure 1). In this scenario the schema mapping (service) is loosely coupled to the service providing the input feature collections (e.g. a FAS or a processing service). The performance is expected to be low for large feature collections.

Figure 1: Loosely coupled approach to schema mapping using only the Schema Mapping interface. •

A service that implements both interfaces can be used in the same way. In this scenario, the requester does not necessarily have to provide the mapping description himself. Rather, he can query the schema mapping service for an appropriate mapping description that can be used for the given source and target schemas (Figure 2).

26/28


1. GetFeature(query to sourceFT)

Client

FAS

FAS

fc1: FeatureCollection

4. mapFeature(fc1, md) md: MappingDescriptor fc2: FeatureCollection 2. getMapping(query)

SMS

Schema Mapping Schema Mapping Repository

3. retrieveMapping() [internal] md: MappingDescriptor

Mapping Store

Figure 2: Loosely coupled approach to schema mapping using both the Schema Mapping and the Schema Mapping Repository interfaces. •

A service that implements the schema mapping repository interface and another interface for creating or accessing feature collections (e.g. the FAS) can be used to provide the output feature collections in different schemas (Figure 3). The user can use the operations of the schema mapping repository interface to create new mappings and/or query for the available mappings. Furthermore, the service should specify all available target schemas in its capabilities. In this scenario, the schema mapping is tightly coupled to the service providing the input feature collections and transparent to the requester. The resulting service type is a Translating Feature Access Service (FAS-X). This approach is expected to be more performant (but less flexible) than the loosely coupled one.

27/28


Figure 3: Tightly coupled approach to schema mapping.

28/28




Specification of the Sensor Access Service

Revision

1/45

[0.8 / 2.2.1]

Specification of the Sensor Access Service – Document Control Page


Specification of the Sensor Access Service

Creator

Ecker Severin

Subject


Description

This document defines an abstract and platform independent formal specification of the Sensor Access Service.

Publisher


Contributor

Ecker Severin

Austrian Research Centers GmbH

Duennebeil Gerhard


Kutschera Peter


Havlik Denis


Schimak Gerald


Anders Friis-Christensen

JRC-IES

Michael Lutz

JRC-IES


Date

2007-09-26

Type

Text

Format

application/msword

Identifier


Source

Not applicable

Language

en-GB.

Relation

none

Coverage



D3.4.3


WP3.4


2007-xx-xx


2007-xx-xx

Audience


Version number

0.8 / 2.2.1

Date

2007-09-26

Modified by

Ecker Severin


2/45

Specification of the Sensor Access Service – Document Control Page

Comments Status


Action requested


3/45

Specification of the Sensor Access Service – Revision History


Date

Sections changed

Description

0.1 / 1.6

2005-12-06

all

Complete revision of the spec & update to template version 1.6

0.2 / 2.0.3

2006-05-17

all

Incorporated comments by JRC and update to template version 2.0.3

0.3 / 2.0.4

2006-05-31

all

Updated to template version 2.0.4

0.4 / 2.0.4

2006-07-25

All

Incorporated comments by JRC

0.5 / 2.0.4

2006-08-01

All

Incorporated comments by Michael Lutz

0.6 / 2.0.4

2006-09-11

7

Incorporated further comments by Michael Lutz

0.7 / 2.0.4

2007-01-17

All

Removed SAS acronym

0.8 / 2.2.1

2007-09-26

all

Updated to new template version

4/45

Specification of the Sensor Access Service – Table of Contents

Table of Contents 1

Foreword..................................................................................................................................................... 9

2

Conventions .............................................................................................................................................. 10

3

2.1

Abbreviations ..................................................................................................................................... 10

2.2


2.3

UML Notation..................................................................................................................................... 10

2.4

Conformance ..................................................................................................................................... 10

2.4.1


2.4.2



Role and Scope of the Sensor Access Service................................................................................. 11

3.1.1 3.2 4

5

6

Usage Examples for the Sensor Access Service....................................................................... 12


Context of the Sensor Access Service ..................................................................................................... 15 4.1


4.2


4.3


4.4


Requirements ........................................................................................................................................... 16 5.1


5.2


Specification of the Sensor Data Interface ............................................................................................... 17 6.1

Specification of an OAS Profile of Parameter Types used by the Sensor Data Interface ................ 17

6.2


6.2.1

Specification of the getSensor Operation................................................................................... 19

6.2.2

Specification of the getSensorData Operation ........................................................................... 20

6.2.3

Specification of the getSensorDataTypes Operation ................................................................. 21

6.3


6.3.1

OA_SensorCache ...................................................................................................................... 22

6.3.2

OA_SensorID ............................................................................................................................. 22

6.3.3

OA_SensorDescriptor ................................................................................................................ 22

6.3.4

OA_SensorDataDescriptor......................................................................................................... 23

6.3.5

OA_SensorData ......................................................................................................................... 23

5/45

Specification of the Sensor Access Service – Table of Contents

7

6.3.6

OA_SensorStatus....................................................................................................................... 24

6.3.7

OA_SensorConfiguration ........................................................................................................... 24

6.3.8

OA_InvalidSensorID................................................................................................................... 25

6.3.9

OA_InvalidConfiguration ............................................................................................................ 25

Specification of the Sensor Administration Interface................................................................................ 26 7.1

Specification of an OAS Profile of Parameter Types used by the Sensor Administration Interface . 26

7.2


7.2.1

Specification of the addSensorDescription Operation ............................................................... 28

7.2.2

Specification of the updateSensorDescription Operation .......................................................... 28

7.2.3

Specification of the removeSensorDescription Operation ......................................................... 29

7.2.4

Specification of the setSensorData Operation ........................................................................... 30

7.2.5

Specification of the getConfigurationSchema Operation ........................................................... 32

7.2.6

Specification of the getSensorConfiguration Operation ............................................................. 32

7.2.7

Specification of the setSensorConfiguration Operation ............................................................. 33

7.3 8

Specification of the Sensor Configuration Interface ................................................................................. 36 8.1

Specification of an OAS Profile of Parameter Types used by the Sensor Configuration Interface... 36

8.2


8.2.1


8.2.2

Specification of the getSensorConfiguration Operation ............................................................. 39

8.2.3

Specification of the setSensorConfiguration Operation ............................................................. 39

8.3 9



Specification of the Service specific Capabilities...................................................................................... 41

10 Known Issues and Limitations .................................................................................................................. 43 11 Appendix A: Abstract Test Suite (normative)............................................................................................ 44 12 Appendix B: UML Models (normative) ...................................................................................................... 45 12.1

XMI Model ...................................................................................................................................... 45

6/45

Specification of the Sensor Access Service – Tables and Diagrams

Tables Table 1: Summary of operations...................................................................................................................... 17 Table 2: Referenced OA Types ....................................................................................................................... 18 Table 3: Specification of the getSensorDescription Operation ........................................................................ 20 Table 4: Specification of the getSensorData Operation .................................................................................. 20 Table 5: Specification of the getSensorData Operation .................................................................................. 21 Table 6: Summary of operations...................................................................................................................... 26 Table 7: Referenced OA Types ....................................................................................................................... 27 Table 8: Specification of the addSensorDescription Operation ....................................................................... 28 Table 9: Specification of the updateSensorDescription Operation .................................................................. 29 Table 10: Specification of the removeSensorDescription Operation ............................................................... 30 Table 11: Specification of the setSensorData Operation................................................................................. 31 Table 12: Specification of the getConfigurationSchema Operation................................................................. 32 Table 13: Specification of the getSensorConfiguration Operation................................................................... 33 Table 14: Specification of the setSensorConfiguration Operation................................................................... 34 Table 15: Summary of operations.................................................................................................................... 36 Table 16: Referenced OA Types ..................................................................................................................... 37 Table 15: Specification of the getConfigurationSchema Operation................................................................. 38 Table 16: Specification of the getSensorConfiguration Operation................................................................... 39 Table 17: Specification of the setSensorConfiguration Operation................................................................... 40 Table 22: Sections of the service specific capabilities..................................................................................... 41 Table 23: Attributes of the service specific capabilities of section SASCapabilities........................................ 42

Diagrams Diagram 1: Class Diagram of the Sensor Access Service .............................................................................. 14 Diagram 2: Class Diagram of the Sensor Data Interface................................................................................. 17 Diagram 3: Class diagram of OA_SensorCache ............................................................................................. 22 Diagram 4: Class diagram of OA_SensorID .................................................................................................... 22 Diagram 5: Class diagram of OA_SensorDescriptor ....................................................................................... 23 Diagram 6: Class diagram of OA_SensorDataDescriptor ............................................................................... 23 Diagram 7: Class diagram of OA_SensorData ................................................................................................ 24 Diagram 8: Class Diagram of OA_SensorStatus............................................................................................. 24 Diagram 9: Class diagram of OA_SensorConfiguration .................................................................................. 25 Diagram 10: Class diagram of OA_InvalidSensorID........................................................................................ 25 Diagram 11: Class diagram of OA_InvalidConfiguration ................................................................................. 25

7/45

Specification of the Sensor Access Service – Tables and Diagrams Diagram 12: Class Diagram of the Sensor Administration Interface ............................................................... 26 Diagram 13: Class Diagram of the Sensor Configuration Interface................................................................. 36

8/45

Specification of the Sensor Access Service – Foreword

1

Foreword This document is an abstract specification of the Sensor Access service and is based on the Template for the abstract Specification of ORCHESTRA Service Types version 2.2.1. This document includes two annexes: Appendix A: Abstract Test Suite (normative) is mandatory and Appendix B: UML Models (normative) is optional.

9/45

Specification of the Sensor Access Service – Conventions

2

Conventions

2.1

Abbreviations •

2.2

The abbreviations used in this document are defined in chapter 3.1 of the Reference Model for the ORCHESTRA Architecture Version 2.0 (RM-OA).

Terms and definitions Terms and definitions necessary for understanding this document are defined in chapter 3.2 of the RMOA Glossary and in chapter 2.2 of the referenced interface type specifications, except for the following terms:

2.3

•

Data/value publishing: Making the measurement data of a sensor retrievable through the getSensorData operation. This can either happen implicitly if the SensorAccessService is wrapping a sensor/repository or explicitly through an invocation of setSensorData.

•

Data/value retrieval: retrieving data from the SensorAccessService through an invocation of the getSensorData operation.


2.4 2.4.1


2.4.2


10/45

Specification of the Sensor Access Service – Overview and Architecture Outline

3 3.1

Overview and Architecture Outline Role and Scope of the Sensor Access Service This service provides a basic interface for accessing sensor data (observations/measurements), configuring a sensor and administration of sensors. While the SensorDataInterface is mandatory, both the SensorConfigurationInterface and the SensorAdministrationInterface are optional. A sensor in this specification is a data producing entity. This means that a sensor can be a simple hardware sensor like a thermometer or a barometer, but also an arbitrarily complex ‘virtual’ sensor like a simulation model. This can be used to retrieve measurement data from places where actually no real sensor is situated but only a ‘virtual’ one that interpolates the observations of real sensors around the virtual position (see section 3.1.1 for more detailed examples). The primary use of the Sensor Access Service is to retrieve measured values from a sensor. Such values might be ‘live’ measurements from a simple hardware sensor (e.g.: thermometer, barometer), but also values from a data repository that stores series of measurements. Additional uses of the Sensor Access Service include configuration of services as well as their administration. These features are optional but if implemented they allow the clients to set a configuration for a specific sensor or addition and removal of sensors. Depending on the implemented interfaces the SensorAccessService has two different users •

Clients that want to retrieve sensor data (and possibly configure the sensor)

•

Sensor operators that want to make their sensor data available.

‘Normal’ clients make use of the SensorDataInterface and, if available, the SensorConfigurationInterface. The SensorDataInterface can be used to find sensors that fulfil certain criteria, retrieve measurement values from a specified sensor or values that match a provided query. Some sensors can be configured in certain ways (e.g.: they can be moved to a different measurement location or their accuracy of measurements can be adjusted). The users can configure such sensors by using the operations that are defined in the SensorConfigurationInterface. The second type of users usually use of SensorAdministrationInterface. The operations of this interface can be used in order to add and/or remove sensors from the service and to publish new measurement data for a specified sensor at the service so that other clients can retrieve these values. Of course this does not mean that the service must offer this interface in order to make sensors and their data available. The SensorAccessService can also poll any a sensor and internally handle that communication. This is not exposed in any form at the interface though; therefore this communication will not be further discussed in this specification. Describing entities of a sensor: A sensor basically is described in three layers where each of these layers contains different information. The three layers ordered by their frequency of change of information (more rarely to more frequently) are: •

Description of the Sensor

•

Description of the Sensor Configuration

•

Description of the Sensor Status

The sensor description holds ‘static’ information. This is information that is very unlikely to change but if so does very rarely. Example for information that would go into the sensor description are serial and model number of the sensor, its measurement domain (e.g.: temperature, O3), operator and similar information. Information that changes more frequently and that could probably be set by a user of the Sensor Access Service (configure a sensor) will be contained in the sensor configuration. Examples for informa-

11/45

Specification of the Sensor Access Service – Overview and Architecture Outline tion that would be available in the configuration might be the current location (if the sensor is mounted on a movable device) or measurement thresholds (e.g.: a thermometer might only produce new measurement values if the temperature has changed by a certain amount compared to the last measured value). The sensor status reflects the current operating mode and other status information that directly influence the sensor measurement. It usually changes on short notice and might do so without manual intervention. Typical examples are error or warning information; e.g.: “filter blocked”, “Lamp defect”, “test gas applied”. Sensor status information is not required but if it exists for a specific sensor it is coupled with the measurement data. The status cannot be retrieved through the interface on its own but only with its related set of measurement data. Therefore the sensor status can directly give information about the confidence and reliability of a measurement. Obviously it is desirable to let the client formulate queries that only retrieve valid data sets or filter out calibration values (Sometime sensors output values during a calibration run. These values are usually stored in the value repository as well but are marked as calibration values. Since these do not reflect a normal measurement it’s desirable to be able to filter these values when retrieving measurements through the SensorAccessService). While saving the need for the client to filter out unneeded data sets itself it might also considerably reduce network traffic when unneeded data is not transferred. Unlike the sensor description and configuration though, the sensor status itself can only be retrieved from the Sensor Access Service with its associated data set. 3.1.1

Usage Examples for the Sensor Access Service •

Assume a SensorAccessService that implements the SensorDataInterface and has a thermometer as its sensor backend. The client can the find sensor and its observations and retrieve these using the operations of the SensorDataInterface. How the new measurements are integrated into the SensorAccessService is implementation-specific and not in the scope of an interface definition. (whether the sensor pushes the data into the service or the service pulls the data from the sensor does not make any difference at the interface level)

•

A number of sensors are placed in a wide area field. The problem is that a point of particular interest is not measured by one of these sensors since it’s not possible for technical (or any other) reasons to place a sensor there. A calculation model has been implemented that uses the observations of the other sensors and produces ‘observations’ for that particular point of interest. Therefore this model can be seen as ‘virtual sensor’. To be able to publish the observations of this virtual sensor through the SensorAccessService the ‘setSensorData’ operation of the SensorAdministrationInterface can be used. Whenever the model has calculated a new value it pushes that observation to the SensorAccessService through which clients can retrieve it. Of course in order to find such a virtual sensor it must be described and added to the SensorAccessService. This can also be done using the SensorAdministrationInterface and the provided operations.

•

In some situations it might also be needed to configure a sensor. Imagine a sensor that has two modes of operations: a) High precision but only narrow value range b) Low precision but very high value range This configuration can be retrieved and changed by using the operations provided in the SensorConfigurationInterface.

3.2

Service Specification Summary This service type specification of the Sensor Access Service is comprised of the following interfaces that are defined in separate interface type specifications: •


•

The SensorAdministration Interface Type

12/45

Specification of the Sensor Access Service – Overview and Architecture Outline •

The SensorData Interface Interface Type

•

The SensorConfiguration Interface Type

The following interfaces are specified as integral part of this service in chapter 6, 7 and 8: •

The SensorData Interface Type

•

The SensorAdministration Interface Type

•

The SensorConfiguration Interface Type

13/45

Specification of the Sensor Access Service – Overview and Architecture Outline cd Sensor Access Service «Interface» ServiceCapabilities {abstract} +


«interface» SensorAdministrationInterface {abstract} + + + +

addSensorDescription(OA_SensorDescriptor) : OA_SensorID updateSensorDescription(OA_SensorID, OA_SensorDescriptor) : void removeSensorDescription(OA_SensorID) : void setSensorData(OA_SensorID, OA_SensorData) : void

«interface» SensorAccessService {abstract}

«interface» SensorDataInterface {abstract} + + +

getSensor(OA_Query) : Sequenc getSensorData(OA_Query) : Sequence getSensorDataTypes(OA_Query) : Sequence

«interface» SensorConfigurationInterface {abstract} + + +

getConfigurationSchema(OA_SensorID) : OA_SchemaDescriptor getSensorConfiguration(OA_SensorID) : OA_SensorConfiguration setSensorConfiguration(OA_SensorID, OA_SensorConfiguration) : void

Diagram 1: Class Diagram of the Sensor Access Service

14/45

Specification of the Sensor Access Service – Context of the Sensor Access Service

4 4.1

4.2

Context of the Sensor Access Service Relations to Standards •

OGC 06-009r1 – Sensor Observation Service

•

OGC 05-086 - SensorML

Relations to ongoing Initiatives and related Projects The Sensor Access Service does not have any direct relations to other ORCHESTRA Services other than the OA Basic Service.

4.3

Relations to ORCHESTRA Application Schemas The Sensor Data Interface Type Specification that is specified as integral part of this Service Type Specification uses Basic and OA Types that are defined in the package OAS/Basic Types, OAS/OA Types and OAS-MI/OA-MI Types of the Information Viewpoint. The Sensor Administration Interface Type Specification that is specified as integral part of this Service Type Specification uses Basic and OA Types that are defined in the package OAS/Basic Types, OAS/OA Types and OAS-MI/OA-MI Types of the Information Viewpoint. The Sensor Configuration Interface Type Specification that is specified as integral part of this Service Type Specification uses Basic and OA Types that are defined in the package OAS/Basic Types, OAS/OA Types and OAS-MI/OA-MI Types of the Information Viewpoint. The Sensor Data Interface Type Specification that is specified as integral part of this Service Type Specification uses OA-MI Types that are defined in the package OAS-MI/OA-MI Types of the Information Viewpoint. The Sensor Administration Interface Type Specification that is specified as integral part of this Service Type Specification uses OA-MI Types that are defined in the package OAS-MI/OA-MI Types of the Information Viewpoint. The Sensor Configuration Interface Type Specification that is specified as integral part of this Service Type Specification uses OA-MI Types that are defined in the package OAS-MI/OA-MI Types of the Information Viewpoint. The Sensor Data Interface Type Specification that is specified as integral part of this Service Type Specification defines new parameter types. The Sensor Administration Interface Type Specification that is specified as integral part of this Service Type Specification defines new parameter types. The Sensor Configuration Interface Type Specification that is specified as integral part of this Service Type Specification defines new parameter types. These parameter types are defined the in the package OAS/OA Types/Sensor Access Service.

4.4

Relations to other ORCHESTRA Service Specifications The Sensor Access Service does not have any direct relations to other ORCHESTRA Services other than the OA Basic Service.

15/45

Specification of the Sensor Access Service – Requirements

5 5.1

Requirements Security Requirements The Sensor Access Service has no requirements beyond the scope of the Authentication and Authorisation Service.

5.2

Reliability Requirements The Sensor Access Service has no special reliability requirements.

16/45

Specification of the Sensor Access Service – Usage Examples for the Sensor Access Service

6

Specification of the Sensor Data Interface cd Sensor Access Service «interface» SensorDataInterface {abstract} + + +

getSensor(OA_Query) : Sequenc getSensorData(OA_Query) : Sequence getSensorDataTypes(OA_Query) : Sequence

Diagram 2: Class Diagram of the Sensor Data Interface The Sensor Data Interface defines the following operations:

Operation Name

Description

getSensor

Retrieves a list of sensor identifiers of sensors that match the specified query.

getSensorDataTypes

Retrieves the schemas for the specified sensor data or sensor.

getSensorData

Retrieves actual data (real measured or calculated/simulated data) of the specified sensor. Table 1: Summary of operations

6.1

Specification of an OAS Profile of Parameter Types used by the Sensor Data Interface The following non basic types are used within this specification:

Name

Usage

from OAS

New

OA_Query

I

OA Types

No

OA_SensorDescriptor

I/O

OA Types

Ye s

OA_SensorDataDescriptor

O

OA Types

Ye s

OA_SensorData

I/O

OA Types

Ye s


E


No


E


No

17/45

Specification of the Sensor Access Service – Usage Examples for the Sensor Access Service

OA_NoApplicableCode

E


No

OA_InternalError

E


No

OA_InvalidQuery

E


No


18/45

Specification of the Sensor Access Service – Specification of the getSensor Operation

6.2 6.2.1

Specification of the Operations Specification of the getSensor Operation The mandatory getSensorDescription operation lets the client retrieve a description for the specified sensor. A description is a CharacterString whose format applies to a specific defined schema in the specified description language. (An example of such a language would be SensorML). The contents of the OA_SensorDescriptor is used to match the query of the getSensor operation against, it therefore should contain useful and correct information about the sensor. The signatures of the operation is Sequence getSensor ( OA_Query ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_InvalidSensorID, OA_IllegalQuery

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

mandatory

Receives

Name query

Returns

Type

Use

OA_Query

mandatory

Type

Query selecting a number of sensors whose descriptions must be retrieved. Description

Sequence Throws

Description

List of sensor descriptions for the specified sensors.

Type

Cause





OA_NoApplicableCode


OA_InternalError


OA_InvalidSensorID

If the provided sensor identifier is not valid at the service.

OA_IllegalQuery


19/45

Specification of the Sensor Access Service – Specification of the getSensorData Operation Table 3: Specification of the getSensorDescription Operation

6.2.2

Specification of the getSensorData Operation The mandatory getSensorData operation lets the client retrieve measured values. Which values need to be retrieved must be formulated in a query using a supported query language. This operation can also be used to retrieve a series of measurements if available. Therefore a sequence of OA_SensorData objects is returned. The signatures of the operation is Sequence getSensorData ( OA_Query ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_IllegalQuery, OA_InvalidSensorID

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

mandatory

Receives

Name query

Returns

Type OA_Query

mandatory

Type Sequence

Throws

Use

Description Specifies the query to be used to retrieve observations/sensor data. Description

List of matching data sets for the specified sensor and query.

Type

Cause





OA_NoApplicableCode


OA_InternalError


OA_IllegalQuery


OA_InvalidSensorID


Table 4: Specification of the getSensorData Operation

20/45

Specification of the Sensor Access Service – Specification of the getSensorDataTypes Operation 6.2.3

Specification of the getSensorDataTypes Operation The mandatory getSensorDataTypes operation lets the client retrieve the schemas for the sensor data types that a specific sensor uses for its measured values. The signatures of the operation is Sequence getSensorDataTypes ( OA_Query ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_IllegalQuery

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

mandatory

Receives

Name query

Returns

Type

Use

OA_Query

mandatory

Type

Specifies the query that sensors whose data description must be returned. Description

Sequence Throws

Description

Type

List of sensor data descriptors that contain the schemas for the queried sensors/sensor data. Cause





OA_NoApplicableCode


OA_InternalError


OA_IllegalQuery


Table 5: Specification of the getSensorData Operation

21/45

Specification of the Sensor Access Service – OA_SensorCache

6.3

Specification of Parameter Types This service specification does define new OA Types. These new OA Types will become part of the OAS “OA Types” This service specification does not define any new OT Types. This service specification does not introduce any new non-orchestra Types.

6.3.1

OA_SensorCache Simple compound data type of a sensor identifier and a Boolean flag to indicate whether the sensor data of the sensor will be kept even after the sensor has been removed from the service. cd Sensor Access Service «Type» OA_SensorCache + +

sensorID: OA_SensorID keepValues: Boolean

Diagram 3: Class diagram of OA_SensorCache

6.3.2

OA_SensorID The OA_SensorID type is used to uniquely identify a specific service on one OSI. Note that this identifier is not required to be unique among multiple SensorAccessService instances. The content of this identifier is specific to the implementation since implementers should not be required to use unique numbers or strings or any other specific method as long as they can guarantee that the identifiers are unique at their service instance. cd Sensor Access... «Type» OA_SensorID -

contents: Any

Diagram 4: Class diagram of OA_SensorID

6.3.3

OA_SensorDescriptor The sensor descriptor contains the description for a specific sensor. This description is formulated in a specific description language and can be used to get detailed information about a sensor. This description is also used when using the getSensor operation with a query to find sensors that apply to certain criteria. Since the dynamic information (if available this might be current position or measurement thresholds) could be useful for finding the desired sensor, the descriptor also contains the sensor’s current configuration. In order to relate the description to the correct sensor, it also contains its sensor’s identifier.

22/45

Specification of the Sensor Access Service – OA_SensorDataDescriptor cd Sensor Access Service - OA Types «Type» OA_SensorDescriptor -

descriptionSchema: OA_SchemaDescriptor encoding: OA_Encoding description: OA_URI 1..*

«Type» OA_SensorConfiguration -

configSchema: OA_SchemaDescriptor encoding: OA_Encoding configuration: OA_URI

«Type» OA_SensorID -

contents: Any

Diagram 5: Class diagram of OA_SensorDescriptor

6.3.4

OA_SensorDataDescriptor The sensor data descriptor contains the schema for a specific sensor data type. The sensorID uniquely identifies the sensor whose data uses the contained schema as its data format. cd Sensor Access Service «type» OA_SensorDataDescriptor -

sensorID: OA_SensorID schema: OA_SchemaDescriptor

Diagram 6: Class diagram of OA_SensorDataDescriptor

6.3.5

OA_SensorData The sensor data contains both the sensor’s identifier and the measured data (along with the data type’s schema). Additionally the sensor data is tightly coupled with a sensor status. Therefore if available the status is only retrievable through its associated data set.

23/45

Specification of the Sensor Access Service – OA_SensorStatus cd Sensor Access Service - OA Types «Type» OA_SensorData -

sensorID: OA_SensorID dataSchema: OA_SchemaDescriptor contents: Any

0..1 «Type» OA_SensorStatus + +

statusSchema: OA_SchemaDescriptor contents: Any

Diagram 7: Class diagram of OA_SensorData

6.3.6

OA_SensorStatus The sensor status contains information about the sensor that might frequently change. Examples of such statuses might be the current operation mode of the sensor or error and warning information. The status of a sensor is only available through the sensor data but not on its own. cd Sensor Access Service - OA Types «Type» OA_SensorStatus + +

statusSchema: OA_SchemaDescriptor contents: Any

Diagram 8: Class Diagram of OA_SensorStatus 6.3.7

OA_SensorConfiguration The sensor configuration models the dynamic (possibly configurable) information about a sensor. Such dynamic might be the current position of the sensor or special measurement thresholds. The configuration contains its related schema descriptor which specifies the schema of the configuration. That way, configurable items can be found out. In order to relate the configuration description to the correct sensor, it also contains its sensor’s identifier. Note: It is not required that all parts of the dynamic information (= configuration data) need to be configurable by using the SensorConfigurationInterface. The OA_SensorConfiguration content only means that the information can change. Whether it can be configured by using the SensorConfigurationInterface must be found out by examining the configuration’s schema.

24/45

Specification of the Sensor Access Service – OA_InvalidSensorID cd Sensor Access Service - OA Types «Type» OA_SensorConfiguration -

configSchema: OA_SchemaDescriptor encoding: OA_Encoding configuration: OA_URI

«Type» OA_SensorID -

contents: Any

Diagram 9: Class diagram of OA_SensorConfiguration

6.3.8

OA_InvalidSensorID The OA_InvalidSensorID exception is returned each time when an invalid sensor identifier is passed as parameter to an operation. cd Sensor Access Service «Type» OA_InvalidSensorID + +

parameterName: CharacterString [1..*] {ordered} sensorIDs: OA_SensorID [1..*] {ordered}

Diagram 10: Class diagram of OA_InvalidSensorID

6.3.9

OA_InvalidConfiguration The OA_InvalidConfiguration exception is returned when an invalid configuration (either not suitable for the specified sensor or it contains invalid values) is passed as parameter to an operation.

cd Sensor Access Service «Type» OA_InvalidConfiguration -

sensorID: OA_SensorID configSchema: OA_SchemaDescriptor

Diagram 11: Class diagram of OA_InvalidConfiguration

25/45

Specification of the Sensor Access Service – OA_InvalidConfiguration

7

Specification of the Sensor Administration Interface cd Sensor Access Service «interface» SensorAdministrationInterface {abstract} + + + +

addSensorDescription(OA_SensorDescriptor) : OA_SensorID updateSensorDescription(OA_SensorID, OA_SensorDescriptor) : void removeSensorDescription(OA_SensorID) : void setSensorData(OA_SensorID, OA_SensorData) : void

Diagram 12: Class Diagram of the Sensor Administration Interface The Sensor Administration Interface defines the following operations:

Operation Name

Description

addSensorDesctiption

Add a new sensor with its specified description to the service.

updateSensorDescription

Updates the description of the specified sensor.

removeSensorDescription

Removes the specified sensor from the service.

setSensorData

Publishes new sensor data at the service so that clients may retrieve it through an invocation of the getSensorData operation. Table 6: Summary of operations

7.1

Specification of an OAS Profile of Parameter Types used by the Sensor Administration Interface The following non basic types are used within this specification:

Name

Usage

from OAS

New

OA_SensorID

I/O

OA Types

Ye s

OA_SensorDescriptor

I/O

OA Types

Ye s

OA_SensorData

I/O

OA Types

Ye s


E


No


E


No

26/45

Specification of the Sensor Access Service – OA_InvalidConfiguration

OA_NoApplicableCode

E


No

OA_InternalError

E


No

OA_InvalidSensorID

E


Ye s


27/45

Specification of the Sensor Access Service – Specification of the addSensorDescription Operation

7.2 7.2.1

Specification of the Operations Specification of the addSensorDescription Operation The optional addSensorDescription operation adds a new sensor to the service. The description of the sensor must be provided which will be returned by the getSensorDescription operation. In order to be able to find the correct sensor this description should be detailed and correct. The signatures of the operation is OA_SensorID addSensorDescription ( OA_SensorDescriptor ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

optional

Receives

Name

Type

Use

sensorDesc

OA_SensorDescriptor

mandatory

Returns

Type OA_SensorID

Throws

Description Description of the newly added sensor. Description

Unique identifier of the new sensor. Type

Cause





OA_NoApplicableCode


OA_InternalError


Table 8: Specification of the addSensorDescription Operation

7.2.2

Specification of the updateSensorDescription Operation The optional updateSensorConfiguration lets the user change the description of an already existing sensor. The parameters are the identifier of the sensor whose description must be changed as well as the new description.

28/45

Specification of the Sensor Access Service – Specification of the removeSensorDescription Operation The signatures of the operation is void updateSensorDescription ( OA_SensorID, OA_SensorDescriptor) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_InvalidSensorID

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

optional

Receives

Name

Type

Use

Description

sensorID

OA_SensorID

mandatory

Identifier of the sensor whose description must be updated.

sensorDesc

OA_SensorDescriptor

mandatory

Updated description of the specified sensor.

Returns

Type

Description

Throws

Type

Cause





OA_NoApplicableCode


OA_InternalError


OA_InvalidSensorID


Table 9: Specification of the updateSensorDescription Operation

7.2.3

Specification of the removeSensorDescription Operation The optional removeSensorDescription operation lets the client remove a sensor that already exists at the service. This means that there will not be any new measurement data from this sensor. Whether the old data is stored (aka there is a repository for old sensor data at the service that) or not is service specific but must be specified in the service’s capabilities. This gives the client the ability to choose only data storing services if decision tracking is a requirement. If the old sensor data is still accessible at the service, the sensor identifier will still be valid and the get-

29/45

Specification of the Sensor Access Service – Specification of the setSensorData Operation SensorData also can be used to retrieve that data. If the old data is not kept but deleted, the sensor identifier is invalid after this operation has successfully been invoked and therefore will not be looked up in a query. If the provided identifier is not related to an existing sensor at the service an OA_InvalidSensorID exception is returned. The signatures of the operation is void removeSensorDescription ( OA_SensorID ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_InvalidSensorID

Overrides

not applicable

Preconditions

At least one sensor must be available at the service

Post conditions

none

Use

optional

Receives

Name

Type

sensorID

OA_SensorID

Use mandatory

Description The identifier of the sensor that must be removed.

Returns

Type

Description

Throws

Type

Cause





OA_NoApplicableCode


OA_InternalError


OA_InvalidSensorID


Table 10: Specification of the removeSensorDescription Operation

7.2.4

Specification of the setSensorData Operation The mandatory setSensorData operation allows the sensor operator to publish new data measured by the provided sensor. Whether the old values are stored in a repository or not is both, sensor and implementation dependent. The signatures of the operation is

30/45

Specification of the Sensor Access Service – Specification of the setSensorData Operation void setSensorData (OA_SensorID, OA_SensorData) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_InvalidSensorID

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

mandatory

Receives

Name

Type

Use

Description

sensorID

OA_SensorID

mandatory

The identifier of the sensor whose data must be published.

sensorData

OA_SensorData

mandatory

The data set provided by the sensor, which will become the most recent value.

Returns

Type

Description

Throws

Type

Cause





OA_NoApplicableCode


OA_InternalError


OA_InvalidSensorID


Table 11: Specification of the setSensorData Operation

31/45

Specification of the Sensor Access Service – Specification of the getConfigurationSchema Operation

7.2.5

Specification of the getConfigurationSchema Operation The mandatory getConfigurationSchema operation retrieves the schema that defines the structure of the sensor’s configuration type. This can be used to find parts that must and/or can be changed when configuring the sensor. The signatures of the operation is OA_SchemaDescriptor getConfigurationSchema ( OA_SensorID) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_InvalidSensorID

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

mandatory

Receives

Name sensorID

Returns

Type OA_SensorID

Description

mandatory

Identifier of the sensor whose configuration schema must be returned.

Type OA_SchemaDescriptor

Throws

Use

Description The schema descriptor of the sensor’s configuration.

Type

Cause





OA_NoApplicableCode


OA_InternalError


OA_InvalidSensorID


Table 12: Specification of the getConfigurationSchema Operation

7.2.6

Specification of the getSensorConfiguration Operation The mandatory getSensorConfiguration operation retrieves the current configuration of the provided sensor. This configuration contains dynamic information that might change with a different configura-

32/45

Specification of the Sensor Access Service – Specification of the setSensorConfiguration Operation tion. (e.g.: current position/orientation of the sensor). The signatures of the operation is OA_SensorConfiguration getSensorConfiguration ( OA_SensorID) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_InvalidSensorID

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

mandatory

Receives

Name

Type

sensorID Returns

OA_SensorID

mandatory

Type OA_SensorConfiguration

Throws

Use

Description The identifier of the sensor whose configuration must be returned. Description

The currently active configuration of the specified sensor.

Type

Cause





OA_NoApplicableCode


OA_InternalError


OA_InvalidSensorID


Table 13: Specification of the getSensorConfiguration Operation

7.2.7

Specification of the setSensorConfiguration Operation The mandatory setSensorConfiguration operation makes the provided configuration current for the specified sensor. If the configuration is invalid an OA_InvalidConfiguration exception is returned and the configuration that was active before this operation has been invoked stays the active one. The signatures of the operation is void setSensorConfiguration ( OA_SensorID, OA_SensorConfiguration ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_InvalidConfiguration

33/45

Specification of the Sensor Access Service – Specification of the setSensorConfiguration Operation

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

mandatory

Receives

Name

Type

Use

Description

sensorID

OA_SensorID

mandatory

The identifier of the sensor whose configuration must be set.

config

OA_SensorConfiguration

mandatory

The configuration that must be set as current configuration for the specified sensor.

Returns

Type

Description

Throws

Type

Cause





OA_NoApplicableCode


OA_InternalError


OA_InvalidConfiguration

The provided configuration is not valid for the specified sensor.

Table 14: Specification of the setSensorConfiguration Operation

34/45


35/45


7.3

Specification of Parameter Types This service specification does not define new OA Types. These new OA Types will become part of the OAS “OA Types”/SensorAccessService This service specification does not define any new OT Types. This service specification does not introduce any new non-orchestra Types.

8

Specification of the Sensor Configuration Interface cd Sensor Access Service «interface» SensorConfigurationInterface {abstract} + + + +

getConfigurationSchema(OA_SensorID) : OA_SchemaDescriptor getSensorConfiguration(OA_SensorID) : OA_SensorConfiguration check SensorConfiguration(OA_SensorID, OA_SensorConfiguration) : void setSensorConfiguration(OA_SensorID, OA_SensorConfiguration) : void

Diagram 13: Class Diagram of the Sensor Configuration Interface The Sensor Configuration Interface defines the following operations:

Operation Name

Description

getConfigurationSchema

Retrieves the configuration schema of the specified sensor.

getSensorConfiguration

Retrieves the currently active configuration for the specified sensor.

setSensorConfiguration

Sets the configuration for the specified sensor. Table 15: Summary of operations

8.1

Specification of an OAS Profile of Parameter Types used by the Sensor Configuration Interface The following non basic types are used within this specification:

Name

Usage

from OAS

New

OA_SensorID

I/O

OA Types

Ye s


I/O

OA Types

Ye s

36/45



E


No


E


No

OA_NoApplicableCode

E


No

OA_InternalError

E


No

OA_InvalidSensorID

E


Ye s


E


Ye s


37/45

Specification of the Sensor Access Service – Specification of the getConfigurationSchema Operation

8.2 8.2.1

Specification of the Operations Specification of the getConfigurationSchema Operation The mandatory getConfigurationSchema operation retrieves the schema that defines the structure of the sensor’s configuration type. This can be used to find parts that must and/or can be changed when configuring the sensor. The signatures of the operation is OA_SchemaDescriptor getConfigurationSchema ( OA_SensorID ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_InvalidSensorID

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

mandatory

Receives

Name sensorID

Returns

Type OA_SensorID

Description

mandatory

Identifier of the sensor whose configuration schema must be returned.


Throws

Use

Description The schema descriptor of the sensor’s configuration.

Type

Cause





OA_NoApplicableCode


OA_InternalError


OA_InvalidSensorID



38/45

Specification of the Sensor Access Service – Specification of the getSensorConfiguration Operation 8.2.2

Specification of the getSensorConfiguration Operation The mandatory getSensorConfiguration operation retrieves the current configuration of the provided sensor. This configuration contains dynamic information that might change with a different configuration. (e.g.: current position/orientation of the sensor). The signatures of the operation is OA_SensorConfiguration getSensorConfiguration (OA_SensorID) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_InvalidSensorID

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

mandatory

Receives

Name

Type

sensorID Returns

OA_SensorID

mandatory

Type OA_SensorConfiguration

Throws

Use

Description The identifier of the sensor whose configuration must be returned. Description

The currently active configuration of the specified sensor.

Type

Cause





OA_NoApplicableCode


OA_InternalError


OA_InvalidSensorID


Table 18: Specification of the getSensorConfiguration Operation

8.2.3

Specification of the setSensorConfiguration Operation The mandatory setSensorConfiguration operation makes the provided configuration current for the specified sensor. If the configuration is invalid an OA_InvalidConfiguration exception is returned and the configuration that was active before this operation has been invoked stays the active one. The signatures of the operation is

39/45

Specification of the Sensor Access Service – Specification of the setSensorConfiguration Operation void setSensorConfiguration (OA_SensorID, OA_SensorConfiguration) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_InvalidSensorID

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

mandatory

Receives

Name

Type

Use

Description

sensorID

OA_SensorID

mandatory

The identifier of the sensor whose configuration must be set.

config


mandatory

The configuration that must be set as current configuration for the specified sensor.

Returns

Type

Description

Throws

Type

Cause





OA_NoApplicableCode


OA_InternalError



The provided configuration is not valid for the specified sensor.

OA_InvalidSensorID


Table 19: Specification of the setSensorConfiguration Operation

40/45

Specification of the Sensor Access Service – Specification of Parameter Types

8.3

Specification of Parameter Types This service specification does not define new OA Types. These new OA Types will become part of the OAS “OA Types”/SensorAccessService This service specification does not define any new OT Types. This service specification does not introduce any new non-orchestra Types.

9

Specification of the Service specific Capabilities As part of ORCHESTRA D3.3.2 a meta-information schema for services is defined acting as a default OAS-MI for service capabilities. OA_MI_CapabilitiesDocument includes both the common capabilities and the service specific capabilities. While the common capabilities are defined in the specification of the Service Capabilities Interface, the specific capabilities have to be specialized in each service specification. The schema for service specific capabilities defined here is explicitly divided into the following schema sections:

Section Name

Section Contents Contains schemas for the additional OA Types as well as information about the implemented interfaces. This information might differ depending on the access rights granted at this service. E.g.: only certain clients might be allowed to add new sensors, therefore others won’t see the SensorAdministrationInterface specifics if they request the capabilities.

SASCapabilities


Name

Definition

Data Type

Multiplicity and Use 1..1

configurationSupported

Flag whether the SensorConfigurationInterface is implemented

Boolean

administrationSupported

Flag whether the SensorAdministrationInterface is implemented

Boolean

keepOldSensorData

List of flag with sensor identifiers whether the measured values of a sensor are still kept and available at the service even after the sensor itself has been removed from the service.

Sequence

1


List of supported query languages that can be used in the SensorDataInterface

Sequence

1

availableSensorData

List of short descriptions about the differ-

Se-

1

41/45

Mandatory 1..1 Mandatory

Mandatory

Mandatory

Specification of the Sensor Access Service – Specification of Parameter Types ent types of sensors (and their data) are available at this SensorAccessService. This gives the client the possibility to check whether the service provides any needed observations.

quence

Mandatory

Table 21: Attributes of the service specific capabilities of section SASCapabilities

42/45

Specification of the Sensor Access Service –

10 Known Issues and Limitations There are currently no issues and limitations known that may to be resolved in a platform specific specification.

43/45

Specification of the Sensor Access Service – Appendix A: Abstract Test Suite (normative)

11

Appendix A: Abstract Test Suite (normative) When creating an implementation specification of the Sensor Access Service, the “Rules for Implementation Specifications of ORCHESTRA Services” defined in chapter 9.2.2.3 and the “Rules for the Service Mapping to a given Platform” of the RM-OA shall be obeyed. In addition, the following tests shall be performed to ensure conformance of an implementation specification to the platform-independent specification of the Sensor Access Service: 1. Syntactical Conformance •


•


•


•




Additional conformance checks that are specifically to the Sensor Access Service are not required.

44/45

Specification of the Sensor Access Service – Appendix B: UML Models (normative)


45/45




Specification of the Service Chain Access Service

Revision

1/25

[0.4 / 2.2.2]

Specification of the Service Chain Access Service – Document Control Page


Specification of the Service Chain Access Service

Creator

Friis-Christensen, Anders, JRC-IES

Subject


Description

This document defines an abstract and platform independent formal specification of the Service Chain Access Service.

Publisher


Contributor

Friis-Christensen, Anders, JRC-IES Lutz, Michael, JRC-IES Lucchi, Roberto, JRC-IES

Date

2007-10-16

Type

Text

Format

application/msword

Identifier


Source

Not applicable

Language

en

Relation

none

Coverage


Rights

D3.4.2

Deliverable number

D3.4.4


WP3.4


2007-10-31


2007-10-20

Audience


Version number

0.4 / 2.2.2

Date

2007-10-16

Modified by

Lucchi, Roberto, JRC-IES

Comments Status


2/25

Specification of the Service Chain Access Service – Document Control Page



3/25

Specification of the Service Chain Access Service – Revision History


Date

Sections changed

Description

0.1 / 1.7

2006-02-23

All

Document created

0.2 / 2.0

2006-05-11

All

Modifications according template ver.2

0.3 /2.0.6

2006-10-20

All

Modifications according template ver.2.0.6 and review. Changes to the semantics of some operations and OA types

0.4/2.2.2

2007-10-16

All

Added additional parameters to the service interface, some considerations about security issues, implementation issues and some minor reviews on data types. Modifications according template ver. 2.2.2

4/25

Specification of the Service Chain Access Service – Table of Contents

Table of Contents 1

Foreword ................................................................................................................................................. 8

2

Conventions............................................................................................................................................. 9

3

4

2.1

Abbreviations.................................................................................................................................... 9

2.2

Terms and definitions ....................................................................................................................... 9

2.3

UML Notation ................................................................................................................................... 9

2.4

Conformance.................................................................................................................................... 9

2.4.1

Conformance to the OMM ......................................................................................................... 9

2.4.2


Overview and Architecture Outline .......................................................................................................... 9 3.1

Role and Scope of the Service Chain Access Service...................................................................... 9

3.2

Service Specification Summary ...................................................................................................... 11

Context of the Service Chain Access Service........................................................................................ 12 4.1

Relations to Standards ................................................................................................................... 12

4.2

Relations to ongoing Initiatives and related Projects....................................................................... 12

4.3

Relations to ORCHESTRA Application Schemas ........................................................................... 12

4.4

Relations to other ORCHESTRA Service Specifications ................................................................ 13

Requirements ........................................................................................................................................ 14 5

6

14 5.1

Security Requirements ................................................................................................................... 14

5.2

Reliability Requirements ................................................................................................................. 14

Specification of the Service Chain Access Service Interface ................................................................. 15 6.1

Specification of an OAS Profile of Parameter Types used by the Service Chain Access Service ... 15

6.2

Specification of additional Types .................................................................................................... 16

6.3

Specification of the Service Interface Operations ........................................................................... 17

6.3.1

Specification of the createServiceChain Operation.................................................................. 17

6.3.2

Specification of the getServiceChain Operation....................................................................... 19

6.3.3

Specification of the deleteServiceChain Operation.................................................................. 20

7

Specification of the Service specific Capabilities ................................................................................... 21

8

Known Issues and Limitations ............................................................................................................... 23

5/25

Specification of the Service Chain Access Service – Table of Contents 9

Appendix A: Abstract Test Suite (normative) ......................................................................................... 24

10 Appendix B: UML Models (normative) ................................................................................................... 25 10.1

XMI Model................................................................................................................................... 25

6/25

Specification of the Service Chain Access Service – Tables and Diagrams

Tables Table 1: Interaction between related Services .............................................................................................. 13 Table 2: Summary of additional Service Operations ..................................................................................... 15 Table 4: Referenced OA Types .................................................................................................................... 16 Table 5: Specification of the createServiceChain Operation ......................................................................... 18 Table 6: Specification of the getServiceChain Operation .............................................................................. 20 Table 7: Specification of the deleteServiceChain Operation ......................................................................... 20 Table 7: Sections of the service specific capabilities .................................................................................... 21 Table 8: Attributes of the service specific capabilities of the Service Chain Access Service ......................... 22

Diagrams Diagram 1: Class Diagram of the Service Chain Access Service.................................................................. 11 Diagram 2: Class Diagram of the Service Chaining Access Service Interface .............................................. 15 Diagram 3: OA Types ................................................................................................................................... 16 Diagram 3: Class diagram with service specific capabilities ......................................................................... 21

7/25

Specification of the Service Chain Access Service – Foreword

1

Foreword This document is an abstract specification of the Service Chain Access service and is based on the Template for the abstract Specification of ORCHESTRA Service Types version 2.2. It updates the specification version 0.2. The changes concerns all the sections by taking into account the new template version and some issues concerning security, service chain instance management. This document includes two annexes: Appendix A: Abstract Test Suite (normative) is mandatory and Appendix B: UML Models (normative) is optional.

8/25

Specification of the Service Chain Access Service – Conventions

2

Conventions

2.1

Abbreviations The abbreviations used in this document are defined in chapter 3.1 of the Reference Model for the ORCHESTRA Architecture Version 2.0 (RM-OA) and in chapter 2.1 of the referenced interface type specifications, except for the following abbreviated terms: •

2.2

SCAS: Service Chaining Access Service

Terms and definitions Terms and definitions necessary for understanding this document are defined in chapter 3.2 of the RMOA Glossary .

2.3


2.4

Conformance

2.4.1


2.4.2


3

3.1


Role and Scope of the Service Chain Access Service The Service Chain Access Service (SCAS) is a service that creates an executable service instance based on an explicit description of a service chain. The chain can then be executed as a single service. However, in the current version of this specification, the execution of the service is outside the scope of this Service Chain Access Service. Based on the Reference Model of Open Distributed Processing (RM-ODP) {RM-ODP} definition of chain of actions, a service chain is defined in ISO 19119 as a sequence of services where, for each adjacent pair of services, occurrence of the first action is necessary for the occurrence of the second action. For the scope of this specification, it is important to distinguish between the description of a service chain (i.e. a document), a deployed instance of a chain (i.e. an executable piece of code) and the actual process of executing the chain.

9/25

Specification of the Service Chain Access Service – Overview and Architecture Outline A service chain description is an explicit description of a concrete service chain in some workflow language (e.g. BPEL), which can be used by a workflow (or service chain execution) service to execute the service chain (see workflow-managed chaining below). A service chain instance is an executable service chain deployed on some server. It can either be a workflow service executing a service chain description or a hard-wired composition of several services that appear as a single service (see aggregate service below). A service chain execution is the process of executing a service chain. The execution can be performed by a workflow service on the fly (or ad hoc) based on a service chain description or it can be a simple call to a service chain instance that has already been deployed. Several approaches can be taken in the creation and execution of service chains. Following the computational viewpoint of ISO 19119, the following three design patterns can be distinguished: •

User defined chaining. The human user creates the service chain and manages its execution. This means that the user has to ensure that the inputs and outputs of individual services are compatible and that the complete chain is semantically correct. As the details of the services are not hidden from the user this pattern is also called transparent chaining. In this scenario, no explicit description of the service chain exists.

•

Workflow-managed chaining. The human user invokes a service that controls the chain (called Workflow Management Service in ISO 19119). The user’s involvement in the steps of the chain is mostly one of watching the execution of the individual services that are apparent to the user (hence the alias of translucent chaining). He may also need to provide parameters particular to the specific instance, but relies on the workflow service to carry out the chain. In contrast to the previous scenario, the “existence of a defined chain prior to the user executing the pattern” is assumed. This predefined chain is assumed to have a degree of semantic validity. It is not specified whether this means an explicit description of the chain in some workflow language (like BPEL) that can be executed by a (loosely coupled) workflow service or a deployed instance of the chain that is tightly coupled to a specific instance of a workflow service (and hence does not require an explicit description). Note also that this pattern is only concerned with the execution of the chain, not its creation.

•

Aggregate service. In this pattern the services appear as a single service which handles all coordination of the individual services that are part of the chain. The user may or may not be aware that there is a set of services behind the aggregate service but has no possibility to watch the execution of the individual services (hence the alias of opaque chaining). As in the previous pattern, the existence of a pre-defined service chain, in the sense of a deployed instance of the chain, is assumed. In contrast to translucent service chaining, however, the user cannot observe the execution of the chain or access intermediate results. Again, the pattern only addresses the execution and not the creation of the chain.

This specification is based on the aggregate service pattern. Through the createServiceChain operation it supports a service provider in creating an executable instance of an aggregate service based on an explicit service chain description and optionally to register that service instance with a catalogue service. The resulting aggregate service is itself an ORCHESTRA Service (i.e. inherits from the OA Basic Service) with all generic properties (like e.g. a getCapabilities operation). It is described by means of an OA_MetaInformationSet (according to the Catalogue Service specification). The execution of the service chain thus corresponds to the call of an ORCHESTRA Service Instance operation in an OSN. The createServiceChain operation has also allows the users to specify the specific engine (identified by its address) to be used for deploying the service chain instance and supporting its execution. It is worth noting that this parameter significantly changes the role of SCAS. In the case the user does not specify the engine the role of SCAS is to fully handle the resources which are necessary for the creation and the execution of the service chain. In this case it directly controls the deployed service chain instance and the engine used for the service chain execution. In the case the engine is selected by the user (which must be aware of existing engines in the system), the role of SCAS is to mediate between the

10/25

Specification of the Service Chain Access Service – Overview and Architecture Outline user and the engine. Note: The createServiceChain operation raises some issues that deserve to be discussed. SCAS receives by the users the service chain description whose execution has to be supplied by SCAS (or by a server it manages). Besides well known issues related with code mobility (what does this service chain? is it trusted/secure? which data does it handle? what kinds of fault does it throw, etc) which are out of the scope of this specification, it is important to verify the conformance of submitted service chain descriptions. The service chain description must satisfy the following conditions: i) it has to be specified in one of the supported languages (e.g. BPEL), ii) it must be (at least syntactically) correct, and iii) it has to be compliant with the ORCHESTRA service requirements (some proposals that could support the definition of correct service chain description are reported in Section 8). Therefore, before creating at run-time new ORCHESTRA service instances based on the service chain, it is necessary to verify the conditions listed above. Since the SCAS is responsible for deploying service chains we delegate these checks to the SCAS (this fact could imply, at the implementation level, an asynchronous interface for the createServiceChain operation). Note: It is worth noting that the policy governing service chain deployment is an implementation aspect of each SCAS instance. We introduce a service chain identifier, used to uniquely identify the service chain descriptions, which allows us to distinguish between the addresses (i.e. a URI) of created service chains instances and the service chain descriptions. In this way the SCAS can manage service instances in a more flexible way by creating, for example, new service chain instances (or moving existing ones) in the OSN. Note: It might become necessary to also consider the workflow-managed service chaining pattern in this specification in order to allow users to flexibly adapt existing service chains and execute them in an ad-hoc fashion. This option will be elaborated in a future version of this specification.

3.2

Service Specification Summary This service type specification of the Service Chain Access Service is comprised of the following interfaces that are defined in separate interface type specifications: •



The Service Chain Access Service Interface Type

class Serv ice Chain Access Serv ice «interface» ServiceChainAccessService + + + +

createServiceChain(request :OA_ServiceChainRequest, catalogue :OA_URI, engine :OA_URI) : OA_ServiceChainResponse deleteServiceChain(id :OA_UniqueID) : void getCapabilities(capabilities :OA_GetCapabilitiesRequest) : OA_GetCapabilitiesResponse getServiceChain(id :OA_UniqueID) : OA_ServiceChainDescriptor

Diagram 1: Class Diagram of the Service Chain Access Service

11/25

Specification of the Service Chain Access Service – Context of the Service Chain Access Service

4 4.1

Context of the Service Chain Access Service Relations to Standards The service chain descriptions must be specified by means of standard languages which are equipped of service engines able to execute the service chaining. A list of the most credited languages for service and service chain description specification follows: •

ISO 19119:2005 Geographic information – Services

•

OASIS Web Services Business Process Execution Language (WS-BPEL) http://www.oasisopen.org/committees/tc_home.php?wg_abbrev=wsbpel

•

XLANG - web services for business process design. Satish Thatte, Microsoft, 2001.

•

Web Services Flow Language (WSFL). IBM, 2001.

•

W3C Web Services Description Language (WSDL) 1.1 (http://www.w3.org/TR/wsdl)

ISO 19119 defines the service chain and in particular, the computational approach we use is based on the aggregate service pattern (opaque chaining). This is due to the fact that: i) current workflow engines support this approach, ii) the aggregate service pattern seems to be the more suitable one for the service oriented paradigm. WS-BPEL is the most credited language for expressing concrete service chains, others are XLANG and WSFL (WS-BPEL inherits all the main design constructs of both languages). Actually WS-BPEL is the only one which is continuously extended (now version 2.0 is available) and it is also the only one equipped with stable engines able to execute the service chain. Since service engines supply the execution of aggregated services by means of a single service, the WSDL standard is used to describe the corresponding interface. During the design of concrete service chain descriptions it could be necessary (e.g. in the case of very com-plex service chains) to start by using higher level languages for services choreography and then move to concrete and executable languages (e.g. WS-BPEL). The most credited standard for choreography is: •

W3C Web Service Choreography http://www.w3.org/TR/ws-cdl-10/:

Description

Language

(WS-CDL)

1.0.

The Service Chain Access Service currently does not qualify for the contribution to a standard.

4.2

Relations to ongoing Initiatives and related Projects The Service Chain Access Service has no immediate relation to ongoing projects.

4.3

Relations to ORCHESTRA Application Schemas The Service Chain Access Interface Type Specification that is specified as integral part of this Service Type Specification uses Basic and OA Types that are defined in the package OAS/Basic Types, OAS/OA Types and OAS-MI/OA-MI Types of the Information Viewpoint. The Service Chain Access Interface Type Specification that is specified as integral part of this Service Type Specification defines new parameter types. These parameter types are defined in the package OAS/OA Types/«Application Schema» Service Chain Access Service Exceptions, OAS/OA Types/ «Application Schema» Service Chain Access Service Types of the Information Viewpoint.

12/25

Specification of the Service Chain Access Service – Context of the Service Chain Access Service

4.4

Relations to other ORCHESTRA Service Specifications The createServiceChain operation supports the publication of the service in a catalogue service.

Name CatalogueService

Service Type

Service Operation createMetaInformation

Table 1: Interaction between related Services

13/25

Specification of the Service Chain Access Service – Requirements

5 5.1

Requirements Security Requirements The Service Chain Access Service has the following requirements beyond the scope of the Authentication and Authorization Service.

5.2

•

The creation of a new service chain inherits all the issues concerning the definition of the access policy to an ORCHESTRA Service instance. However, in this case, the problem is more complex because such services are created on-the-fly during the evolution of the system by specialized services (SCASs). In this scenario UAA operations for defining (at run-time) and supporting new service access policies are necessary.

•

Services involved in service chains could be supplied by multiple providers and for some of them the user could be not authorized to use them. In this scenario, it maybe useful to perform a preliminary check about access permissions to all the involved services. This check should allow us to avoid of uselessly consuming computational services resources when the chain cannot complete its execution. In order to tackle this issue it should be necessary dealing with the different authorization mechanism used by the User Authentication and Authorization Services for service chains (see the “UAA Guidelines” document). Actually the most prominent mechanism for this aspect seems to be the “Acting with the Service Chain’s Principal” one.


SCAS is responsible for managing created services chains instances. If one of those services fails (e.g. it crashes) or it does not ensure basic quality of service requirements (e.g. the server is overloaded with service requests), it has to be replaced with a new service chain instance (based on the same service chain description). The distinction between service chain description identifiers and service chain instances addresses simplifies the management of such problems. Indeed, for instance, a user can get the addresses of newer service chain instances by using the getServiceChain operation.

14/25

Specification of the Service Chain Access Service – Specification of the Service Chain Access Service Interface

6

Specification of the Service Chain Access Service Interface

class SCAS OA Types ServiceCapabilities «interface» ServiceChainAccessService + + +

createServiceChain(OA_ServiceChainRequest, OA_URI, OA_URI) : OA_ServiceChainResponse deleteServiceChain(OA_UniqueID) : void getServiceChain(OA_UniqueID) : OA_ServiceChainDescriptor

Diagram 2: Class Diagram of the Service Chaining Access Service Interface The Service Chain Access Service interface defines the following additional operations:

Operation Name

Description

createServiceChain

Deploys the service chain instance (an aggregated service) specified in a service chain description document

getServiceChain

Gets a descriptor of the service chain which includes MI (id, address, description, and service chain description language) and the service chain description description itself

deleteServiceChain

Deletes service chain description and its corresponding service chain instances Table 2: Summary of additional Service Operations

6.1

Specification of an OAS Profile of Parameter Types used by the Service Chain Access Service The following non basic types are used within this specification:

Name

Usage

from OAS

New

OA_ServiceChainRequest

I

Yes

OA_ServiceChainResponse

O

Yes

OA_ServiceChainDescription

I

Yes

OA_ServiceChainDescriptor

I

Yes

OA_ChainDefinition

I

Yes

15/25


OA_DeployInfo

I

Yes

OA_WorkflowLanguage

I/O

Yes

OA_ServiceChainInfo

O

Yes

OA_URI

I/O

No

OA_UniqueID

I

No

OA_InvalidServiceChainDescription

E

Yes


6.2

Specification of additional Types This service specification defines the following new OA Types. class SCAS OA Types

«type» OA_Serv iceChainRequest + + +

description: OA_ServiceChainDescription language: OA_WorkflowLanguage name: CharacterString

«type» OA_Serv iceChainDescriptor + + + +

description: CharacterString id: OA_UniqueID language: OA_WorkflowLanguage name: CharacterString

«type» OA_Serv iceChainResponse +

serviceChainDescriptionID: OA_UniqueID

«CodeList» OA_Workflow Language + +

OA_Discov ery_MetaInformation_Serv ice

BPEL: ...:

«type» OA_Serv iceChainDescription +

concreteChainDescription: CharacterString

1 OA_ChainDefinition

The metainformation for services has to be defined in the catalogue specification

0..1 OA_DeployInfo

Diagram 3: OA Types 6.2.1

OA_ServiceChainRequest The OA_ServiceChainRequest is specifying the request to create the service chain. It includes information such as requested name, a description of the service chain, the language in which the service chain description is described, and the service chain description itself.

16/25

Specification of the Service Chain Access Service – Specification of the Service Chain Access Service Interface 6.2.2

OA_ServiceChainResponse The OA_ServiceChainResponse is specifying the response when a service chain instance has been created. It includes the id and address the service instance is deployed under.

6.2.3

OA_ServiceChainDescriptor The OA_ServiceChainDescriptor is the representation of a service chain (an aggregated service), including an id, a name, a description, the language used to define the service chain, and finally a reference to the description itself. This is also considered as MI for the service chain and should be entered as a catalogue entry as well.

6.2.4

OA_ServiceChainDescription The OA_ServiceChainDescription is the description of the service chain (service chain description). It contains the service chain definition expressed in some workflow language (e.g. WS-BPEL) and information used to deploy a service chain instance in a workflow engine.

6.2.5

OA_MetaInformationSet The OA_MetaInformationSet should specify the MI for the deployed service and that will be registered in a catalogue and used during the createMetaInformation operation invocation.

6.2.6

OA_ChainDefinition The OA_ChainDefinition describes the concrete workflow of the chain (e.g. a WS-BPEL document).

6.2.7

OA_DeployInfo The OA_DeployInfo contains specific information used during the deployment of the service chain instance. This information could be not necessary and may depend on the specific engine used to support the execution.

6.2.8

OA_WorkflowLanguage The OA_WorkflowLanguage describes the supported workflow languages.

6.2.9

OA_ServiceChainInfo The OA_ServiceChainInfo describes a service chain instance by means of its name, its corresponding identifier and description.

6.3 6.3.1

Specification of the Service Interface Operations Specification of the createServiceChain Operation The mandatory createServiceChain operation deploys a service chain instance specified in a service chain description on a server managed by the SCAS (not necessarily the same server where SCAS is running). More specifically it deploys an aggregated service instance which may be executed as a normal service. Furthermore it is possible by including a URI to a catalogue to register the newly created aggregated service within the catalogue.

Overrides

None

17/25


Preconditions

None

Post conditions

All the related information (including meta information of service chain descriptions) is registered in the catalogue service

Use

Mandatory

Receives

Name

request

catalogue

engine

Type

Use

OA_ServiceChainRequest

OA_URI

OA_URI

Returns

Type

required

The request contains the MI for a service chain (such as name, description, etc) and the actual specification of the service chain (including detailed information for the deployment)

optional

The catalogue is an address of a catalogue which is then updated with the new service instance MI (based on the request)

optional

The engine is an address of a workflow engine. If specified, the service chain instance will be deployed by using this engine. Description

Returns an id identifying the service chain description described in the request parameter

OA_ServiceChainResponse Throws

Description

Type

Cause





OA_NoApplicableCode


OA_InternalError


OA_InvalidServiceChainDescription

The service chain description document is not valid

Table 4: Specification of the createServiceChain Operation

18/25


6.3.2

Specification of the getServiceChain Operation The mandatory getServiceChain operation gets a service chain descriptor which includes meta information (id, address, description, and service chain description language), the service chain description itself and the list of deployed service chain instance descriptors.

Overrides

None

Preconditions

None

Post conditions

None

Use

Mandatory

Receives

Name

Type

serviceChainDescriptionID Returns

OA_UniqueID

Type

required

Description The id of the service Description

The serviceChainDescriptor includes the MI for the service chain (such as name, description), the address of the deployed services and the actual specification of the service chain (the workflow document and the information for the deploy)

OA_ServiceChainDescriptor

Throws

Use

Type





OA_NoApplicableCode


OA_InternalError


19/25


Table 5: Specification of the getServiceChain Operation

6.3.3

Specification of the deleteServiceChain Operation The mandatory deleteServiceChain deletes the service chain instances and its corresponding service chain description. Due to the distribution of the services over the OSN, the deletion is a best effort process (i.e. deployed service chain instances are not necessarily deleted immediately). In particular, the service chain instances will not be available for incoming service operation calls but current executions will be completed.

Overrides

None

Preconditions

None

Post conditions

All the related information (including meta information of service chain descriptions) is deleted from the catalogue service

Use

Mandatory

Receives

Name Id

Type

Use

OA_UniqueID

Returns

required

Type

The id of the service chain description Description

Not applicable Throws

Description

Not applicable Type

Cause





OA_NoApplicableCode


OA_InternalError


Table 6: Specification of the deleteServiceChain Operation

20/25

Specification of the Service Chain Access Service –

7

Specification of the Service specific Capabilities As part of ORCHESTRA D3.3.2 a meta-information schema for services is defined acting as a default OAS-MI for service capabilities. The base type OA_ServiceCapabilitesResponse is divided into common capabilities and service specific capabilities. While the common capabilities are further refined in D3.3.2 the specific capabilities have to be specialized in each service specification.

Section Name

Section Contents Includes information about the specific capabilities of the Service Chain Access Service, containing information about the supported workflow languages and the name, the identifier and the description of each service chain instance that has been created by the SCAS.

SCAS_Capabilities

Table 7: Sections of the service specific capabilities class OAS-MI Serv ice Specific SCAS

«type» OAS-MI Sections:: OA_MI_SectionContentBase

«type» OA_MI_SCAS_Capabilities + +

supportedWorkflowLanguages: OA_WorkflowLanguage serviceChainInfo: OA_ServiceChainInfo [0..*]

«type» OA_Serv iceChainInfo + + +

name: CharacterString description: CharacterString id: CharacterString

Diagram 4: Class diagram with service specific capabilities

21/25



Name

Definition

Data Type

supportedWorkflowLanguage

The language in which the serviceChainDescription is specified in (the service chain description document)

OA_WorkflowLanguage

1:1 / mandatory

serviceChainInfo

Information about each service chain instance that has been created by the SCAS.

OA_ServiceChainInfo

0:N / mandatory

Table 8: Attributes of the service specific capabilities of the Service Chain Access Service

22/25


8

Known Issues and Limitations •

In order to simplify the definition of service chain specifications compliant with the RM-OA service requirements, future versions of this specification could be equipped of additional operations like, for instance, one that returns a service chain description template whose aim is to help in defining valid ORCHESTRA services and, possibly, an additional one supplying service chain description validation (based, e.g., by XML-Schema).

23/25

Specification of the Service Chain Access Service – Appendix A: Abstract Test Suite (normative)

9

Appendix A: Abstract Test Suite (normative) When creating an implementation specification of the Service Chain Access Service, the “Rules for Implementation Specifications of ORCHESTRA Services” defined in chapter 9.2.2.3 and the “Rules for the Service Mapping to a given Platform” of the RM-OA shall be obeyed. In addition, the following tests shall be performed to ensure conformance of an implementation specification to the platform-independent specification of the Service Chain Access Service: 1. Syntactical Conformance •


•


•


•




Additional conformance checks that are specifically to the Service Chain Access Service are not required.

24/25

Specification of the Service Chain Access Service – Appendix B: UML Models (normative)

10 Appendix B: UML Models (normative) 10.1 XMI Model The XMI Models of the Service Chain Access Service specification can be downloaded from the OGC Portal under the following URL: https://portal.opengeospatial.org/index.php?m=projects&a=view&project_id=140&tab=2&artifact_id=242 95 The XMI Model contains only the parameters specified in this service specification. Additional parameters used by this service can be found in the XMI Models of the following interface or service specifications: •


25/25




Specification of the Service Monitoring Service

Revision

1/31

[0.4 / 2.2.1]

Specification of the Service Monitoring Service – Document Control Page


Specification of the Service Monitoring Service

Creator

Ecker, Severin

Subject


Description

This document defines an abstract and platform independent formal specification of the Service Monitoring Service.

Publisher


Contributor

Ecker Severin


Kutschera Peter


Duennebeil Gerhard



Date

2007-09-24

Type

Text

Format

application/msword

Identifier


Source

Not applicable

Language

en-GB.

Relation

none

Coverage



D3.4.3


WP3.4


2007-xx-xx


2007-xx-xx

Audience


Version number

0.4 / 2.2.1

Date

2007-09-24

Modified by

Ecker, Severin


Comments Status


2/31

Specification of the Service Monitoring Service – Document Control Page



3/31

Specification of the Service Monitoring Service – Revision History


Date

Sections changed

Description

0.1 / 2.0.4

2006-07-24

all

Initial version of the specification

0.2 / 2.0.4

2006-10-10

all

Integrated comments by MSC

0.3 / 2.0.4

2007-01-11

all

Removed SMS acronyms

0.4 / 2.2.1

2007-09-24

all

Updated to new template version

4/31

Specification of the Service Monitoring Service – Table of Contents

Table of Contents 1

Foreword..................................................................................................................................................... 8

2

Conventions ................................................................................................................................................ 9 2.1

Abbreviations ....................................................................................................................................... 9

2.2


2.3

UML Notation....................................................................................................................................... 9

2.4

Conformance ....................................................................................................................................... 9

2.4.1


2.4.2


2.5 3

4

5

6

Used parts of other documents ........................................................................................................... 9


Role and Scope of the Service Monitoring Service ........................................................................... 10

3.2


Context of the Service Monitoring Service ............................................................................................... 14 4.1


4.2


4.3


4.4


Requirements ........................................................................................................................................... 15 5.1


5.2


Specification of the Service Monitoring Interface ..................................................................................... 16 6.1 Specification of an OAS Profile of Parameter Types used by the Service Monitoring Service Interface........................................................................................................................................................ 16 6.2


6.2.1

Specification of the putStatus Operation.................................................................................... 18

6.2.2

Specification of the getConfiguration Operation ........................................................................ 20

6.2.3

Specification of the setConfiguration Operation......................................................................... 21

6.2.4


6.2.5

Specification of the getStatistics Operation ............................................................................... 23

6.3


6.3.1

OA_MonitoringSource ................................................................................................................ 24

6.3.2

OA_MonitoringValue .................................................................................................................. 24

5/31

Specification of the Service Monitoring Service – Table of Contents 6.3.3

OA_MonitoringProperty.............................................................................................................. 25

6.3.4

OA_MonitoringConfiguration...................................................................................................... 25

6.3.5

OA_ServiceID............................................................................................................................. 26

6.3.6

OA_Statistics.............................................................................................................................. 26

6.3.7

OA_StatisticalDataValue ............................................................................................................ 26

7

Specification of the Service specific Capabilities...................................................................................... 28

8


9



XMI Model ...................................................................................................................................... 31

6/31

Specification of the Service Monitoring Service – Tables and Diagrams

Tables Table 1: Summary of operations...................................................................................................................... 16 Table 2: Referenced OA Types ....................................................................................................................... 17 Table 3: Specification of the putStatus Operation ........................................................................................... 19 Table 4: Specification of the getConfiguration Operation ................................................................................ 20 Table 5: Specification of the setConfiguration Operation ................................................................................ 21 Table 6: Specification of the getConfigurationSchema Operation................................................................... 22 Table 7: Specification of the getStatistics Operation ....................................................................................... 23 Table 8: Sections of the service specific capabilities....................................................................................... 28 Table 9: Attributes of the service specific capabilities of section SMSCapabilities ......................................... 28 Table 10: Attributes of the service specific capabilities of the sections monitorableCapabilities .................... 28 Table 11: Attributes of the service specific capabilities of section alertCapabilities ........................................ 28

Diagrams Diagram 1: active monitoring ........................................................................................................................... 10 Diagram 2: passive monitoring ........................................................................................................................ 10 Diagram 3: sample monitoring setup ............................................................................................................... 11 Diagram 4: multiple alert services.................................................................................................................... 12 Diagram 5: Class Diagram of the Service Monitoring Service......................................................................... 13 Diagram 6: Class Diagram of the Service Monitoring Service Interface.......................................................... 16 Diagram 7: Class diagram of OA_MonitoringSource....................................................................................... 24 Diagram 8: Class diagram of OA_MonitoringValue ......................................................................................... 25 Diagram 9: Class diagram of OA_MonitoringProperty..................................................................................... 25 Diagram 10: Class diagram of OA_MonitoringConfiguration........................................................................... 26 Diagram 11: Class diagram of OA_ServiceID ................................................................................................. 26 Diagram 12: Class diagram of OA_Statistics................................................................................................... 26 Diagram 13: Class diagram of OA_StatisticalDataValue................................................................................. 27

7/31

Specification of the Service Monitoring Service – Foreword

1

Foreword This document is an abstract specification of the Service Monitoring service and is based on the Template for the abstract Specification of ORCHESTRA Service Types version 2.2. This document includes two annexes: Appendix A: Abstract Test Suite (normative) is mandatory and Appendix B: UML Models (normative) is optional.

8/31

Specification of the Service Monitoring Service – Conventions

2

Conventions

2.1


2.2

Terms and definitions Terms and definitions necessary for understanding this document are defined in chapter 3.2 of the RMOA Glossary and in chapter 2.2 of the referenced interface type specifications, except for the following terms:

2.3

•

Push-model The push-model is a monitoring setup where the service to be monitored ‘pushes’ relevant data to the Service Monitoring Service

•

Pull-model The pull-model is a monitoring setup where the Service Monitoring Service ‘pulls’ relevant data from the monitored service.

•

SMS unless stated otherwise this means Service Monitoring Service in this document.


2.4 2.4.1


2.4.2


2.5

Used parts of other documents

9/31

Specification of the Service Monitoring Service – Overview and Architecture Outline

3 3.1

Overview and Architecture Outline Role and Scope of the Service Monitoring Service The Service Monitoring Service is used to check on (= monitor) the functionality and behaviour of other services within an OSN. The service monitoring components in an OSN consist of three different parts: •

The service being monitored

•

The service monitoring the other services

•

A service that carries out alert instructions

In principle, any ORCHESTRA service can be monitored. This of course includes the monitoring services themselves as well. This way a fully monitored service network can be built. Basically there are two different ways the monitoring can happen: •

Active monitoring (pull model): the monitoring service collects the desired monitoring information from the monitored service (Diagram 1).

•

Passive monitoring (push model): the monitored service pushes status information to the monitoring service (Diagram 2).

Diagram 1: active monitoring

Diagram 2: passive monitoring Usually the implementer and provider of a service monitoring service does not know which situations must be considered as erroneous, especially if the triggering of an alarm depends on probably complex calculations or legal constraints that may even differ from region to region where the service is situated. While the primary use of the Service Monitoring Service will most likely be the supervision of the services in an OSN (meaning: the service checks whether the monitored services are running and responding or if they are down), it is also possible to monitor any other condition as specified in the capabilities of the monitored service.

10/31


Diagram 3: sample monitoring setup

Diagram 3 gives an example of a small monitored sample OSN. The monitored service on the left may be any ORCHESTRA service. Whether the service must implement the Monitorable Interface depends on the desired monitoring capabilities. In cases where it’s enough to check if the service is running, a simple invocation of any service operation might be enough and no special interface is needed. The monitoring service is an ORCHESTRA service that implements the Service Monitoring Service interface. This is the service where the client configures the monitoring of the OSN and can retrieve statistics about it. The third component in the service monitoring setup is the Alert Service. This service provides a simple interface to the OSN that is (usually) been used by the Monitoring Service. Depending on the configuration, in case of a detected problem the Monitoring Service uses the Alert Service to notify the client. Strictly, the notification of the client is not a mandatory functionality of the Alert Service. As shown in Diagram 3 , the Alert Service may implement any desired behaviour (sending SMSes (Short Message Service) or emails, performing complex and special operations or simply ignoring the notification). This makes it possible for a service operator to add a new kind of special notification to the OSN without having to implement the whole Monitoring Service again, because of this special functionality. It also enables the client to use any combination of Monitored Service/Alert Service e.g.: being notified by ServiceMonitoringService, if a crucial service fails to operate but only by an email, if a less important service fails and a downtime of a few hours or probably days don’t let collapse the whole OSN. The dashed line splitting the Alert Service emphasizes that only the interface is part of ORCHESTRA. The notification mechanism (might be)/is not ORCHESTRA conformant. Of course the Alert Service itself might as well just act as client to any other ORCHESTRA service instead of using other notification techniques.

11/31


Diagram 4: multiple alert services

Diagram 4 shows a sample setup with multiple OSIs and multiple Alert Services. Assume that a Catalogue Service is crucial for the correct functionality of an OSN and there is only one (Note: the monitoring service must be configured beforehand and the corresponding alert service must be hooked to the monitoring properties). A Monitoring Service recognizes that at some point in time the Catalogue Service does not respond anymore. Since this situation breaks the use of the OSN it sends a message using a high priority SMS-Alert service (Short Message Service). This SMS (Short Message Service) will most likely be sent to the Catalogue Service operator so that the OSI can be repaired / restarted as quickly as possible. The second OSI in this OSN is a FAS which actually is a cluster of redundant services in the backend. Let’s assume one of these redundant services failed to work and might reduce the performance a bit, but the full FAS functionality is still available. In this case, the Monitoring Service is informed that something is wrong but it’s not crucial to the OSN and has to be repaired as soon as possible. Therefore the Monitoring Service uses the low priority email-Alert Service.

Many different events (apart from service is running/not running) can be monitored in an OSN. Some examples for such monitorable conditions are hard disk capacity/usage, CPU time usage, concurrent user accesses, and uptime. But what exactly is of interest and should be monitored for a specific OSI can only be known by the service operator. Therefore two things have to be done in order to enable ‘special’ monitoring for an arbitrary OSI 1. list the monitorable properties of the OSI within the service capabilities 2. implement the Monitorable Interface Since the Monitoring Service cannot distinguish a positive state from a negative one the monitored information also must have status information. E.g.: Assume a service whose HDD usage must be monitored. Is 90% of used disk space to be considered critical or already 50%? Only the service operator can answer that question and therefore provides a status flag with this information.

12/31


Another usage for the Monitoring Service is statistical information. This can be used to answer questions about the average downtime of services or their utilization. Some more examples would be current load or concurrent open sessions.

3.2

Service Specification Summary This service type specification of the Service Monitoring Service is comprised of the following interfaces that are defined in separate interface type specifications: •


•

The Monitorable Interface Type

•

The Alert Interface


The Service Monitoring Interface Type

cd Service Monitoring Service «interface» ServiceMonitoringService {abstract} + + + + +

putStatus(source :OA_MonitoringSource, value :Sequence) : void getConfiguration(service :OA_ServiceID[0..1]) : OA_MonitoringConfiguration setConfiguration(config :OA_MonitoringConfiguration) : void getConfigurationSchema() : OA_SchemaDescriptor getStatistics(query :OA_Query) : Sequence

Diagram 5: Class Diagram of the Service Monitoring Service

13/31

Specification of the Service Monitoring Service – Context of the Service Monitoring Service

4 4.1

Context of the Service Monitoring Service Relations to Standards No standard could be found that is applicable to the specification of the Service Monitoring Service. The Service Monitoring Service currently does not qualify for the contribution to a standard.

4.2

Relations to ongoing Initiatives and related Projects The Service Monitoring Service has no immediate relation to ongoing projects.

4.3

Relations to ORCHESTRA Application Schemas The Service Monitoring Interface Type Specification that is specified as integral part of this Service Type Specification uses Basic and OA Types that are defined in the package OAS/Basic Types, OAS/OA Types and OAS-MI/OA-MI Types of the Information Viewpoint. The Service Monitoring Interface Type Specification that is specified as integral part of this Service Type Specification uses standardised non-orchestra Types that are defined in the package, OAS/Imported Types/ Service Monitoring of the Information Viewpoint. The Service Monitoring Interface Type Specification that is specified as integral part of this Service Type Specification uses OA-MI Types that are defined in the package OAS-MI/OA-MI Types of the Information Viewpoint. The Service Monitoring Interface Type Specification that is specified as integral part of this Service Type Specification defines new parameter types. These parameter types are defined the in the package OAS/OA Types of the Information Viewpoint.

4.4

Relations to other ORCHESTRA Service Specifications The Service Monitoring Service might have a slight relation to the Map and Diagram Service (which could be used to produce charts for available statistics). Other than that it does have a relation to the OA Basic Service.

14/31

Specification of the Service Monitoring Service – Requirements

5 5.1

Requirements Security Requirements The Service Monitoring Service has no requirements beyond the scope of the Authentication and Authorisation Service.

5.2

Reliability Requirements The Service Monitoring Service has no special reliability requirements.

15/31

Specification of the Service Monitoring Service – Conformance of Implementation Specifications

6

Specification of the Service Monitoring Interface cd Service Monitoring Service «interface» ServiceMonitoringService {abstract} + + + + +

putStatus(source :OA_MonitoringSource, value :Sequence) : void getConfiguration(service :OA_ServiceID[0..1]) : OA_MonitoringConfiguration setConfiguration(config :OA_MonitoringConfiguration) : void getConfigurationSchema() : OA_SchemaDescriptor getStatistics(query :OA_Query) : Sequence

Diagram 6: Class Diagram of the Service Monitoring Service Interface The Service Monitoring Service Interface defines the following operations:

Operation Name

Description

putStatus

Sends the status for a specific monitored property to the Monitoring service. These values are also used to produce statistics.

getConfiguration

Retrieves the current configuration of the Monitoring Service.

setConfiguration

Sets the configuration for the Monitoring Service.

getConfigurationSchema

Retrieves the schema for the configuration of the Monitoring Service.

getStatistics

Retrieves the statistics for a certain property from the Monitoring Service. Table 1: Summary of operations

6.1

Specification of an OAS Profile of Parameter Types used by the Service Monitoring Service Interface The following non basic types are used within this specification:

Name

Usage

from OAS

New

OA_GetCapabilitiesResponse

O

OA Types

No


I

OA Types

No

OA_MonitoringSource

I

OA Types/Service Monitoring Service

Yes

16/31

Specification of the Service Monitoring Service – Conformance of Implementation Specifications

OA_MonitoringValue

I


Yes

OA_MonitoringStatus

I


Yes

OA_StatisticalDataValue

O


Yes

OA_ServiceID

I


Yes

OA_MonitoringConfiguration

I&O


Yes

OA_SchemaDescriptor

O

OA Types

No

OA_QueryLanguage

I

OA Types

No


E


No


E


No


E


No


E


No

OA_NoApplicableCode

E


No

OA_InternalError

E


No


17/31

Specification of the Service Monitoring Service – Specification of the putStatus Operation

6.2 6.2.1

Specification of the Operations Specification of the putStatus Operation The optional putStatus operation allows any service to use a push model for the monitoring. This means that the values that are used for monitoring certain properties of the service are actively sent to the Service Monitoring Service by the monitored service. This monitored service is identified by the source parameter. The value parameter contains a list of monitoring values that are sent to the service. These values will be checked whether a notification must be sent (using the Alert Service) as well as statistics will be computed if this ServiceMonitoringService supports this feature. If the ServiceMonitoringService has not been configured, no notifications will be sent for any monitoring values, even those that are marked as CRITICAL. The signatures of the operation is void putStatus ( OA_MonitoringSource, Sequence ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError

Overrides

not applicable

Preconditions

None

Post conditions

None

Use

Optional

Receives

Name

source

value

Type

OA_MonitoringSource

Sequence

Use

Description

mandatory

Specifies the service that sends the monitoring data to the ServiceMonitoringService.

mandatory

List of monitoring values that were produced by the monitored service.

Returns

Type

Description

Throws

Type



18/31

Specification of the Service Monitoring Service – Specification of the putStatus Operation



OA_NoApplicableCode


OA_InternalError


Table 3: Specification of the putStatus Operation

19/31

Specification of the Service Monitoring Service – Specification of the getConfiguration Operation

6.2.2

Specification of the getConfiguration Operation The mandatory getConfiguration operation retrieves the current configuration of the Service Monitoring Service. This configuration contains either the current configuration for a specific monitored service or for the Service Monitoring Service itself. The information about a monitored service should (among other probably available optional entities) contain the Alert Services that must be used for CRITICAL monitoring values (and possibly the other states), if the monitored service should be polled for its monitoring data and so forth. The signatures of the operation is OA_MonitoringConfiguration getConfiguration ( OA_ServiceID ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

mandatory

Receives

Name

service

Returns

Type

OA_ServiceID

optional

Type OA_MonitoringConfiguration

Throws

Use

Description Specifies the service whose configuration should be retrieved. If this parameter is omitted the configuration of the Service Monitoring Service itself is returned. Description

The currently active configuration of the specified service.

Type

Cause





OA_NoApplicableCode


OA_InternalError


Table 4: Specification of the getConfiguration Operation

20/31

Specification of the Service Monitoring Service – Specification of the setConfiguration Operation

6.2.3

Specification of the setConfiguration Operation The mandatory setConfiguration operation sets the configuration for either a monitored service or the monitoring service itself. This option is implicitly specified through the existence of the service parameter. The signatures of the operation is void setConfiguration ( OA_ServiceID, OA_MonitoringConfiguration ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

mandatory

Receives

Name

service

config

Type

Use

OA_ServiceID

OA_MonitoringConfiguration

Description

optional

Specifies the service whose configuration should be set. If this parameter is omitted the configuration of the Service Monitoring Service itself is set.

mandatory

The configuration that must be set as current configuration for the specified service.

Returns

Type

Description

Throws

Type

Cause





OA_NoApplicableCode


OA_InternalError


Table 5: Specification of the setConfiguration Operation

21/31

Specification of the Service Monitoring Service – Specification of the getConfigurationSchema Operation

6.2.4

Specification of the getConfigurationSchema Operation The mandatory getConfigurationSchema operation retrieves the schema that defines the structure of the OA_MonitoringConfiguration type. The signatures of the operation is OA_SchemaDescriptor getConfigurationSchema ( ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

mandatory

Receives

Returns

Name

Type


Throws

Use

Description

Description The schema descriptor of the service’s configuration.

Type

Cause





OA_NoApplicableCode


OA_InternalError



22/31

Specification of the Service Monitoring Service – Specification of the getStatistics Operation

6.2.5

Specification of the getStatistics Operation The optional getStatistics operation retrieves a list of statistical values. These values are features so they could be sent to a Map and Diagram Service to produce a chart. In that way it’s very easy and convenient to produce graphs for working loads of services or a chart of the maximum downtime of every service. The signatures of the operation is Sequence getStatistics ( OA_Query ) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError

Overrides

Not applicable

Preconditions

None

Postconditions

None

Use

Optional Name

Type

query

OA_Query

Receives

Returns

Throws

Use

Description

Required

Specifies the query to be used to fetch the statistical data.

Type

Description

Sequence

A list of statistical data is returned from the request.

Type

Cause





OA_NoApplicableCode

No other basic or service-specific exception type applies. A problem occurred in the runtime environment (e.g., out of memory).

OA_InternalError

Table 7: Specification of the getStatistics Operation

23/31

Specification of the Service Monitoring Service – OA_MonitoringSource

6.3

Specification of Parameter Types This service specification does define new OA Types. These new OA Types will become part of the OAS “OA Types” This service specification does not define any new OT Types. This service specification does not introduce any new non-orchestra Types.

6.3.1

OA_MonitoringSource The OA_MonitoringSource type is used to specify a monitored service along with a responsible party for this service. This information is used to link a provided monitoring value with the producing service. Note: This is NOT the responsible that must be notified by the alert service. cd Service Monitoring Service «type» OA_MonitoringSource -

source: OA_ServiceID contact: OA_MI_ResponsibleParty

Diagram 7: Class diagram of OA_MonitoringSource

6.3.2

OA_MonitoringValue An OA_MonitoringValue is the type for all monitored properties of a service. Disk-usage, uptime and all other properties can be specified with this type since the value is of type any. The timestamp specifies the exact date and time when this value was produced at the monitored service. As additional information it contains an OA_MonitoringProperty field that specifies the property to which this value is linked to as well as an OA_MonitoringStatus which will be used by the Service Monitoring Service to invoke the alert operation at an Alert Service, if such, a hook has been specified using the ServiceMonitoringService’s configuration possibilities.

24/31

Specification of the Service Monitoring Service – OA_MonitoringProperty cd Service Monitoring Service - OA Types «type» OA_MonitoringValue -

-

value: Any timestamp: DateTime schema: OA_SchemaDescriptor

«type» OA_MonitoringProperty

«enumeration» OA_MonitoringStatus

name: CharacterString description: CharacterString

enum + OK: + WARNING: + CRITICAL: + N/A:

Diagram 8: Class diagram of OA_MonitoringValue

6.3.3

OA_MonitoringProperty The OA_MonitoringProperty specifies a monitorable entity/property of a service (e.g.: disk usage), using a name and a description. cd Service Monitoring Service... «type» OA_MonitoringProperty -

name: CharacterString description: CharacterString

Diagram 9: Class diagram of OA_MonitoringProperty

6.3.4

OA_MonitoringConfiguration There are numerous parameters that need to be configured at the Service Monitoring Service. Among these are the Alert services that need to be hooked to the different states of monitoring values for every monitored service, the interval between the invocations of the operations of the monitored service if the pull-model is implemented, configuration for the statistical data handling part of the ServiceMonitoringService and others. The schema for the actual configuration type at a specific OSI can be retrieved from the service.

25/31

Specification of the Service Monitoring Service – OA_ServiceID cd Service Monitoring Servic... «type» OA_MonitoringConfiguration -

configuration: Any

Diagram 10: Class diagram of OA_MonitoringConfiguration

6.3.5

OA_ServiceID The OA_ServiceID type is used to uniquely identify an OSI within an OSN. An URI is used as id for each service. cd Service Mo... «type» OA_ServiceID -

id: OA_URI

Diagram 11: Class diagram of OA_ServiceID 6.3.6

OA_Statistics The OA_Statistics type is used mainly in the ServiceMonitoringService service capabilities in order to depict the available statistical data that the ServiceMonitoringService can produce. These values can be used in the query to the getStatistics operation. It consists of a name and a description. cd Service Monitoring Service... «type» OA_Statistics -


Diagram 12: Class diagram of OA_Statistics 6.3.7

OA_StatisticalDataValue The OA_StatisticalDataValue type is used to describe a single statistical property. It can either be a result value of a calculation based on the monitoring values that are processed at this ServiceMonitoringService (e.g.: the average load of a monitored service) or the monitoring values themselves (e.g.: the load at a specific point in time). The OA_StatisticalDataValue type is a feature type therefore all instances of this type are features. These could then be sent to a Map and Diagram Service in order to produce charts of graphs of the statistics.

26/31

Specification of the Service Monitoring Service – OA_StatisticalDataValue cd Service Monitoring Service - O... «FeatureType» OA_StatisticalDataValue -

value: Any schema: OA_SchemaDescriptor

«type» OA_Statistics -


Diagram 13: Class diagram of OA_StatisticalDataValue

27/31

Specification of the Service Monitoring Service –

7

Specification of the Service specific Capabilities As part of ORCHESTRA D3.3.2 a meta-information schema for services is defined acting as a default OAS-MI for service capabilities. OA_MI_CapabilitiesDocument includes both the common capabilities and the service specific capabilities. While the common capabilities are defined in the specification of the Service Capabilities Interface, the specific capabilities have to be specialized in each service specification. The schema for service specific capabilities defined here is explicitly divided into the following schema sections:

Section Name

Section Contents

SMSCapabilities

Contains schemas for the additional OA Types as well as information about statistical capabilities.

monitorableCapabilities

This section contains the information that is needed for proper monitoring of this service.

alertCapabilities

Specifies the specific capabilities for an Alert Service. Table 8: Sections of the service specific capabilities

Name

Definition

Data Type

availableStatistics

List of available statistics that can be retrieved from the Service Monitoring Service.

OA_Statistics


Lists which query languages are supported by the service.

OA_QueryLanguage

Multiplicity and Use 0..* Optional 1..* mandatory

Table 9: Attributes of the service specific capabilities of section SMSCapabilities

Name

properties

Definition

Data Type

A list of all properties that can be monitored at this service.

Sequence

Multiplicity and Use 0..* Mandatory

Table 10: Attributes of the service specific capabilities of the sections monitorableCapabilities

Name

destinationSchema

Definition

Data Type

Specifies the exact schema for the OA_AlertDestination type.

OA_SchemaDesciptor

Multiplicity and Use 1 Mandatory

Table 11: Attributes of the service specific capabilities of section alertCapabilities

28/31

Specification of the Service Monitoring Service –

8


29/31

Specification of the Service Monitoring Service – Appendix A: Abstract Test Suite (normative)

9

Appendix A: Abstract Test Suite (normative) When creating an implementation specification of the Service Monitoring Service, the “Rules for Implementation Specifications of ORCHESTRA Services” defined in chapter 9.2.2.3 and the “Rules for the Service Mapping to a given Platform” of the RM-OA shall be obeyed. In addition, the following tests shall be performed to ensure conformance of an implementation specification to the platform-independent specification of the Service Monitoring Service: 1. Syntactical Conformance •


•


•


•




Additional conformance checks that are specifically to the Service Monitoring Service are not required.

30/31

Specification of the Service Monitoring Service – Appendix B: UML Models (normative)


31/31




Specification of the User Management Service

Revision

1/39

[1.8 / 2.2.2]

Specification of the User Management Service – Document Control Page


Specification of the User Management Service

Creator

Fischer, Julian, EIG

Subject


Description

This document defines an abstract and platform independent formal specification of the User Management Service.

Publisher


Contributor

Julian Fischer,

EIG

Wenjie Ma,

EIG

Thomas Hofmann,

EIG

Date

2006-05-29

Type

Text

Format

application/msword

Identifier


Source

Not applicable

Language

en-GB.

Relation

none

Coverage



D3.4.3


WP3.4


2006-07-30


2006-08-15

Audience


Version number

1.8 / 2 2.2

Date

2007-10-08

Modified by

Wenjie Ma, EIG

Comments Status


2/39

Specification of the User Management Service – Document Control Page



3/39

Specification of the User Management Service – Revision History


Date

Sections changed

Description st

1.0

2006-01-31

all

1 release

1.1

2006-02-05

all

Linguistic adjustments

1.2

2006-02-06

all

Processed input from IITB

1.3

2006-05-29

4 Service Interface Specification

Subject credentials removed

1.4

2006-05-30

all

Update to template 2.0.4

1.5

2006-06-19

6.4

Specification of additional Types extended.

1.5.1

2006-08-03

all

Mainly renaming of types, updating of diagrams

1.5.2

2006-08-14

6.3

Addition of capabilities

1.5.4

2006-08-19

6.3

Edits to capabilities

1.5.5/2.0.6

2006-08-22

some

Adapted template-version.

1.6 / 2.0.6

2006-08-28

none

Accepted/rejected final edits and comments

1.6.1

2006-10-18

3.2, 6.2, 6.2.1, 6.2.4

Added return value for createGroup and createSubject

1.6.2

2007-01-10

All

Minor changes

1.7

2007-01-22

All

Updated description of deleteSubject operation. Updated return types for operations returning a collection.

1.8 / 2.2.2

2007-10-08

all

Minor changes, update to new template

4/39

Specification of the User Management Service – Table of Contents

Table of Contents 1

Foreword..................................................................................................................................................... 8

2

Conventions ................................................................................................................................................ 9

3

2.1

Abbreviations ....................................................................................................................................... 9

2.2


2.3

UML Notation....................................................................................................................................... 9

2.4

Conformance ....................................................................................................................................... 9

2.4.1


2.4.2



3.1.1

Subjects and Principals .............................................................................................................. 10

3.1.2

Groups........................................................................................................................................ 10

3.1.3

Services...................................................................................................................................... 11

3.1.4

Service-chains............................................................................................................................ 11

3.2 4

5

Role and Scope of the User Management Service ........................................................................... 10


Context of the User Management Service................................................................................................ 13 4.1


4.2


4.3


4.4


4.4.1

Authentication Service................................................................................................................ 13

4.4.2

Authorisation Service ................................................................................................................. 13

4.4.3

Feature Access Service ........................................................ Fehler! Textmarke nicht definiert.

Requirements ........................................................................................................................................... 14 5.1


5.2


5.2.1 6

Referential Integrity .................................................................................................................... 14

Specification of the User Management Interface...................................................................................... 15 6.1

Specification of an OAS Profile of Parameter Types used by the User Management Interface....... 16

6.2


6.2.1

Specification of the createSubject Operation............................................................................. 17

6.2.2

Specification of the deleteSubject Operation ............................................................................. 18

5/39

Specification of the User Management Service – Table of Contents 6.2.3

Specification of the updateSubject Operation ............................................................................ 20

6.2.4

Specification of the createGroup Operation ............................................................................... 21

6.2.5

Specification of the deleteGroup Operation ............................................................................... 22

6.2.6

Specification of the updateGroup Operation .............................................................................. 23

6.2.7

Specification of the addPrincipalToGroup Operation................................................................. 24

6.2.8

Specification of the removePrincipalFromGroup Operation....................................................... 25

6.2.9

Specification of the getSubjects Operation ................................................................................ 27

6.2.10

Specification of the getGroups Operation .................................................................................. 28

6.2.11

Specification of the addPrincipalToSubject Operation............................................................... 29

6.2.12

Specification of the removePrincipalFromSubject Operation..................................................... 31

6.3


6.3.1

OA_Subject ................................................................................................................................ 33

6.3.2

OA_SubjectAttributes ................................................................................................................. 33

6.3.3

OA_Principal .............................................................................................................................. 34

6.3.4

OA_Group .................................................................................................................................. 34

6.3.5

OA_NoSuchMemberException .................................................................................................. 34

6.3.6

OA_ReferentialIntegrityException .............................................................................................. 34

6.3.7

OA_SubjectNotFoundException ................................................................................................ 34

6.3.8

OA_PrincipalNotFoundException............................................................................................... 34

7


8

Known Issues and Limitations .................................................................................................................. 37 8.1.1

9

OA_ServiceChainAuthenticationMode....................................................................................... 37



XMI Model ...................................................................................................................................... 39

6/39

Specification of the User Management Service – Tables and Diagrams

Tables Table 1: Summary of operations...................................................................................................................... 16 Table 2: Referenced OA Types ....................................................................................................................... 16 Table 3: Specification of the createSubject Operation..................................................................................... 17 Table 4: Specification of the deleteSubject Operation..................................................................................... 19 Table 5: Specification of the updateSubject Operation ................................................................................... 20 Table 6: Specification of the createGroup Operation....................................................................................... 21 Table 7: Specification of the deleteGroup Operation....................................................................................... 22 Table 8: Specification of the updateGroup Operation...................................................................................... 23 Table 9: Specification of the addPrincipalToGroup Operation ........................................................................ 24 Table 10: Specification of the removePrincipalFromGroup Operation ............................................................ 26 Table 11: Specification of the getSubjects Operation...................................................................................... 27 Table 12: Specification of the getGroups Operation........................................................................................ 28 Table 13: Specification of the addPrincipalToSubject Operation .................................................................... 30 Table 14: Specification of the removePrincipalFromSubject Operation .......................................................... 32 Table 15: Sections of the service specific capabilities..................................................................................... 36

Diagrams Diagram 1: Class diagram of the User Management Service ......................................................................... 12 Diagram 2: Class diagram of the User Management Interface ....................................................................... 15 Diagram 3: Connection between OA_Subject and OA_SubjectAttributes....................................................... 33 Diagram 4: Class diagram of OA_Group ......................................................................................................... 34 Diagram 5: New exceptions in the User Management Interface ..................................................................... 35 Diagram 6: User Mangement Service specific capabilities.............................................................................. 36 Diagram 7: Class diagram of OA_ServiceChainAuthenticationMode.............................................................. 37

7/39

Specification of the User Management Service – Foreword

1

Foreword This document is an abstract specification of the User Management Service and is based on the Template for the abstract Specification of ORCHESTRA Service Types version 2.2.2. It updates the specification version 2.0.6. An update of was required to accommodate the changes of the new service templates. This document includes two annexes: Appendix A: Abstract Test Suite (normative) is mandatory and Appendix B: UML Models (normative) is optional.

8/39

Specification of the User Management Service – Conventions

2

Conventions

2.1


2.2


2.3


2.4 2.4.1


2.4.2


9/39

Specification of the User Management Service – Overview and Architecture Outline

3


3.1

Role and Scope of the User Management Service The ORCHESTRA user management mainly defines an abstract user concept needed for authentication and authorisation purposes. As defined in the UAA terminology the term user is knowingly avoided. This is because the general understanding of the term conflicts with ORCHESTRA’s UAA requirements. Commonly a user is considered to be a human person. Even if ORCHESTRA has redefined the term in a broader meaning, there is still a large potential for conflict. Thus, the UAA terminology uses the term subject. According to the associated impersonal sound, a subject can not only be a person but, among others, a service, a group as well as a service chain.

3.1.1

Subjects and Principals Subjects represent entities that need to be authenticated. They are not authenticated themselves but rather represent a point of contact and management feature for authentication and authorisation purposes. As mentioned in the context of the authentication, a subject itself cannot be used for authentication purposes. This is mainly because ORCHESTRA aims at supporting multiple authentication paradigms and mechanisms. The potentially simultaneous use leads to a number of implications. Different authentication mechanisms e.g. use different user representations. Thus, a single subject representation can not be chosen for ORCHESTRA. To solve the representation problem, a subject is decoupled from authentication. This decoupling is done by separating principals from subjects. A principal is an identity of a subject and is defined in an Authentication Service instance. As an example consider an Authentication Service instance wrapping an existing Kerberos authentication. Usually a Kerberos implementation ships with a user management. A user in the Kerberos user management becomes an ORCHESTRA principal. This principal then will be associated with the corresponding subject. Principals are created in instances of Authentication Services. A subject may be associated with principals in arbitrary Authentication Service instances. The process of creating a new principal depends on the authentication mechanism used by the corresponding Authentication Service instance. Thus, the creation of a principal is done using the Authentication Service interface. Delegating this process to the User Management is therefore not possible. Subjects can have attributes to contain information about them. These attributes can be used to organise the subject’s service invocations. Consider, e.g. a subject may have five different principals to access five different services. If the subject wants to invoke these services, it has to know which service needs which principal to be authenticated. This mapping could be stored as an attribute of this subject.

3.1.1.1

Referencing Principals

In the UAA concept principals need to be referenced. Group memberships, association to subjects as well as permissions depend on references to principals. Therefore, principal references need to be unique. 3.1.2

Groups A group is a special subject. Thus, a group can have one or more principals (group principals). In addition to principals identifying the group itself a group can have one or more principals as members (member principals).

10/39

Specification of the User Management Service – Overview and Architecture Outline A group principal can be treated as an ordinary subject by Authorisation Service instances. Therefore, assigning permissions to a group does not differ from assigning permissions to any other subject. Member principals are assigned to a group to define memberships of certain principals. 3.1.2.1

Why Groups consist of Principals and not of Subjects

Principals are implicitly associated with defined authentication mechanisms. Thus, a user management administrator can implicitly choose the authentication mechanisms of the group’s members. He only adds trustworthy principals. A principal is considered trustworthy if it has been authenticated by an authentication mechanism which is trustworthy enough. If an authentication mechanism is trustworthy depends on the security requirements associated with the corresponding group. The group authentication is knowingly different from the authentication of individual principals. Individual principals have knowledge about some kind of secrets. They have to proof this knowledge about the secret during the authentication process. If a group had a secret, every member would need to know it in order to act as a member of the group. Removing a member of the group would raise the need to change the group’s common secret. Otherwise a former member would still be able to act as a group member. Changing the secret would also mean to update or notify other group members. This problem is completely avoided by the following method of group authentication. Authentication of groups is done in two steps. A principal demanding to act with a group principal has to authenticate one of its own principals, first. After authenticating the principal is checked whether the principal is a member of the demanded group. 3.1.2.2

Why ORCHESTRA needs Groups

From the functional point of view there is no need for groups. Group concepts generally provide a convenient method for structuring and facilitating administrative tasks related to subjects. One of important purpose of groups in ORCHESTRA is the usage in the context of an Authorisation Service. Groups can facilitate the assignment of permissions to principals. More than that, it can help to outsource limited permission assignment. As described before permissions are generally bound to principals. Consider a scenario where a Format Conversion Service instance and a Document Access Service instance need to be used by eight principals from various Authentication Service instances. Without groups each service instance would need to add corresponding rights to each of the eight principals (excluding possible grouping mechanisms in the Authorisation Services themselves. In contrast to that, any User Management instance may be used to create a group, adding the eight principals as members. Now, it is sufficient to add the permissions to the group’s principal in both services. 3.1.3

Services Services are treated as individual subjects. They can thus have one or more principals. Service providers may assign permissions to those principals just like to any other subject.

3.1.4

Service-chains The access to a service-chain is provided by a specialised service, therefore there is no difference to any other service invocation.

3.2

Service Specification Summary This service type specification of the User Management Service is comprised of the following interface that is defined in a separate interface type specification: •

The Service Capabilities Interface

11/39

Specification of the User Management Service – Overview and Architecture Outline


The User Management Interface Type

cd User Management Serv ice ServiceCapabilities UserManagementInterface «interface» UserManagementService + + + + + + + + + + + + +

addPrincipalToGroup(OA_Principal, OA_Group) : void addPrincipalToSubject(OA_Subject, OA_Principal) : void createGroup(OA_Group) : OA_Group createSubject(OA_Subject) : OA_Subject deleteGroup(OA_Group) : void deleteSubject(OA_Subject) : void getCapabilities(OA_GetCapabilitiesRequest) : OA_CapabilitiesDocument getGroups(OA_Query) : Sequence getSubjects(OA_Query) : Sequence removePrincipalFromGroup(OA_Principal, OA_Group) : void removePrincipalFromSubject(OA_Principal, OA_Subject) : void updateGroup(OA_Group) : void updateSubject(OA_Subject) : void

Diagram 1: Class diagram of the User Management Service

12/39

Specification of the User Management Service – Context of the User Management Service

4

Context of the User Management Service

4.1

Relations to Standards The concept of separating subjects and principals has been taken from the Java Authentication and Authorization Service (JAAS) API. RFC 4519 Lightweight Directory Access Protocol (LDAP): Schema for User Applications LDAP is widely spread in current identity management systems. Similar to the User Management Service these identity management systems need to store user profiles (Subject Attributes). The RFC 4519 is part of a set of LDAP RFC standard and contains schemas describing object classes including their attributes. These object classes can serve as a template for the definition of subject attribute types. A User Management Service supporting Subject Attributes compatible to LDAP core schemas could easily use LDAP as a data backend. This could facilitate integration of existing identity management systems into ORCHESTRA.

4.2

Relations to ongoing Initiatives and related Projects The User Management Service has no immediate relation to ongoing projects.

4.3

Relations to ORCHESTRA Application Schemas The User Management Interface Type Specification that is specified as integral part of this Service Type Specification uses Basic and OA Types that are defined in the package OAS/Basic Types, OAS/OA Types and OAS-MI/OA-MI Types of the Information Viewpoint. The User Management Interface Type Specification that is specified as integral part of this Service Type Specification defines new parameter types. These parameter types are defined the in the package OAS/OA Types/«Application Schema» Usermanagement Service Exceptions, OAS/OA Types/ «Application Schema» Usermanagement Service Types of the Information Viewpoint.

4.4 4.4.1

Relations to other ORCHESTRA Service Specifications Authentication Service Accessing a User Management Service instance will need authenticated principals in the context of authorisation.

4.4.2

Authorisation Service In order to prevent arbitrary subjects to invoke freely operations on a User Management Service instance the usage of an authorisation service instance will be needed.

13/39

Specification of the User Management Service – Requirements

5

Requirements

5.1

Security Requirements The User Management Service has no requirements beyond the scope of the Authentication and Authorisation Service.

5.2 5.2.1

Reliability Requirements Referential Integrity Operations triggering the deletion or update of further data should be implemented using transactions. This is has special meaning for the following operations: •

deleteSubject The deletion of a subject can include the deletion of all registered principals. Deletion of principals is done using responsible Authentication Services. If the deletion can not be completed no principal shall be deleted. Since a User Management Service instance does not necessarily have permissions to delete principals in remote Authentication Service instances, future versions of Usermanagement and Authentication Services could communication using notifications. Once a principal should be deleted, the User Management Service sends a notification to all Authentication Services involved. Authentication Services may then decide whether to delete the corresponding principals.

•

deleteGroup This is analogous to the operation deleteSubject. The deletion of a group subject can include the deletion of the group’s principals. Deletion of group principals is done using responsible Authentication Services. If the deletion can not be completed no principal shall be deleted. Since a group in additional to ordinary subjects associations to principals (group members) these associations should not be affected as well if an error occurs.

14/39

Specification of the User Management Service – Specification of the User Management Interface

6

Specification of the User Management Interface cd User Management Interface «interface» UserManagementInterface + + + + + + + + + + + +

addPrincipalToGroup(OA_Principal, OA_Group) : void addPrincipalToSubject(OA_Subject, OA_Principal) : void createGroup(OA_Group) : OA_Group createSubject(OA_Subject) : OA_Subject deleteGroup(OA_Group) : void deleteSubject(OA_Subject) : void getGroups(OA_Query) : Sequence getSubjects(OA_Query) : Sequence removePrincipalFromGroup(OA_Principal, OA_Group) : void removePrincipalFromSubject(OA_Principal, OA_Subject) : void updateGroup(OA_Group) : void updateSubject(OA_Subject) : void

Diagram 2: Class diagram of the User Management Interface The User Management Interface defines the following operations:

Operation Name

Description

createSubject

Creates a subject. After a subject has been created, at least one principal has to be created and associated with the subject.

deleteSubject

Deletes a subject including the deletion of all associated principals.

updateSubject

Updates the subject itself. Can be used to change subject related information, e.g. subject attributes.

createGroup

Creates a group. Groups contain principals, not subjects.

deleteGroup

Deletes a group without deleting the principals.

updateGroup

Updates the group itself. Can be used to change group related information, e.g. group attributes.

addPrincipalToSubject

Associates an existing principal to an existing subject.

removePrincipalFromSubject

Removes an association between a given principal and subject.

getSubjects

Enumerates all subjects of the current service instance.

getGroups

Enumerates all group subjects of the current service instance.

removePrincipalFromGroup

Removes the association between a given principal and a given group.

addPrincipalToGroup

Associates an existing group with an existing principal. The principal may reside in another User Management Service instance.

15/39

Specification of the User Management Service – Specification of the User Management Interface Table 1: Summary of operations

6.1

Specification of an OAS Profile of Parameter Types used by the User Management Interface The following non basic types are used within this specification:

Name

Usage

from OAS

New

OA_MI_CapabilitiesDocument

O

OA MI Types

No


I

OA Types

No

OA_Subject

I/O

OA Types

Yes

OA_Principal

I/O

OA Types

No

OA_SubjectAttributes

I/O

OA Types

Yes

OA_KeyValueSubjectAttributes

I/O

OA Types

Yes

OA_Group

I/O

OA Types

Yes

OA_OSI_Identifier

I/O

OA Types

No

OA_NoSuchMemberException

E

OA Types/Exceptions Types

Yes

OA_ReferentialIntegrityException

E


Yes

OA_SubjectNotFoundException

E


Yes


E


Yes


E


No


E


No

OA_NoApplicableCode

E


No

OA_InternalError

E


No


E


No


16/39


6.2 6.2.1

Specification of the Operations Specification of the createSubject Operation The mandatory createSubject operation is used to add new subjects. Note that the creation of a subject is not sufficient to invoke a service. To do so, a principal has to be created and registered with the corresponding subject. After this has been done, a service provider may grant permissions to the principal. The signatures of the operation is OA_Subject createSubject (OA_Subject) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PermissionDeniedException

Overrides

Not applicable

Preconditions

none

Post conditions

none

Use

mandatory

Receives

Name subject

Returns

Type OA_Subject

mandatory

Type

Description Subject to be created. Description

The created Subject including a recently added unqiue id (unqie within the service) that can be used for a latter reference to this subject.

OA_Subject Throws

Use

Type

Cause


Operati on request contains an invalid parameter value.


Operation request does not include a parameter value.

OA_NoApplicableCode


OA_InternalError




Table 3: Specification of the createSubject Operation

17/39


6.2.2

Specification of the deleteSubject Operation The mandatory deleteSubject operation is used to delete subjects. Deleting a subject means to completely delete the subject from ORCHESTRA. In order to keep overall consistency this should include deletion of all principals as well as credentials, memberships to groups and subject attributes associated with the corresponding subject. Note that a subject’s membership to a group is realised by adding one of its principals as a group member to the corresponding group subject. The signatures of the operation is void deleteSubject (OA_Subject) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_ReferentialIntegrityException, OA_SubjectNotFoundException, OA_PermissionDeniedException

Overrides

Not applicable

Preconditions

Subject to be deleted exists

Post conditions

To keep a consistent state overall ORCHESTRA this operation should be atomic. It is either executed completely or not at all. Otherwise there could remain principals without corresponding subjects.

Use

mandatory

Receives

Name subject

Returns

Type OA_Subject

Use mandatory

Description Subject to delete.

Type

Description

Type

Cause

void Throws


Operation request contains an invalid parameter value.



OA_NoApplicableCode


OA_InternalError


OA_ReferentialIntegrityException

Thrown if at least one subject related feature (e.g. a principal) cannot be deleted.


Thrown if the subject to be deleted does not exist.

18/39




Table 4: Specification of the deleteSubject Operation

19/39


6.2.3

Specification of the updateSubject Operation The mandatory updateSubject operation is used to update subjects as well as related information like subject attributes. The signatures of the operation is void updateSubject (OA_Subject) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_SubjectNotFoundException, OA_PermissionDeniedException

Overrides

not applicable

Preconditions

Subject to be updated exists

Post conditions

none

Use

mandatory

Receives

Name subject

Returns

Type OA_Subject

Use mandatory

Description Subject to be updated.

Type

Description

Type

Cause

void Throws





OA_NoApplicableCode


OA_InternalError



Thrown if the subject to be updated does not exist.



Table 5: Specification of the updateSubject Operation

20/39


6.2.4

Specification of the createGroup Operation The mandatory operation is used to create new group subjects. Members of a group are principals not subjects. As groups themselves are special subjects, they can have one ore more principals on their own. Again, groups have two associations to principals. First, members of groups are principals. Second, groups have principals like ordinary subjects. The latter is needed that a service provider may grant permissions to a group. Since permissions are generally bound to principals, they can also be bound to group principals. The signatures of the operation is OA_Group createGroup (OA_Group) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_PermissionDeniedException

Overrides

not applicable

Preconditions

None

Post conditions

Principals have to be added.

Use

mandatory

Receives

Name

Type

groupSubject Returns

OA_Group

mandatory

Type

Description Group to be added Description

The created group including a recently added id (unique within the service) that can be used for a latter reference to this group.

OA_Group Throws

Use

Type

Cause





OA_NoApplicableCode


OA_InternalError




Table 6: Specification of the createGroup Operation

21/39


6.2.5

Specification of the deleteGroup Operation The mandatory deleteGroup operation is used to delete group subjects. Deletion affects only the groups own principals and the membership of added user principals. No principals of members are deleted. The signatures of the operation is void deleteGroup (OA_Group) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_SubjectNotFoundException, OA_PermissionDeniedException

Overrides

Not applicable

Preconditions

Group must exist

Post conditions

none

Use

mandatory

Receives

Name

Type


OA_Group

Use mandatory

Description Group to be deleted

Type

Description

Type

Cause

void Throws





OA_NoApplicableCode


OA_InternalError



Thrown if the group subject to be deleted does not exist.



Table 7: Specification of the deleteGroup Operation

22/39


6.2.6

Specification of the updateGroup Operation The mandatory updateGroup operation is used to update group subjects. The signatures of the operation is void updateGroup (OA_Group) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_SubjectNotFoundException, OA_PermissionDeniedException

Overrides

not applicable

Preconditions

Group has to exist.

Post conditions

none

Use

mandatory

Receives

Name

Type


OA_Group

Use mandatory

Description Group to be updated

Type

Description

Type

Cause

void Throws


Operation request contains an invalid parameter value



OA_NoApplicableCode


OA_InternalError



Group to be updated does not exist.



Table 8: Specification of the updateGroup Operation

23/39


6.2.7

Specification of the addPrincipalToGroup Operation The mandatory addPrincipalToGroup operation is used to add an existing principal to a group subject in a User Management Interface. The principal can be part of any ORCHESTRA Authentication Service instance. The signatures of the operation is void addPrincipalToGroup (OA_Principal, OA_Group) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_SubjectNotFoundException, OA_PrincipalNotFoundException, OA_PermissionDeniedException

Overrides

not applicable

Preconditions

Group has to exist. Principal has to exist

Post conditions

Principal may not be deleted without notification of the User Management Interface containing the group.

Use

mandatory

Receives

Name

Type

Use

Description

principal

OA_Principal

mandatory

Principal to be added to the group.

groupSubject

OA_Group

mandatory

Group to be updated.

Returns

Type

Description

Type

Cause

void Throws





OA_NoApplicableCode


OA_InternalError



Group does not exist.


Principal to be added to the group does not exist.



Table 9: Specification of the addPrincipalToGroup Operation

24/39


6.2.8

Specification of the removePrincipalFromGroup Operation The mandatory removePrincipalFromGroup operation is used to remove an existing principal from an existing group subject. The principal can be part of any ORCHESTRA Authentication Service instance. The principal itself gets not deleted. The signatures of the operation is void removePrincipalFromGroup (OA_Principal, OA_Group) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_SubjectNotFoundException, OA_PrincipalNotFoundException, OA_NoSuchMemberException, OA_PermissionDeniedException

Overrides

not applicable

Preconditions

Group has to exist. Principal has to exist. Principal has to be member of the group.

Post conditions

none

Use

mandatory

Receives

Name

Type

Use

Description

Principal

OA_Principal

Mandatory

Principal to be removed from the group.

group

OA_Group

mandatory

Group from where the principal should be removed.

Returns

Type

Description

Type

Cause

void Throws





OA_NoApplicableCode


OA_InternalError






OA_NoSuchMemberException

Principal to be removed is not a member of the given group.

25/39




Table 10: Specification of the removePrincipalFromGroup Operation

26/39


6.2.9

Specification of the getSubjects Operation The mandatory getSubjects operation is used to retrieve specified subjects. The signatures of the operation is Sequence getSubjects (OA_Query) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_SubjectNotFoundException, OA_PermissionDeniedException

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

mandatory

Receives

Name query

Returns

Type

Use

OA_Query

optional

Type Sequence

Throws

Description Query specifying subjects to be retrieved. Description

A list of subjects selected by the given query.

Type

Cause





OA_NoApplicableCode


OA_InternalError



No subjects match the query..



Table 11: Specification of the getSubjects Operation

27/39


6.2.10 Specification of the getGroups Operation The mandatory getGroups operation is used to retrieve specified groups. The signatures of the operation is Sequence getGroups (OA_Query) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_SubjectNotFoundException, OA_PermissionDeniedException

Overrides

not applicable

Preconditions

none

Post conditions

none

Use

mandatory

Receives

Name query

Returns

Type

Use

OA_Query

optional

Type Sequence

Throws

Description Query specifying groups to be retrieved. Description

A list of groups selected by the given query.

Type

Cause





OA_NoApplicableCode


OA_InternalError



No subjects match the query..



Table 12: Specification of the getGroups Operation

28/39


6.2.11 Specification of the addPrincipalToSubject Operation The mandatory addPrincipalToSubject operation is used to add an existing principal to an existing subject. The principal can be part of any ORCHESTRA Authentication Service instance. Note that a group is also a subject. Thus, this operation can also be used to add principals to a group. This operation cannot be used to add principals as a member to a group. The signatures of the operation is void addPrincipalToSubject (OA_Principal, OA_Subject) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_SubjectNotFoundException, OA_PrincipalNotFoundException, OA_PermissionDeniedException

Overrides

not applicable

Preconditions

Subject has to exist. Principal has to exist.

Post conditions

Principal may not be deleted without notification of the User Management Interface containing the group.

Use

mandatory

Receives

Name

Type

Use

Description

principal

OA_Principal

mandatory

Principal to be added to the given subject.

subject

OA_Subject

mandatory

Subject to which a principal should be added.

Returns

Type

Description

Type

Cause

void Throws





OA_NoApplicableCode


OA_InternalError








29/39

Specification of the User Management Service – Specification of the User Management Interface Table 13: Specification of the addPrincipalToSubject Operation

30/39


6.2.12 Specification of the removePrincipalFromSubject Operation The mandatory removePrincipalFromSubject operation is used to remove a principal from a subject. The principal can be part of any ORCHESTRA Authentication Service instance. Note that a group is also a subject. Thus, this operation can also be used to remove principals from a group. This operation cannot be used to remove member principal from a group. The signatures of the operation is void removePrincipalFromSubject (OA_Principal, OA_Subject) throws OA_InvalidParameterValue, OA_MissingParameterValue, OA_NoApplicableCode, OA_InternalError, OA_SubjectNotFoundException, OA_PrincipalNotFoundException, OA_PermissionDeniedException

Overrides

not applicable

Preconditions

Subject has to exist. Principal has to exist. Association between subject and principal has to exist.

Post conditions

none

Use

mandatory

Receives

Name

Type

Use

Description

principal

OA_Principal

Mandatory

Principal to be removed from the given subject.

subject

OA_Subject

Mandatory

Subject from which a principal should be removed.

Returns

Type

Description

Type

Cause

void Throws





OA_NoApplicableCode


OA_InternalError






31/39




Table 14: Specification of the removePrincipalFromSubject Operation

32/39

Specification of the User Management Service – Specification of Parameter Types

6.3

Specification of Parameter Types This interface specification does define new OA Types. These new OA Types will become part of the “OAS::OA Types”. This interface specification does not introduce any new non-ORCHESTRA Types.

6.3.1

OA_Subject A Subject represents an abstract user like an end user, group, service, service chain, etc. An OA_Subject has the following attributes: •

id The id identifies an OA_Subject inside an instance of the User Management Service.

•

origin Via origin the User Management Service instance managing this OA_Subject is identified.

•

principals The attribute principals are a list of principals belonging to this subject. The combination of id and origin allows to identify a subject inside an OSN. cd Subj ect «type» OA_Subj ect + + +

id: Integer origin: OA_OSI_Identifier principals: Sequence

1 1 OA_SubjectAttributes

OA_Subj ectAttributesHash -

OA_Subj ectAttributesTree

subjectAttributes: OA_HashTable

Diagram 3: Connection between OA_Subject and OA_SubjectAttributes 6.3.2

OA_SubjectAttributes Subject attributes represent subject related information. SubjectAttributes are abstract and thus not used directly. Instead, concrete subject attribute types have to inherit from OA_SubjectAttributes. Examples for concrete subject attribute types would be a hash/dictionary with key-value pairs or a tree structure.

33/39

Specification of the User Management Service – Specification of Parameter Types 6.3.3

OA_Principal The type OA_Principal is defined in the specification of the Authentication Service.

6.3.4

OA_Group A group is a subject representing a group of principals. cd Groups «type» OA_Subj ect + + + +

id: Integer origin: OA_OSI_Identifier principals: Sequence attributes: OA_SubjectAttributes

«type» OA_Principal + 0..* + + +

1

id: Integer origin: OA_OSI_Identifier refSubject: OA_Subject [0..1] refGroups: Sequence 1..*

«type» OA_Group +

1

memberPrincipals: Sequence

Diagram 4: Class diagram of OA_Group 6.3.5

OA_NoSuchMemberException The OA_NoSuchMemberException is thrown if the given principal to act on is not a member of the given group.

6.3.6

OA_ReferentialIntegrityException The OA_ReferentialIntegrityException is thrown if at least one subject related feature (e.g. a principal) cannot be changed or deleted.

6.3.7

OA_SubjectNotFoundException The OA_SubjectNotFoundException is thrown if the subject to act on does not exist.

6.3.8

OA_PrincipalNotFoundException The OA_PrincipalNotFoundException is thrown if the principal to act on does not exist.

34/39

Specification of the User Management Service – Specification of Parameter Types cd User Management Serv ice Exceptions «type» OA_AbstractException + +


+


«type» OA_ReferentialIntegrityException

«type» OA_Subj ectNotFoundException

«type» OA_PrincipalNotFoundException

«type» OA_NoSuchMemberException

Diagram 5: New exceptions in the User Management Interface

35/39


7

Specification of extended Service Capabilities As part of ORCHESTRA D3.3.2 a meta-information schema for services is defined acting as a default OAS-MI for service capabilities. OA_MI_CapabilitiesDocument includes both the common capabilities and the service specific capabilities. While the common capabilities are defined in the specification of the Service Capabilities Interface, the specific capabilities have to be specialized in each service specification. The schema for service specific capabilities defined here is explicitly divided into the following schema sections:

Section Name

Section Contents This is true if this User Management Service supports to dynamically add attributes (e.g. to store client-specific information like a Service-URI with a specific principal).

dynamicAttributesSupported

supportedSubjectAttributeTypes

This lists the supported types of subject-attributes. Examples for such types would be: OA_SubjectAttributesHash and OA_SubjectAttributesTree


cd User Management Serv ice Capabilities «type» OA_MI_Serv ice_SpecificCapabilities

«type» OA_MI_UserManagementServ iceCapabilities + +

dynamicAttributesSupported: Boolean supportedSubjectAttributeTypes: Sequence

Diagram 6: User Mangement Service specific capabilities

36/39


8

Known Issues and Limitations In order to be able to reference to subjects and groups they need unique identifiers. There are still ongoing discussions about generating unique ids. Results of these discussions need to be considered afterwards. Another issue is in the context of service-chains where it needs to be clarified where the necessary meta-information is created. Currently the thoughts circle around different modes to authenticate in the context of a service-chain. The required meta-information should be made available by the service managing the service-chain and providing the access to it. An idea would be to provide the mode explicitly, e.g. by introduction of a dedicated enumeration-type:

8.1.1

OA_ServiceChainAuthenticationMode The service-chain authentication mode represents an enumeration with two elements: Mode 1: The enumeration value SERVICE_CHAIN_PRINCIPAL indicates that services of the service chain will be invoked with authenticated service-chain principals. A service-chain principal is a principal which is connected to the service-chain’s subject. Mode 2: The enumeration value SERVICE_REQUESTOR_PRINCIPAL indicates that the constituting services of the service-chain will be invoked with authenticated principals of the requestor of that service-chain. Obviously these principals need to be authenticated in advance. cd Serv ice Chains «enumeration» OA_Serv iceChainAuthenticationMode + +

«enum» SERVICE_CHAIN_PRINCIPAL: int = 1 «enum» SERVICE_REQUESTOR_PRINCIPAL: int = 2

Diagram 7: Class diagram of OA_ServiceChainAuthenticationMode

37/39

Specification of the User Management Service – Appendix A: Abstract Test Suite (normative)

9

Appendix A: Abstract Test Suite (normative) When creating an implementation specification of the User Management Service, the “Rules for Implementation Specifications of ORCHESTRA Services” defined in chapter 9.2.2.3 and the “Rules for the Service Mapping to a given Platform” of the RM-OA shall be obeyed. In addition, the following tests shall be performed to ensure conformance of an implementation specification to the platform-independent specification of the User Management Service: 1. Syntactical Conformance •


•


•


•




Additional conformance checks that are specifically to the User Management Service are not required.

38/39

Specification of the User Management Service – Appendix B: UML Models (normative)

10 Appendix B: UML Models (normative) 10.1 XMI Model The XMI Models of this interface specification can be downloaded from the OGC Portal under the following URL: https://portal.opengeospatial.org/index.php?m=projects&a=view&project_id=140&tab=2&artifact_id=222 41 The XMI Model contains all parameters required by this service including those data types and exceptions inherited or reused from other interface and service specifications.

39/39

OA Service Specifications S

OA Service Specifications S

Suggest Documents

Technical Specifications - Apex Service

NISSAN FIGARO SERVICE SPECIFICATIONS

engine service specifications

SS SERVICE SPECIFICATIONS - TodoAutos

ON OA ON OA ON OA ON OA ON OA ON OA ON OA ON OA

Specifications. The new S-Class

Mechanical and Cab Specifications - Isuzu Truck Service

Designing Web Services using Web Service Specifications

Ö¼ Deriving Protocol Specifications from Service ... - CiteSeerX

Managing the Evolution of Service Specifications - CiteSeerX

SCHEDULE 2 â THE SERVICES A. Service Specifications Service ...

Industry's Draft Technical Specifications (IDTS)

Owner's Manual And Product Specifications

S-Class Saloon Specifications (PDF) - Mercedes-Benz

Service delivery protests in South African municipalities - Cogent OA

OA - Core

Assessing service quality of online bill payment system ... - Cogent OA

service quality on customer loyalty and behavioral intention - Cogent OA

OA AFRICA

DIPS-OA

Specifications

Specifications

Specifications

Specifications

OA Service Specifications S