OASIS ebXML RegRep Version 4.0
Part 2: Services and Protocols (ebRS)

Committee Specification Draft 01

24 March 2011

Specification URIs:

This Version:

http://docs.oasis-open.org/regrep/regrep-core/v4.0/csd01/regrep-core-rs-v4.0-csd01.odt
(Authoritative)
http://docs.oasis-open.org/regrep/regrep-core/v4.0/csd01/regrep-core-rs-v4.0-csd01.pdf
http://docs.oasis-open.org/regrep/regrep-core/v4.0/csd01/regrep-core-rs-v4.0-csd01.html

Previous Version:

http://docs.oasis-open.org/regrep/v3.0/specs/regrep-rs-3.0-os.pdf

Latest Version:

http://docs.oasis-open.org/regrep/regrep-core/v4.0/regrep-core-rs-v4.0.odt (Authoritative)

http://docs.oasis-open.org/regrep/regrep-core/v4.0/regrep-core-rs-v4.0.pdf

http://docs.oasis-open.org/regrep/regrep-core/v4.0/regrep-core-rs-v4.0.html

Technical Committee:

OASIS ebXML Registry TC

Chair(s):

Kathryn Breininger, Boeing

Farrukh Najmi, Wellfleet Software

Editor(s):

Farrukh Najmi, Wellfleet Software

Nikola Stojanovic, RosettaNet

Related Work:

This specification replaces or supersedes the OASIS ebXML RegRep 3.0 specifications.

This specification consists of the following documents, schemas, and ontologies:

Declared XML Namespace(s):

See Part 0: Overview Document

Abstract:

This document defines the services and protocols for an ebXML RegRep.

A separate document, OASIS ebXML RegRep Version 4.0 Part 1: Registry Information Model (ebRIM), defines the types of metadata and content that can be stored in an ebXML RegRep.

Status:

See Part 0: Overview Document

Citation Format:

When referencing this specification the following citation format should be used:

[regrep-rs-v4.0] OASIS ebXML RegRep Version 4.0 Part 2: Services and Protocols (ebRS). 24 March 2011. OASIS Committee Specification Draft 01. http://docs.oasis-open.org/regrep/regrep-core/v4.0/csd01/regrep-core-rs-v4.0-csd01.odt.

Notices

Copyright © OASIS Open 2010-2011. All Rights Reserved.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.

OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.

The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see http://www.oasis-open.org/who/trademark.php for above guidance.



Table of Contents

1 Introduction 11

1.1 Terminology 11

1.2 Abstract Protocol 11

1.2.1 RegistryRequestType 11

1.2.1.1 Syntax 11

1.2.1.2 Description 11

1.2.2 RegistryResponseType 11

1.2.2.1 Syntax 12

1.2.2.2 Description 12

1.2.3 RegistryExceptionType 12

1.2.3.1 Syntax 13

1.2.3.2 Description 13

1.3 Server Plugins 13

2 QueryManager Interface 14

2.1 Parameterized Queries 14

2.1.1 Invoking Adhoc Queries 14

2.2 Query Protocol 14

2.2.1 QueryRequest 14

2.2.1.1 Syntax 15

2.2.1.2 Example 15

2.2.1.3 Description 15

2.2.1.4 Response 16

2.2.1.5 Exceptions 16

2.2.2 Element Query 16

2.2.2.1 Syntax 17

2.2.2.2 Description: 17

2.2.3 Element ResponseOption 17

2.2.3.1 Syntax 17

2.2.3.2 Description: 17

2.2.4 QueryResponse 18

2.2.4.1 Syntax 18

2.2.4.2 Example 18

2.2.4.3 Description: 19

2.2.5 Iterative Queries 19

2.3 Parameterized Query Definition 19

2.4 Canonical Query: AdhocQuery 19

2.4.1 Parameter Summary 20

2.4.2 Query Semantics 20

2.5 Canonical Query: BasicQuery 20

2.5.1 Parameter Summary 20

2.5.2 Query Semantics 21

2.6 Canonical Query: ClassificationSchemeSelector 21

2.6.1 Parameter Summary 21

2.6.2 Query Semantics 22

2.7 Canonical Query: FindAssociations 22

2.7.1 Parameter Summary 22

2.7.2 Query Semantics 23

2.8 Canonical Query: FindAssociatedObjects 23

2.8.1 Parameter Summary 23

2.8.2 Query Semantics 24

2.9 Canonical Query: GarbageCollector 24

2.9.1 Parameter Summary 24

2.9.2 Query Semantics 24

2.10 Canonical Query: GetAuditTrailById 25

2.10.1 Parameter Summary 25

2.10.2 Query Semantics 25

2.11 Canonical Query: GetAuditTrailByLid 25

2.11.1 Parameter Summary 25

2.11.2 Query Semantics 26

2.12 Canonical Query: GetAuditTrailByTimeInterval 26

2.12.1 Parameter Summary 26

2.12.2 Query Semantics 26

2.13 Canonical Query: GetAuditTrailByLid 26

2.13.1 Parameter Summary 27

2.13.2 Query Semantics 27

2.14 Canonical Query: GetChildrenByParentId 27

2.14.1 Parameter Summary 27

2.14.2 Query Semantics 28

2.15 Canonical Query: GetClassificationSchemesById 29

2.15.1 Parameter Summary 29

2.15.2 Query Semantics 29

2.16 Canonical Query: GetRegistryPackagesByMemberId 29

2.16.1 Parameter Summary 29

2.16.2 Query Semantics 29

2.17 Canonical Query: GetNotification 30

2.17.1 Parameter Summary 30

2.17.2 Query Semantics 30

2.18 Canonical Query: GetObjectById 30

2.18.1 Parameter Summary 30

2.18.2 Query Semantics 30

2.19 Canonical Query: GetObjectsByLid 30

2.19.1 Parameter Summary 31

2.19.2 Query Semantics 31

2.20 Canonical Query: GetReferencedObject 31

2.20.1 Parameter Summary 31

2.20.2 Query Semantics 31

2.21 Canonical Query: KeywordSearch 31

2.21.1 Canonical Indexes 32

2.21.2 Parameter Summary 32

2.21.3 Query Semantics 33

2.22 Canonical Query: RegistryPackageSelector 34

2.22.1 Parameter Summary 34

2.22.2 Query Semantics 34

2.23 Query Functions 34

2.23.1 Using Functions in Query Expressions 34

2.23.2 Using Functions in Query Parameters 35

2.23.3 Function Processing Model 36

2.23.4 Function Processor BNF 36

2.24 Common Patterns In Query Functions 37

2.24.1 Specifying a null Value for string Param or Return Value 37

2.25 Canonical Functions 37

2.25.1 Canonical Function: currentTime 38

2.25.1.1 Function Semantics 38

2.25.2 Canonical Function: currentUserId 38

2.25.2.1 Function Semantics 38

2.25.3 Canonical Function: relativeTime 38

2.25.3.1 Parameter Summary 38

2.25.3.2 Function Semantics 39

2.25.4 Canonical Function: getClassificationNodes 39

2.25.4.1 Parameter Summary 39

2.25.4.2 Function Semantics 39

2.26 Query Plugins 40

2.26.1 Query Plugin Interface 40

3 LifecycleManager Interface 41

3.1 SubmitObjects Protocol 41

3.1.1 SubmitObjectsRequest 41

3.1.1.1 Syntax 41

3.1.1.2 Description 42

3.1.1.3 id and lid Requirements 42

3.1.1.4 Returns 43

3.1.1.5 Exceptions 43

3.1.2 Audit Trail Requirements 44

3.1.3 Sample SubmitObjectsRequest 44

3.2 The Update Objects Protocol 44

3.2.1 UpdateObjectsRequest 45

3.2.1.1 Syntax 45

3.2.1.2 Description 45

3.2.1.3 Returns 46

3.2.1.4 Exceptions 46

3.2.2 UpdateAction 46

3.2.2.1 Syntax 46

3.2.2.2 Description 47

3.2.3 Audit Trail Requirements 48

3.2.4 Sample UpdateObjectsRequest 48

3.3 RemoveObjects Protocol 48

3.3.1 RemoveObjectsRequest 49

3.3.1.1 Syntax 49

3.3.1.2 Description 49

3.3.1.3 Returns: 50

3.3.1.4 Exceptions: 50

3.3.2 Audit Trail Requirements 50

3.3.3 Sample RemoveObjectsRequest 50

4 Version Control 52

4.1 Version Controlled Resources 52

4.2 Versioning and Id Attribute 53

4.3 Versioning and Lid Attribute 53

4.4 Version Identification for RegistryObjectType 53

4.5 Version Identification for RepositoryItem 53

4.5.1 Versioning of RegistryObjectType 53

4.5.2 Versioning of ExtrinsicObjectType 54

4.6 Versioning and References 54

4.7 Versioning of RegistryPackages 55

4.8 Versioning and RegistryPackage Membership 55

4.9 Inter-version Association 55

4.10 Version Removal 55

4.11 Locking and Concurrent Modifications 56

4.12 Version Creation 56

5 Validator Interface 57

5.1 ValidateObjects Protocol 57

5.1.1 ValidateObjectsRequest 57

5.1.1.1 Syntax 57

5.1.1.2 Example 58

5.1.1.3 Description 58

5.1.1.4 Response 58

5.1.1.5 Exceptions 58

5.1.2 ValidateObjectsResponse 58

5.2 Validator Plugins 58

5.2.1 Validator Plugin Interface 59

5.2.2 Canonical XML Validator Plugin 59

6 Cataloger Interface 60

6.1 CatalogObjects Protocol 60

6.1.1 CatalogObjectsRequest 60

6.1.1.1 Syntax 60

6.1.1.2 Example 61

6.1.1.3 Description 61

6.1.1.4 Response 61

6.1.1.5 Exceptions 61

6.1.2 CatalogObjectsResponse 61

6.1.2.1 Syntax 62

6.1.2.2 Example 62

6.1.2.3 Description 62

6.2 Cataloger Plugins 63

6.2.1 Cataloger Plugin Interface 63

6.2.2 Canonical XML Cataloger Plugin 63

7 Subscription and Notification 65

7.1 Server Events 65

7.1.1 Pruning of Events 65

7.2 Notifications 65

7.3 Creating a Subscription 65

7.3.1 Subscription Authorization 65

7.3.2 Subscription Quotas 65

7.3.3 Subscription Expiration 65

7.3.4 Event Selection 66

7.4 Event Delivery 66

7.4.1 Notification Option 67

7.4.2 Delivery to NotificationListener Web Service 67

7.4.3 Delivery to Email Address 67

7.4.4 Delivery to a NotificationListener Plugin 67

7.4.4.1 Processing Email Notification Via XSLT 67

7.5 NotificationListener Interface 67

7.6 Notification Protocol 68

7.6.1 Notification 68

7.7 Pulling Notification on Demand 68

7.8 Deleting a Subscription 68

8 Multi-Server Features 69

8.1 Remote Objects Reference 69

8.2 Local Replication of Remote Objects 69

8.2.1 Creating Local Replica and Keeping it Synchronized 70

8.2.2 Removing a Local Replica 71

8.2.3 Removing Subscription With Remote Server 71

8.3 Registry Federations 71

8.3.1 Federation Configuration 72

8.3.1.1 Creating a Federation 72

8.3.1.2 Joining a Federation 72

8.3.1.3 Leaving a Federation 73

8.3.1.4 Dissolving a Federation 73

8.3.2 Local Vs. Federated Queries 73

8.3.2.1 Local Queries 73

8.3.2.2 Federated Queries 73

8.3.3 Local Replication of Federation Configuration 74

8.3.4 Time Synchronization Between Federation Members 74

9 Governance Features 75

9.1 Representing a Governance Collaboration 75

9.1.1 Content of Governance Collaboration BPMN Files 77

9.2 Scope of Governance Collaborations 77

9.2.1 Packaging Related Objects as a Governance Unit 77

9.3 Assigning a Governance Collaboration 78

9.4 Determining Applicable Governance Collaboration 78

9.5 Determining the Registry Process in a Governance Collaboration 79

9.6 Starting the Registry Process for a Governance Collaboration 79

9.6.1 Starting Registry Process By WorkflowAction 79

9.7 Incoming messageFlows to Registry Process 79

9.8 Outgoing messageFlows from Registry Process 79

9.9 Canonical Task Patterns 79

9.9.1 SendWorkflowAction Task Pattern 80

9.9.1.1 Server Processing of WorkflowAction 80

9.9.2 ReceiveWorkflowAction Task Pattern 81

9.9.3 SendNotification Task Pattern 81

9.9.4 ReceiveNotification Task Pattern 82

9.9.5 SetStatus Task 82

9.9.6 Validate Task 82

9.9.7 Catalog Task 83

9.10 XPATH Extension Functions 83

9.11 Default Governance Collaboration 84

10 Security Features 85

10.1 Message Integrity 85

10.1.1 Transport Layer Security 85

10.1.2 SOAP Message Security 85

10.2 Message Confidentiality 86

10.3 User Registration and Identity Management 86

10.4 Authentication 86

10.5 Authorization and Access Control 86

10.6 Audit Trail 86

11 Native Language Support (NLS) 87

11.1 Terminology 87

11.2 NLS and Registry Protocol Messages 87

11.3 NLS Support in RegistryObjects 87

11.3.1 Language of a LocalizedString 88

11.3.2 Character Set of RegistryObject 89

11.4 NLS and Repository Items 89

11.4.1 Character Set of Repository Items 89

11.4.2 Language of Repository Items 89

12 REST Binding 90

12.1 Canonical URL 90

12.1.1 Canonical URL for RegistryObjects 90

12.1.2 Canonical URL for Repository Items 90

12.2 Query Protocol REST Binding 91

12.2.1 Parameter queryId 91

12.2.2 Query Specific Parameters 91

12.2.3 Canonical Query Parameter: depth 92

12.2.4 Canonical Query Parameter: format 92

12.2.5 Canonical Query Parameter: federated 92

12.2.6 Canonical Query Parameter: federation 92

12.2.7 Canonical Query Parameter: matchOlderVersions 92

12.2.8 Canonical Query Parameter: startIndex 93

12.2.9 Canonical Query Parameter: lang 93

12.2.10 Canonical Query Parameter: maxResults 93

12.2.11 Use of Functions in Query Parameters 93

12.2.12 Query Response 94

13 SOAP Binding 95

13.1 WS-Addressing SOAP Headers 95



Illustration Index

Illustration 1: Query Protocol 14

Illustration 2: SubmitObjects Protocol 41

Illustration 3: UpdateObjects Protocol 45

Illustration 4: RemoveObjects Protocol 49

Illustration 5: A visual example of a version tree 52

Illustration 6: ValidateObjects Protocol 57

Illustration 7: CatalogObjects Protocol 60

Illustration 8: Notification Protocol 68

Illustration 9: Remote Object Reference 69

Illustration 10: Local Replication of Remote Objects 70

Illustration 11: Registry Federations 72

Illustration 12: Default Governance Collaboration 76



Index of Tables

Table 1: Canonical Functions Defined By This Profile 38

Table 2: Requirements for id and lid During SubmitObjects Protocol 43



1 Introduction

All text is normative unless otherwise indicated.

This document specifies the ebXML RegRep service interfaces and the protocols they support. For a general overview of ebXML RegRep and other related parts of the specification please refer to Part 0 [RR-OVERVIEW].

1.1 Terminology

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in IETF [RFC 2119].

Abstract Protocol

This section describes the types RegistryRequestType, RegistryResponseType and RegistryExceptionType defined within rs.xsd that are the abstract types used by most protocols defined by this specification in subsequent chapters. A typical registry protocol is initiated by a request message that extends RegistryRequestType. In response the registry server sends a response that extends RegistryResponseType. If an error is encountered by the server during the processing of a request, the server returns a fault message that extends the RegistryExceptionType.

1.1.1 RegistryRequestType

The RegistryRequestType is the abstract base type for most requests sent by client to the server.

1.1.1.1 Syntax

<complexType name="RegistryRequestType">

<complexContent>

<extension base="rim:ExtensibleObjectType">

<attribute name="id" type="string" use="required"/>

<attribute name="comment" type="string" use="optional"/>

</extension>

</complexContent>

</complexType>

1.1.1.2 Description

1.1.2 RegistryResponseType

The RegistryResponseType is the base type for most responses sent by the server to the client in response to a client request. A global RegistryResponse element is defined using this type which is used by several requests defined within this specification.

1.1.2.1 Syntax

<complexType name="RegistryResponseType">

<complexContent>

<extension base="rim:ExtensibleObjectType">

<sequence>

<element name="Exception" type="tns:RegistryExceptionType"

minOccurs="0" maxOccurs="unbounded"/>

<element ref="rim:RegistryObjectList" minOccurs="0" maxOccurs="1"/>

<element ref="rim:ObjectRefList" minOccurs="0" maxOccurs="1"/>

</sequence>

<attribute name="status" type="rim:objectReferenceType" use="required"/>

<attribute name="requestId" type="anyURI" use="optional"/>

</extension>

</complexContent>

</complexType>

<element name="RegistryResponse" type="tns:RegistryResponseType"/>

1.1.2.2 Description

1.1.3 RegistryExceptionType

The RegistryExceptionType is the abstract base type for all exception or fault messages sent by the server to the client in response to a client request. A list of all protocol exceptions is available in the Protocol Exceptions appendix.

1.1.3.1 Syntax

<complexType name="RegistryExceptionType">

<annotation>

<documentation>Base for all registry exceptions. Based upon SOAPFault: http://www.w3schools.com/soap/soap_fault.asp</documentation>

</annotation>

<complexContent>

<extension base="rim:ExtensibleObjectType">

<attribute name="code" type="string" use="optional"/>

<attribute name="detail" type="string" use="optional"/>

<attribute name="message" type="string"/>

<attribute name="severity" type="rim:objectReferenceType" default="urn:oasis:names:tc:ebxml-regrep:ErrorSeverityType:Error"/>

</extension>

</complexContent>

</complexType>

1.1.3.2 Description

In addition to the attributes and elements inherited from ExtensibleObjectType this type defines the following attributes and elements:

1.2 Server Plugins

Deployments of a server MAY extend the core functionality of the server by using function-specific software modules called plugins. A plugin extends the server by adding additional functionality to it. A plugin MUST conform to standard interfaces as defined by this specification. These standard interfaces are referred to as Service Provider Interfaces (SPI).

Subsequent chapters will specifies various Service Provider Interfaces (SPI) that defines the standard interface for various types of server plugins. These interfaces are described in form of [WSDL2, WSDL1] specification.

A server may implement these interfaces as external web services invoked by the server using [SOAP-MF, SOAP-ADJ] or as plugin modules that share the same process as the server and are invoked by local function calls.

Examples of types of server plugins include, but are not limited to query plugin, validator plugin and cataloger plugin.

This specification does not define how a plugin is implemented or how it is configured within a server. Nor does it define whether or how, plugin configuration functionality is made discoverable to clients.

2 QueryManager Interface

The QueryManager interface allows a client to invoke queries on the server.

2.1 Parameterized Queries

A server may support any number of pre-configured queries known as Parameterized Queries, that may be invoked by clients. Parameterized queries are similar in concept to stored procedures in SQL.

This specification defines a number of canonical queries that are standard queries that MUST be supported by a server. Profiles, implementations and deployments may define additional parameterized queries beyond the canonical queries defined by this specification.

A client invokes a parameterized query supported by the server by specifying its unique id as well as values for any parameters supported by the query.

A parameterized query MAY be stored in the server as a specialized RegistryObject called QueryDefinition object which is defined by [ebRIM]. The definition of a QueryDefinition may contain any number of Parameters supported by the query.

2.1.1 Invoking Adhoc Queries

A client may invoke a client-specific ad hoc query using a special canonical parameterized query called the AdhocQuery query defined by this specification. Due to the risks associated with un-controlled ad hoc queries, a deployment MAY choose to restrict the invocation of the AdhocQuery query to specific roles. This specification does not define a standard query expression syntax for ad hoc queries. A server MAY support any number of query expression syntaxes for ad hoc queries.

2.2 Query Protocol

A client invokes a parameterized query using the Query protocol defined by the executeQuery operation of the QueryManager interface.

A client initiates the Query protocol by sending a QueryRequest message to the QueryManager endpoint.

The QueryManager sends a QueryResponse back to the client as response. The QueryResponse contains a set of objects that match the query.


Illustration 1: Query Protocol




2.2.1 QueryRequest

The QueryRequest message is sent by the client to the QueryManager interface to invoke a query.

2.2.1.1 Syntax

<element name="QueryRequest">

<complexType>

<complexContent>

<extension base="rs:RegistryRequestType">

<sequence>

<element name="ResponseOption" type="tns:ResponseOptionType"

minOccurs="1" maxOccurs="1"/>

<element name="Query" type="rim:QueryType"

minOccurs="1" maxOccurs="1" />

</sequence>

<attribute name="federated" type="boolean"

use="optional" default="false"/>

<attribute name="federation" type="anyURI" use="optional"/>

<attribute name="format" type="string"

use="optional" default="application/ebrim+xml"/>

<attribute ref="xml:lang" use="optional"/>

<attribute name="startIndex" type="integer" default="0"/>

<attribute name="maxResults" type="integer" default="-1"/>

<attribute name="depth" type="integer" default="0"/>

<attribute name="matchOlderVersions" type="boolean"

use="optional" default="false"/>

</extension>

</complexContent>

</complexType>

</element>

2.2.1.2 Example

The following example shows a QueryRequest which gets an object by its id using the canonical GetObjectById query.



<query:QueryRequest maxResults="-1" startIndex="0" ...>

<rs:ResponseOption returnComposedObjects="true" returnType="LeafClassWithRepositoryItem"/>

<query:Query queryDefinition="urn:oasis:names:tc:ebxml-regrep:query:GetObjectById">

<rim:Slot name="id">

<rim:SlotValue xsi:type="StringValueType" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<rim:Value>%danyal%</rim:Value>

</rim:SlotValue>

</rim:Slot>

</query:Query>

</query:QueryRequest>

2.2.1.3 Description

2.2.1.4 Response

This request returns QueryResponse as response.

2.2.1.5 Exceptions

In addition to common exceptions, the following exceptions MAY be returned:

2.2.2 Element Query

A client specifies a Query element within a QueryRequest to specify the parameterized query being invoked as well as the values for its parameters.

2.2.2.1 Syntax

<complexType name="QueryType">

<complexContent>

<extension base="tns:ExtensibleObjectType">

<attribute name="queryDefinition"

type="tns:objectReferenceType" use="required"/>

</extension>

</complexContent>

</complexType>



2.2.2.2 Description:

2.2.3 Element ResponseOption

A client specifies a ResponseOption structure within a QueryRequest to control the type and structure of results within the corresponding QueryResponse.

2.2.3.1 Syntax

<complexType name="ResponseOptionType">

<attribute name="returnType" default="LeafClassWithRepositoryItem">

<simpleType>

<restriction base="NCName">

<enumeration value="ObjectRef"/>

<enumeration value="RegistryObject"/>

<enumeration value="LeafClass"/>

<enumeration value="LeafClassWithRepositoryItem"/>

</restriction>

</simpleType>

</attribute>

<attribute name="returnComposedObjects"

type="boolean" use="optional" default="false"/>

</complexType>

<element name="ResponseOption" type="tns:ResponseOptionType"/>

2.2.3.2 Description:

If “returnType” specified does not match a result returned by the query, then the server MUST use the closest matching semantically valid returnType that matches the result. For example, consider a case where a Query that matches rim:OrganizationType instances is asked to return LeafClassWithRepositoryItem. As this is not possible, QueryManager will assume the LeafClass option instead.

2.2.4 QueryResponse

The QueryResponse message is sent by the QueryManager in response to a QueryRequest when the format requested by the client is the default ebrs format.

2.2.4.1 Syntax

<element name="QueryResponse">

<complexType>

<complexContent>

<extension base="rs:RegistryResponseType">

<attribute name="startIndex" type="integer" default="0"/>

<attribute name="totalResultCount" type="integer" use="optional"/>

</extension>

</complexContent>

</complexType>

</element>

2.2.4.2 Example

The following shows a sample response for the example QueryRequest presented earlier.

<query:QueryResponse totalResultCount="1" startIndex="0" status="urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Success">

<rim:RegistryObjectList>

<RegistryObject xsi:type="PersonType"

status="urn:oasis:names:tc:ebxml-regrep:StatusType:Submitted"

objectType="urn:oasis:names:tc:ebxml-regrep:ObjectType:RegistryObject:Person"

lid="urn:acme:Person:Danyal" id="urn:acme:Person:Danyal">

<Name>

<LocalizedString value="Danyal Najmi" xml:lang="en-US"/>

</Name>

<VersionInfo versionName="1"/>

<PersonName lastName="Najmi" middleName="Idris" firstName="Danyal"/>

</RegistryObject>

</rim:RegistryObjectList>

</query:QueryResponse>

2.2.4.3 Description:

2.2.5 Iterative Queries

The QueryRequest and QueryResponse support the ability to iterate over a large result set matching a query by allowing multiple QueryRequest requests to be submitted in succession such that each query requests a different subset of results within the result set. This feature enables the server to handle queries that match a very large result set, in a scalable manner. The iterative query feature is accessed via the startIndex and maxResults parameters of the QueryRequest and the startIndex and totalResultCount parameters of the QueryResponse as described earlier.

A server MUST return a result set whose size is less than or equal to the maxResults parameter depending upon whether enough results are available starting at startIndex.

The iterative queries feature is not a true Cursor capability as found in databases. A server is not required to maintain transactional consistency or state between iterations of a query. Thus it is possible for new objects to be added or existing objects to be removed from the complete result set in between iterations. As a consequence it is possible to have a result set element be skipped or duplicated between iterations. However, a server MUST return the same result in a deterministic manner for the same QueryRequest if no changes have been made in between the request to the server (or servers in case of federated queries).

Note that while it is not required, a server MAY implement a transactionally consistent iterative query feature.

2.3 Parameterized Query Definition

A parameterized query is defined by submitting a rim:QueryDefinitionType instance to the server using the submitObjects protocol. A detailed specification of the rim:QueryDefinitionType is defined in ebRIM. The definition of a parameterized query includes detailed specification of each supported parameter including its name, description, data type, cardinality and domain.

2.4 Canonical Query: AdhocQuery

The canonical query AdhocQuery allows clients to invoke a client-specified ad hoc query in a client-specified query expression syntax that is supported by the server. This specification does not require a server to support any specific query expression syntax. It is likely that servers may support one or more common syntaxes such as SQL-92, XQuery, XPath, SPARQL, Search-WS, OGC Filter etc.

2.4.1 Parameter Summary

Parameter

Description

Data Type

Default Value

Cardinality

queryExpression

Value is a query expression string in the language specified by the queryLanguage parameter

string


1

queryLanguage

Value is the id of a ClassificationNode within the canonical QueryLanguageScheme ClassificationScheme.

taxonomyElement


1

2.4.2 Query Semantics

2.5 Canonical Query: BasicQuery

The canonical query BasicQuery allows clients to query for RegistryObjects by their name, description, type, status and classifications.

2.5.1 Parameter Summary

Parameter

Description

Data Type

Default Value

Cardinality

classifications

Set whose elements are path attribute values to ClassificationNodes.

Matches RegistryObjects that have a classification whose classificationNode attribute value matches the id of the ClassificationNode where rim:RegistryObject[@xsi:type="rim:ClassificationNodeType"]/@path matches specified value

When multiple values are specified it implies a logical AND operation.

string


0..*

description

Matches rim:RegistryObject/rim:Description/rim:LocalizedString/@value

string


0..1

matchOnAnyParameter

If true then use logical OR between predicates for each parameter

boolean

false

0..1

name

Matches rim:RegistryObject/rim:Name/rim:LocalizedString/@value

string


0..1

objectType

Matches RegistryObjects whose objectType attribute matches the id of the ClassificationNode where rim:ClassificationNode/@path matches specified value

taxonomyElement


0..1

owner

Matches rim:RegistryObject/@owner. Note that a parameter value of “#@'@#rs:currentUserId()#@'@#” may be used to specify the id of the user associated with the current request

string


0..1

status

Matches RegistryObjects whose status attribute matches the id of the ClassificationNode where rim:ClassificationNode/@path matches specified value

taxonomyElement


0..1

2.5.2 Query Semantics

2.6 Canonical Query: ClassificationSchemeSelector

The canonical query ClassificationSchemeSelector allows clients to create a Subscription to a remote server to replicate a remote ClassificationScheme. This query may be used as Selector query in the subscription as defined in the object replication feature.

2.6.1 Parameter Summary

Parameter

Description

Data Type

Default Value

Cardinality

classificationSchemeId

Matches rim:RegistryObject[@xsi:type="rim:ClassificationSchemeType"]/@id.

Does not allow wildcards.

string


1

2.6.2 Query Semantics

2.7 Canonical Query: FindAssociations

The canonical query FindAssociations query allows clients to find Associations that match the specified criteria.

2.7.1 Parameter Summary

Parameter

Description

Data Type

Default Value

Cardinality

associationType

Matches Associations whose type attribute references a ClassificationNode where rim:ClassificationNode/@path matches specified value

taxonomyElement


0..1

matchOnAnyParameter

If true then use logical OR between predicates for each parameter

boolean

false

0..1

sourceObjectId

Matches rim:/RegistryObject[@xsi:type="rim:AssociationType"]/@sourceObject.

Allows use of “%” wildcard character to match multiple characters.

Allows use of “?” wildcard character to match a single character.

string


0..1

sourceObjectType

Matches Associations whose sourceObject attribute references a RegistryObject whose objectType attribute matches the id of the ClassificationNode where rim:ClassificationNode/@path matches specified value

taxonomyElement


0..1

targetObjectId

Matches rim:/RegistryObject[@xsi:type="rim:AssociationType"]/@targetObject.

Allows use of “%” wildcard character to match multiple characters.

Allows use of “?” wildcard character to match a single character.

string


0..1

targetObjectType

Matches Associations whose targetObject attribute references a RegistryObject whose objectType attribute matches the id of the ClassificationNode where rim:ClassificationNode/@path matches specified value

taxonomyElement


0..1

2.7.2 Query Semantics

2.8 Canonical Query: FindAssociatedObjects

The canonical query FindAssociatedObjects allows clients to find RegistryObjects that are associated with the specified RegistryObject and match the specified criteria.

2.8.1 Parameter Summary

Parameter

Description

Data Type

Default Value

Cardinality

associationType

Matches associated RegistryObjects of Association's whose type attribute references a ClassificationNode where rim:ClassificationNode/@path matches specified value

taxonomyElement


0..1

matchOnAnyParameter

If true then use logical OR between predicates for each parameter

boolean

false

0..1

sourceObjectId

Matches target RegistryObjects of Associations where the source RegistryObject's id matches rim:/RegistryObject[@xsi:type="rim:AssociationType"]/@sourceObject.

Allows use of “%” wildcard character to match multiple characters.

Allows use of “?” wildcard character to match a single character.

string


0..1

sourceObjectType

Matches target RegistryObjects of Associations whose sourceObject attribute references a RegistryObject whose objectType attribute matches the id of the ClassificationNode where rim:ClassificationNode/@path matches specified value

taxonomyElement


0..1

targetObjectId

Matches source RegistryObjects of Associations where the target RegistryObject's id matches rim:/RegistryObject[@xsi:type="rim:AssociationType"]/@targetObject.

Allows use of “%” wildcard character to match multiple characters.

Allows use of “?” wildcard character to match a single character.

string


0..1

targetObjectType

Matches source RegistryObjects of Associations whose targetObject attribute references a RegistryObject whose objectType attribute matches the id of the ClassificationNode where rim:ClassificationNode/@path matches specified value

taxonomyElement


0..1

2.8.2 Query Semantics

2.9 Canonical Query: GarbageCollector

The canonical query GarbageCollector allows clients to find RegistryObjects that are deemed as garbage by the server.

2.9.1 Parameter Summary

This query specifies no parameters.

2.9.2 Query Semantics

2.10 Canonical Query: GetAuditTrailById

The canonical query GetAuditTrailById allows clients to get the change history or audit trail for a RegistryObject whose id attribute value is the same as the value of the id parameter.

2.10.1 Parameter Summary

Parameter

Description

Data Type

Default Value

Cardinality

endTime

Specifies the end of the time interval (inclusive) for rim:/RegistryObject[@xsi:type="rim:AuditableEventType"]/@timestamp value

dateTime


0..1

id

Matches rim:/RegistryObject/@id.

string


1

startTime

Specifies the end of the time interval (inclusive) for rim:/RegistryObject[@xsi:type="rim:AuditableEventType"]/@timestamp value

dateTime


0..1

2.10.2 Query Semantics

2.11 Canonical Query: GetAuditTrailByLid

The canonical query GetAuditTrailByLid allows clients to get the change history or audit trail for all RegistryObjects whose lid attribute value is the same as the value of the lid parameter.

2.11.1 Parameter Summary

Parameter

Description

Data Type

Default Value

Cardinality

endTime

Specifies the end of the time interval (inclusive) for rim:/RegistryObject[@xsi:type="rim:AuditableEventType"]/@timestamp value

dateTime


0..1

lid

Matches rim:/RegistryObject/@lid.

string


1

startTime

Specifies the end of the time interval (inclusive) for rim:/RegistryObject[@xsi:type="rim:AuditableEventType"]/@timestamp value

dateTime


0..1

2.11.2 Query Semantics

2.12 Canonical Query: GetAuditTrailByTimeInterval

The canonical query GetAuditTrailByTimeInterval allows clients to get all changes to all objects in the server within a specified time interval. This query may be used to keep a client periodically synchronized with changes in the server.

2.12.1 Parameter Summary

Parameter

Description

Data Type

Default Value

Cardinality

endTime

Specifies the end of the time interval (inclusive) for rim:/RegistryObject[@xsi:type="rim:AuditableEventType"]/@timestamp value

dateTime

5 minutes before current time

0..1

startTime

Specifies the end of the time interval (inclusive) for rim:/RegistryObject[@xsi:type="rim:AuditableEventType"]/@timestamp value

dateTime

Current time

0..1

2.12.2 Query Semantics

2.13 Canonical Query: GetAuditTrailByLid

The canonical query GetAuditTrailByLid allows clients to get the change history or audit trail for all RegistryObjects whose lid attribute value is the same as the value of the lid parameter.

2.13.1 Parameter Summary

Parameter

Description

Data Type

Default Value

Cardinality

endTime

Specifies the end of the time interval (inclusive) for rim:/RegistryObject[@xsi:type="rim:AuditableEventType"]/@timestamp value

dateTime


0..1

lid

Matches rim:/RegistryObject/@lid.

string


1

startTime

Specifies the end of the time interval (inclusive) for rim:/RegistryObject[@xsi:type="rim:AuditableEventType"]/@timestamp value

dateTime


0..1

2.13.2 Query Semantics

2.14 Canonical Query: GetChildrenByParentId

The canonical query GetChildrenByParentId allows clients to get the children of a RegistryObject whose Id attribute value is the same as the value specified for the parentId parameter. This query is used to query objects hierarchies with parent-child relationships such as the following:

2.14.1 Parameter Summary

Parameter

Description

Data Type

Default Value

Cardinality

depth

Specifies how many levels of descendants to fetch:

  • depth > 0 implies get descendants upto “depth” levels

  • depth <= 0 implies get all descendants


integer

1

0..1

exclusiveChildrenOnly

Specifies how to handle children that may have multiple parents:

  • True value specifies that only children that are not children of any other parent should be returned

  • false value specifies that children that have other parents should also be matched


boolean

false

0..1

objectType

Specifies the type of object hierarchy for the query

string


0..1

parentId

Specifies the id of the parent object

string


0..1

2.14.2 Query Semantics

2.15 Canonical Query: GetClassificationSchemesById

The canonical query GetClassificationSchemesById allows clients to fetch specified ClassificationSchemes.

2.15.1 Parameter Summary

Parameter

Description

Data Type

Default Value

Cardinality

id

Matches rim:/RegistryObject[@xsi:type="rim:ClassificationSchemeType"]/@id.

Allows use of “%” wildcard character to match multiple characters.

Allows use of “?” wildcard character to match a single character.

string


0..1

2.15.2 Query Semantics

2.16 Canonical Query: GetRegistryPackagesByMemberId

The canonical query GetRegistryPackagesByMemberId allows clients to get the RegistryPackages that a specified RegistryObject is a member of.

2.16.1 Parameter Summary

Parameter

Description

Data Type

Default Value

Cardinality

memberId

Matches RegistryPackages that have a RegistryObject as an immediate member where the RegistryObject's id rim:RegistryObject/@id matches the specified value.

Allows use of “%” wildcard character to match multiple characters.

Allows use of “?” wildcard character to match a single character.

string


0..1

2.16.2 Query Semantics

2.17 Canonical Query: GetNotification

The canonical query GetNotification allows clients to “pull” any pending Notification for a Subscription at a time of their choosing. This is defined in detail under section titled “Pulling Notification on Demand”.

2.17.1 Parameter Summary

Parameter

Description

Data Type

Default Value

Cardinality

subscriptionId

Matches rim:/RegistryObject[@xsi:type="rim:SubscriptionType"]/@id.

Wildcards are not allowed.

string


1

startTime

The time since which events should be included in the Notification

xs:dateTime


0..1

2.17.2 Query Semantics

2.18 Canonical Query: GetObjectById

The canonical query GetObjectById allows clients to find RegistryObjects based upon the value of their id attribute.

2.18.1 Parameter Summary

Parameter

Description

Data Type

Default Value

Cardinality

id

Matches rim:RegistryObject/@id.

Allows use of “%” wildcard character to match multiple characters.

Allows use of “?” wildcard character to match a single character.

string


1

2.18.2 Query Semantics

2.19 Canonical Query: GetObjectsByLid

The canonical query GetObjectByLid allows clients to find RegistryObjects based upon the value of their lid attribute. It is used to fetch all versions of a logical object without any specific order or relationship among them.

2.19.1 Parameter Summary

Parameter

Description

Data Type

Default Value

Cardinality

lid

Matches rim:RegistryObject/@lid.

Allows use of “%” wildcard character to match multiple characters.

Allows use of “?” wildcard character to match a single character.

string


1

2.19.2 Query Semantics

2.20 Canonical Query: GetReferencedObject

The canonical query GetReferencedObject allows clients to get a RegistryObject that is the target of an rim:objectReferenceType attribute value.

2.20.1 Parameter Summary

Parameter

Description

Data Type

Default Value

Cardinality

objectReference

Contains the value for a rim:objectReferenceType attribute

string


0..1

2.20.2 Query Semantics

2.21 Canonical Query: KeywordSearch

The canonical query KeyWordSearch allows clients to find RegistryObjects and RepositoryItems that contain text that matches keywords identified by specified search patterns.

2.21.1 Canonical Indexes

This query defines a set of canonical index names as defined by table below. Each index name is associated with a particular type of information that it indexes. A server MUST index all information that is defined by the canonical indexes below. A server MAY define additional indexes to index information not specified by this section.



Index Name

Description

name.localizedString.value

Indexes the value of all localized string in all Name elements of all RegistryObjects

description.localizedString.value

Indexes the value of all localized string in all Description elements of all RegistryObjects

slot.name

Indexes the name of all slots on all RegistryObjects

slot.value

Indexes the value of all slots on all RegistryObjects

repositoryItem

Indexes the text of all text based repository items associated with ExtrinsicObjects

personName.firstName

Indexes the firstName attribute of PersonName elements in all Person objects

personName.middleName

Indexes the middleName attribute of PersonName elements in all Person objects

personName.lastName

Indexes the lastName attribute of PersonName elements in all Person objects

emailAddress.address

Indexes the address attribute of all EmailAddress objects

postalAddress.city

Indexes the city attribute of all PostalAddress elements contained within any RegistryObject

postalAddress.country

Indexes the country attribute of all PostalAddress elements contained within any RegistryObject

postalAddress.postalCode

Indexes the postalCode attribute of all PostalAddress elements contained within any RegistryObject

postalAddress.stateOrProvince

Indexes the stateOrProvince attribute of all PostalAddress elements contained within any RegistryObject

postalAddress.street

Indexes the street attribute of all PostalAddress elements contained within any RegistryObject





2.21.2 Parameter Summary

Parameter

Description

Data Type

Default Value

Cardinality

keywords

A space separated list of keywords to search for

string


1

2.21.3 Query Semantics

2.22 Canonical Query: RegistryPackageSelector

The canonical query RegistryPackageSelector allows clients to create a Subscription to a remote server to replicate a remote RegistryPackage as well as all its member objects and the AssociationType instances that relate the members of the RegistryPackage to it. This query MAY be used as Selector query within the Subscription for the replication as defined in the object replication feature.

2.22.1 Parameter Summary

Parameter

Description

Data Type

Default Value

Cardinality

registryPackageIds

A set of IDs of rim:RegistryPackageType instances. Does not allow wildcards.

string


1..*

2.22.2 Query Semantics

2.23 Query Functions

A server MAY support any number of functions known as Query Functions, that may be used within a query expression or query parameter. Query functions are similar in concept to functions in SQL. Query functions may be used within the query expression of a parameterized query as well as within its invocation parameter values. Query functions enable parameterized queries to use specialized search algorithms to augment their capabilities.

This specification defines a number of canonical functions that are standard functions that MUST be supported by a server. Profiles, implementations and deployments may define additional query functions beyond the canonical functions defined by this specification.

2.23.1 Using Functions in Query Expressions

A parameterized query stored as a rim:QueryDefinition instance MAY have a rim:QueryExpression which defines a query expression within its sub-nodes. A client MAY submit a rim:QueryDefinition such that its query expression may use any number of query functions supported by the server any where within the query expression where it is syntactically correct to use the value returned by the function.

If a query expression contains one or more function invocations then the query expression MUST delimit the parts of the query expression that are not a function invocation with the leading characters “#@” and trailing characters “@#”. This is similar in syntax to a Java multi-line comment syntax where a comment is delimited by leading characters “/*” and trailing characters “*/”. The delimiters serve the following purposes:

The following is an example of a SQL query expression which uses the getClassificationNodes function to match all RegistryObjects that are targets of Association with specified sourceObject and type that is a subnode of AffiliatedWith node upto a depth of 2 levels in the descendant hierarchy. The delimiter characters are in bold font while the function invocations is in bold and italic font below:

--example of a query expression with query functions

#@SELECT targetObject.* FROM

RegistryObjectType targetObject, AssociationType a WHERE


a.sourceObject = :sourceObject AND

a.type IN (@# getClassificationNodes("urn:oasis:names:tc:ebxml-regrep:AssociationType:AffiliatedWith", 0, 2, "false", ",", "${id}") #@) AND

targetObject.id = a.targetObject@#

2.23.2 Using Functions in Query Parameters

A client MAY use query functions supported by a server within parameter values specified when invoking a parameterized query. A client MAY invoke a parameterized query using the Query protocol such that its query parameter values may use any number of query functions supported by the server any where within the query parameter where it is syntactically correct to use the value returned by the function.

If a query parameter value contains one or more function invocations then the query expression MUST delimit the parts of the query parameter that are not a function invocation with the leading characters “#@” and trailing characters “@#”. If a query parameter value only has function invocations and contains no non-function parts then it must include at least one leading or trailing “#@@#” delimiter token pair to allow optimized parsing and evaluation of query functions only when needed.

The following is an example of a query expression that has no query functions. Its two parameters are shown in bold font:

--Following is the query expression within the server

--This time it has no query functions as they are in the query parameters

SELECT targetObject.* FROM

RegistryObjectType targetObject, AssociationType a WHERE


a.sourceObject = :sourceObject AND

a.type IN ( :types ) AND

targetObject.id = a.targetObject

The following is an example of invocation of a parameterized query that uses the above query expression and uses the getClassificationNodes function from previous example within the value of the types parameter. Note the trailing “#@@#” delimiter tokens are present as required.



<query:QueryRequest maxResults="-1" startIndex="0" ...>

<rs:ResponseOption returnComposedObjects="true" returnType="LeafClassWithRepositoryItem"/>

<query:Query queryDefinition="urn:acme:ExampleQuery">

<rim:Slot name="sourceObject">

<rim:SlotValue xsi:type="StringValueType" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<rim:Value>urn:test:Person:Danyal</rim:Value>

</rim:SlotValue>

<rim:Slot name="types">

<rim:SlotValue xsi:type="StringValueType" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<rim:Value>getClassificationNodes("urn:oasis:names:tc:ebxml-regrep:AssociationType:AffiliatedWith", 0, 2, "false", ",", "${id}")#@@#</rim:Value>

</rim:SlotValue>

</rim:Slot>

</query:Query>

</query:QueryRequest>

2.23.3 Function Processing Model

A server MUST meet the following function processing requirements during the processing of a QueryRequest:

2.23.4 Function Processor BNF

The following BNF grammar normatively describes the grammar for query expressions and query invocation parameters with embedded function invocations. The start production describes the grammar for query expressions and query invocation parameters with embedded function invocations.



<DEFAULT> SKIP : {

" "

| "\t"

| "\r"

| "\n"

}



<DEFAULT> TOKEN : {

<FLOAT: <INTEGER> "." <INTEGER> | "." <INTEGER> | <INTEGER> ".">

| <INTEGER: (<DIGIT>)+>

| <DIGIT: ["0"-"9"]>

| <BOOLEAN: "true" | "false">

}



<DEFAULT> TOKEN : {

<S_IDENTIFIER: (<LETTER>)+ (<DIGIT> | <LETTER> | <SPECIAL_CHARS>)*>

| <#LETTER: ["a"-"z","A"-"Z"]>

| <#SPECIAL_CHARS: "_">

| <S_CHAR_LITERAL: "\'" (~["\'"])* "\'" ("\'" (~["\'"])* "\'")*>

| <S_QUOTED_IDENTIFIER: "\"" (~["\n","\r","\""])* "\"">

| <OPENPAREN: "(">

| <CLOSEPAREN: ")">

| <COMMA: ",">

| <COLON: ":">

| <DELIMITED_TEXT: "#@" (~["@"])* "@#">

}


start ::= ( textOrFunctionCall )+ <EOF>

text ::= ( ( <DELIMITED_TEXT> ) )

textOrFunctionCall ::= ( text | FunctionCall )

FunctionCall ::= FunctionReference <OPENPAREN> ( FunctionArgumentList )* <CLOSEPAREN>

FunctionReference ::= <S_IDENTIFIER> <COLON> <S_IDENTIFIER>

FunctionArgumentList ::= FunctionArgument ( <COMMA> FunctionArgument )*

FunctionArgument ::= ( FunctionCall | <S_CHAR_LITERAL> | <S_QUOTED_IDENTIFIER> | <FLOAT> | <INTEGER> | <BOOLEAN> )

2.24 Common Patterns In Query Functions

This section defines some commonly occurring patterns in query functions and defines some common solutions to addressing these patterns. Profiles SHOULD conform to the solutions defined in this section whenever possible.

2.24.1 Specifying a null Value for string Param or Return Value

A function that accepts a string parameter SHOULD treat a value of “rs:null” as a null string. A null string is a string whose value is unspecified.

When a function returns a “string” type it SHOULD return a null value string as the canonical value “rs:null”.

2.25 Canonical Functions

This section defines a set of standard canonical functions that MUST be supported by all servers. A client MAY use these functions within a query expression or within the value of a parameter to a parameterized query. A server MUST process the functions according to their behavior as specified in this section. The function processing model is specified in Function Processing Model.

A client MUST use the “rs:” namespace prefix when using a canonical function defined by this profile. Profiles of this specification MAY define their own canonical functions as well as a standard namespace prefix to be used with these functions.

A client MUST specify the parameters of a function in the same order as specified in the table for the function specification.

Table 1 summarizes the canonical functions defined by this specification.



Function Name

Semantics

currentTime

Returns the current time in ISO 8601 format

currentUserId

Returns the id of the user associated with the current RegistryRequest

relativeTime

Returns a time in the future or past, relative to the current time where the offset period is determined by specified parameter

getClassificationNodes

Returns all ClassificationNode's that are descendants and / or ancestor of the specified reference ClassificationNode and within the specified number of levels as indicated by the ancestorLevels and descendantLevels parameters.

Table 1: Canonical Functions Defined By This Profile

2.25.1 Canonical Function: currentTime

This canonical function takes no parameters and returns the current time associated with the server.

2.25.1.1 Function Semantics

2.25.2 Canonical Function: currentUserId

This canonical function takes no parameters and returns a string whose value is the id of the user associated with the current RegistryRequest. This specification does not define how user's are managed within the server nor does it define how an id is assigned to a user.

2.25.2.1 Function Semantics

2.25.3 Canonical Function: relativeTime

This canonical function takes a string parameter in the format specified by xs:duration that specify a time offset period and returns a time in the future or past relative to the current time by the specified period.

2.25.3.1 Parameter Summary

Parameter

Description

Data Type

duration

A duration of time in the format as specified by the duration type defined by XML Schema duration type. The duration format supports negative or positive durations so this function may be used to return a time relative to current in the future or the past.

duration

2.25.3.2 Function Semantics

2.25.4 Canonical Function: getClassificationNodes

This canonical function takes a reference ClassificationNode's id as parameter and returns all ClassificationNode's that are descendants and/or ancestors of the specified reference ClassificationNode and within the specified number of levels as indicated by the ancestorLevels and descendantLevels parameters.

2.25.4.1 Parameter Summary

Parameter

Description

Data Type

nodeId

Specifies the id of the reference ClassificationNodeType instance

string

ancestorLevels

Specifies how many levels to match ancestors of reference node

integer

descendantLevels

Specifies how many levels to match descendants of reference node

integer

includeSelf

Specifies whether to include the reference ClassificationNodeType instance or not

boolean

delimiter

The value of this parameter specifies the delimiter string to be used as separator between the tokens representing the ids matched by the function

string

template

The value of this parameter specifies a template to contain each id returned by the function. The template may contain one or more occurrences of template parameter string “${id}” as placeholder for the id of a matched ClassificationNode

string

2.25.4.2 Function Semantics



2.26 Query Plugins

Query plugins allow a server to use specialized extension modules to implement support for a parameterized query. Since query plugins are software modules, they are able to handle highly specialized query semantics that may not be expressed in most query languages. A specific instance of a query plugin is designed and configured to handle a specific parameterized query.

2.26.1 Query Plugin Interface

A Query plugin implements the QueryManager interface. A QueryManager endpoint MUST delegate an executeQuery operation to a Query plugin if a Query plugin has been configured for the requested parameterized query. A Query plugin MUST process the query and return a QueryResponse or fault message to the QueryManager. The QueryManager MUST then deliver that response to the client.

3 LifecycleManager Interface

The LifecycleManager interface allows a client to perform various lifecycle management operations on RegistryObjects. These operations include submitting RegistryObjects to the server, updating RegistryObjects in the server, creating new versions of RegistryObjects in the server and removing RegistryObjects from the server.

A server MUST implement the LifecycleManager interface as an endpoint.

3.1 SubmitObjects Protocol

The SubmitObjects protocol allows a client to submit RegistryObjects to the server. It also allows a client to completely replace existing RegistryObjects in the server.

A client initiates the SubmitObjects protocol by sending a SubmitObjectsRequest message to the LifecycleManager endpoint.

The LifecycleManager sends a RegistryResponse back to the client as response.




Illustration 2: SubmitObjects Protocol




3.1.1 SubmitObjectsRequest

The SubmitObjectsRequest message is sent by a client to submit RegistryObjects to the server.

3.1.1.1 Syntax

<simpleType name="mode">

<restriction base="NCName">

<enumeration value="CreateOrReplace"/>

<enumeration value="CreateOrVersion"/>

<enumeration value="CreateOnly"/>

</restriction>

</simpleType>


<element name="SubmitObjectsRequest">

<complexType>

<complexContent>

<extension base="rs:RegistryRequestType">

<sequence>

<element ref="rim:RegistryObjectList" minOccurs="0" maxOccurs="1"/>

</sequence>

<attribute name="checkReferences" type="boolean" use="optional"

default="false"/>

<attribute name="mode" type="tns:mode" use="optional"

default="CreateOrReplace"/>

</extension>

</complexContent>

</complexType>

</element>

3.1.1.2 Description

3.1.1.3 id and lid Requirements

Table 2 defines the requirements for id and lid attribute values for RegistryObjectType instances that are submitted via the SubmitObjects protocol.



Mode / Requirements

ID Requirements

LID Requirements

CreateOrReplace

  • MUST be specified by client or else server MUST return InvalidRequestException

  • If id does not exists, server MUST create new object using that id (create)

  • If id exists, server MUST replace existing object matching that id (update)

  • MUST be specified by client or else server MUST return InvalidRequestException

CreateOrVersion

  • MUST be specified by client or else server MUST return InvalidRequestException

  • If id does not exists and lid does not exist, server MUST create new object using that id (create)

  • If id does not exists and lid exists, server MUST throw InvalidRequestException (otherwise multiple root level versions would become possible)

  • If id exists, server MUST create a new version of existing object matching that id (version)

  • MUST be specified by client or else server MUST return InvalidRequestException

CreateOnly

  • MAY be specified by client

  • If unspecified Server MUST generate UUID URN

  • If id does not exists, server MUST create new object using that id (create)

  • If id exists, server MUST return ObjectExistsException

  • MUST be specified by client or else server MUST return InvalidRequestException

  • MUST NOT exist or else server MUST return ObjectExistsException

Table 2: Requirements for id and lid During SubmitObjects Protocol



3.1.1.4 Returns

This request returns a RegistryResponse.

3.1.1.5 Exceptions

3.1.2 Audit Trail Requirements

3.1.3 Sample SubmitObjectsRequest

The following simplified example shows a SubmitObjectsRequest that submits a single Organization object to the server.



<lcm:SubmitObjectsRequest>

<rim:RegistryObjectList>

<rim:RegistryObject xsi:type="rim:OrganizationType" lid="${LOGICAL_ID}"

id="${ID}" ...>

...


</rim:RegistryObject>

</rim:RegistryObjectList>

</SubmitObjectsRequest>

3.2 The Update Objects Protocol

The UpdateObjectsRequest protocol allows a client to make partial updates to one or more RegistryObjects that already exist in the server. This protocol enables partial update of RegistryObjects rather than a complete replacement. A client SHOULD use the SubmitObjects protocol for complete replacement of RegistryObjects.

A server MUST return InvalidRequestException fault message if the client attempts to update the id, lid or objectType attribute of a RegistryObject.




Illustration 3: UpdateObjects Protocol




3.2.1 UpdateObjectsRequest

The UpdateObjectsRequest message is sent by a client to partially update existing RegistryObjects in the server. An UpdateObjectsRequest identifies a set of RegistryObjects as target objects to be updated by the request. It also specifies the update action that modifies each target object. Update actions may insert a node within a target object, delete an existing node from a target object or update an existing node within the target object. A node in the context of the UpdateObjects protocol is defined to be an XML DOM node (typically an element or an attribute).

3.2.1.1 Syntax

<element name="UpdateObjectsRequest">

<complexType>

<complexContent>

<extension base="rs:RegistryRequestType">

<sequence>

<!-- Query and ObjectRefList select objects to update -->

<element name="Query" type="rim:QueryType" minOccurs="0" maxOccurs="1" />

<element ref="rim:ObjectRefList" minOccurs="0" maxOccurs="1" />

<!-- Specifies how to update selected objects -->

<element name="UpdateAction" type="tns:UpdateActionType"

minOccurs="1" maxOccurs="unbounded"/>

</sequence>

<attribute name="checkReferences" type="boolean" use="optional"

default="false"/>

<attribute name="mode" type="tns:mode" use="optional"

default="CreateOrReplace"/>

</extension>

</complexContent>

</complexType>

</element>

3.2.1.2 Description

3.2.1.3 Returns

This request returns a RegistryResponse.

3.2.1.4 Exceptions

3.2.2 UpdateAction

An UpdateRequest contains one or more UpdateActions. Each UpdateObjectsRequest defines a specific update action to be performed on each target object.

3.2.2.1 Syntax

<complexType name="UpdateActionType">

<annotation>

<documentation xml:lang="en">

</documentation>

</annotation>

<sequence>

<!-- Value for attribute or element -->

<element name="ValueHolder" type="rim:ValueType"

minOccurs="0" maxOccurs="1"/>

<!--

Value of selector is an XPATH expression that uniquely identifies

an attribute or an element within target documents.

-->

<element name="Selector" type="rim:QueryExpressionType"

minOccurs="1" maxOccurs="1"/>

</sequence>


<!--

Specifies whether to insert, update or delete a node from

target document.

-->

<attribute name="mode" use="required">

<simpleType>

<restriction base="NCName">

<enumeration value="Insert"/>

<enumeration value="Update"/>

<enumeration value="Delete"/>

</restriction>

</simpleType>

</attribute>

</complexType>

3.2.2.2 Description

3.2.3 Audit Trail Requirements

3.2.4 Sample UpdateObjectsRequest

The following example shows an UpdateObjectsRequest which updates the Name element within a PersonType instance with the Name element specified by the Value element within UpdateAction. The Selector element uses an XPATH expression to select the Name element node within the Person objects identified as target of update in the ObjectRefList. The context node of the XPATH expression is the RegistryObject element for the PersonType instance. The target objects could also have been chosen by a Query element.

<UpdateObjectsRequest ...>

<rim:ObjectRefList>

<rim:ObjectRef id="urn:acme:person:Danyal"/>

</rim:ObjectRefList>

<UpdateAction mode="Update">

<Value xsi:type="rim:AnyValueType">

<rim:Name>

<rim:LocalizedString xml:lang="en-US" value="Danny"/>

</rim:Name>

</Value>

<Selector xsi:type="rim:StringQueryExpressionType"

queryLanguage="urn:oasis:names:tc:ebxml-regrep:QueryLanguage:XPath">


<rim:Value>./rim:Name</rim:Value>

</Selector>

</UpdateAction>

</UpdateObjectsRequest>

3.3 RemoveObjects Protocol

The Remove Objects protocol allows a client to remove or delete one or more RegistryObject instances from the server.

A client initiates the RemoveObjects protocol by sending a RemoveObjectsRequest message to the LifecycleManager endpoint.

The LifecycleManager sends a RegistryResponse back to the client as response.




Illustration 4: RemoveObjects Protocol




3.3.1 RemoveObjectsRequest

The RemoveObjectsRequest message is sent by a client to remove one or more existing RegistryObjects from the server.

3.3.1.1 Syntax

<element name="RemoveObjectsRequest">

<complexType>

<complexContent>

<extension base="rs:RegistryRequestType">

<sequence>

<element name="Query" type="rim:QueryType"

minOccurs="0" maxOccurs="1" />

<element ref="rim:ObjectRefList" minOccurs="0" maxOccurs="1" />

</sequence>

<attribute name="checkReferences" type="boolean" use="optional"

default="false"/>

<attribute name="deleteChildren" type="boolean" use="optional"

default="false"/>

<attribute name="deletionScope" type="rim:objectReferenceType"

use="optional" default="urn:oasis:names:tc:ebxml-regrep:DeletionScopeType:DeleteAll"/>

</extension>

</complexContent>

</complexType>

</element>



3.3.1.2 Description

3.3.1.3 Returns:

This request returns a RegistryResponse.

3.3.1.4 Exceptions:

In addition to the exceptions common to all requests, the following exceptions MAY be returned:

3.3.2 Audit Trail Requirements

3.3.3 Sample RemoveObjectsRequest

The following is a sample RemoveObjectsRequest to remove an Object by its id.

<lcm:RemoveObjectsRequest ...>

<rim:ObjectRefList>

<rim:ObjectRef id="urn:acme:Person:Danyal"/>

</rim:ObjectRefList>

</lcm:RemoveObjectsRequest>

4 Version Control

This section describes the version control features of the ebXML RegRep.

Versioning of a RegistryObjectType instance is the process of updating the object in such a way that the original instance remains unchanged while a new instance is created as a new version of the original instance. Any specific version of an object may itself be versioned. Thus in general the versions of an object form a tree structure referred to as the Version Tree for that object.

A Version Tree for an object is defined to be a tree structure where:


Illustration 5: A visual example of a version tree




Illustration 5 visualizes the version tree concept. In this non-normative example the object TestRegister has 8 versions. Each node's version is identified by the parenthesized string suffix like “(1.2.2)”. Version 1 is the original version. Version 1 was versioned twice to create versions 1.1 and 1.2. Version 1.1 was versioned twice to create versions 1.1.1 and 1.1.2. Version 1.2 was versioned twice to create versions 1.2.1 and 1.2.2. Version 1.2.1 was versioned once to create version 1.2.1.1. Note that this example uses a version naming convention for ease of understanding only. This specification does not prescribe a specific version naming convention for server to use when assigning version names.

The terms “logical object” or “logical RegistryObject” are used to refer to all version of a RegistryObject in a version independent manner. The terms “object version” or “RegistryObject version” are used to refer to a specific version of the logical object. The terms “RegistryObject instance” and “RegistryObjectType instance” imply a specific object version.

Illustration 5 visualizes a single logical object TestRegister with 8 object versions.

4.1 Version Controlled Resources

Version controlled resources are resources that support versioning capability.

All repository items in an ebXML RegRep are implicitly version-controlled resources as defined by section 2.2.1 of [DeltaV]. No explicit action is required to make them a version-controlled resource.

Instances of RegistryObjectType types are also implicitly version-controlled resources. The only exceptions are those sub-types of RegistryObjectType that are composed1 types and their instances do not have independent lifecycles that are separate from the lifecycle of their parent objects. Some example of such composed types are:

A server MAY further limit specific non-composed types from being version-controlled resources based upon server specific policies.

4.2 Versioning and Id Attribute

Each object version of a logical RegistryObject is a unique object and as such has its own unique value for its id attribute as defined by [ebRIM].

4.3 Versioning and Lid Attribute

A RegistryObject instance MUST have a Logical ID (LID) defined by its “lid” attribute to identify the logical RegistryObject of which it is a version. All versions of a logical RegistryObject have the same “lid” attribute value. Note that this is in contrast with the “id” attribute that MUST be unique for each version of the same logical RegistryObject. A client may refer to the logical RegistryObject in a version independent manner using its LID.

4.4 Version Identification for RegistryObjectType

A RegistryObjectType instance MUST have a VersionInfo element whose type is the VersionInfoType type defined by ebRIM. The VersionInfo element identifies the version information for that RegistryObjectType instance. The versionName attribute of the VersionInfo element identifies the version name for a specific version of a logical object. A server MUST not allow two versions of the same logical object to have the same versionName attribute value within its VersionInfo element.

4.5 Version Identification for RepositoryItem

When a RegistryObject is an ExtrinsicObject with an associated repository item, the version identification for the repository item is distinct from the version identification for the ExtrinsicObject.

An ExtrinsicObject that has an associated repository item MUST have a contentVersionInfo element whose type is VersionInfoType defined by ebRIM. The contentVersionInfo attributes identifies the version information for that repository item instance.

4.5.1 Versioning of RegistryObjectType

This section describes the versioning of all RegistryObjectType types with the exception of ExtrinsicObjectType which is defined in a separate section.

The following rules apply to versioning of all RegistryObjectType instances that are not instances of ExtrinsicObjectType type. It assumes that versioning is enabled for such RegistryObjectType types:

4.5.2 Versioning of ExtrinsicObjectType

The ExtrinsicObjectType type requires special consideration for versioning because it may have an associated RepositoryItem which is versioned independently from the ExtrinsicObjectType instance.

The following rules apply to versioning of ExtrinsicObjectType instances assuming that a server has versioning enabled for the ExtrinsicObjectType type:

4.6 Versioning and References

An object reference from a RegistryObjectType instance references a specific version of the referenced RegistryObjectType instance. When a server creates a new version of a referenced RegistryObjectType instance it MUST NOT move references from other objects from the previous version to the new version of the referenced object. Clients that wish to always reference the latest versions of an object MAY use the “dynamic reference” defined in ebRIM feature to always reference the latest version.

A special case is when a SubmitObjectsRequest contains an object that is being versioned by the server and the request contains other objects that reference the object being versioned. In such case, the server MUST update all references within the submitted objects to the object being versioned such that those objects now reference the new version of the object being created by the request.

4.7 Versioning of RegistryPackages

When a server creates a new version of a RegistryPackageType instance, it MUST implicitly make all members of the old version also be members of the new version. This requires that the server MUST make a copy of all HasMember Associations in which the old version of the RegistryPackage is the sourceObject as follows:




4.8 Versioning and RegistryPackage Membership

A RegistryPackage MUST NOT contain more than version of the same logical object as its member.

4.9 Inter-version Association

Each RegistryObject node in the version tree of a logical object except for the root version MUST be linked to the RegistryObject node in the version tree that was its immediate predecessor (previous version).

Note that this section is functionally equivalent to the predecessor-set successor-set elements of the Version Properties as defined by [DeltaV].

4.10 Version Removal

Specific versions of a logical object MAY be deleted using the RemoveObjects protocol by specifying the version by its unique id.

4.11 Locking and Concurrent Modifications

This specification does not define explicit checkin and checkout capabilities as defined by [DeltaV]. A server MAY support such features in an implementation specific manner.

This specification does not prescribe a locking model. An implementation may choose to support a locking model in an implementation specific manner. A future specification may address these capabilities.

4.12 Version Creation

The server manages creation of new version of a version-controlled resource automatically. A server that supports versioning MUST implicitly create a new version for the resource if an existing version of the resource is updated via a SubmitObjectsRequest or UpdateObjectsRequest when the mode attribute value is CreateOrVersion. A server MUST update the existing version of a resource without creating a new version when the mode attribute is set to CreateOrReplace.

5 Validator Interface

The Validator interface allows the validation of objects published to the server. The interface may be used by clients to validate objects already published to the server or may be used by the server to validate objects during the processing of the submitObjects or updateObjects protocol

A server MUST implement the Validator interface as an endpoint. The Validator interface validates objects using Validator Plugins specific to the type of object being validated.

5.1 ValidateObjects Protocol

The ValidateObjects protocol is initiated by sending an ValidateObjectsRequest message to the Validator endpoint.


Illustration 6: ValidateObjects Protocol


The Validator endpoint sends an ValidateObjectsResponse back as response. The ValidateObjectsResponse contains information on whether the objects were valid and if invalid objects were found it includes any validation errors that were encountered.

5.1.1 ValidateObjectsRequest

The ValidateObjectsRequest message initiates the validateObjects protocol and specifies the objects that need to be validated.

5.1.1.1 Syntax

<element name="ValidateObjectsRequest">

<complexType>

<complexContent>

<extension base="rs:RegistryRequestType">

<sequence>

<element name="Query" type="rim:QueryType"

minOccurs="0" maxOccurs="1" />

<element ref="rim:ObjectRefList" minOccurs="0" maxOccurs="1" />

<element name="OriginalObjects" type="rim:RegistryObjectListType"

minOccurs="1" maxOccurs="1"/>

<element name="InvocationControlFile"

type="rim:ExtrinsicObjectType"

minOccurs="0" maxOccurs="unbounded"/>

</sequence>

</extension>

</complexContent>

</complexType>

</element>

5.1.1.2 Example

The following example shows a client request to validate a specified WSDL file. It assumes that the server will be configured with a Validator plugin for WSDL files. It also assumes that the server will specify OriginalObjects and InvocationControlFile elements when it relays the request to the appropriate Validator plugin.

<spi:ValidateObjectsRequest ...>

<rim:ObjectRefList>

<rim:ObjectRef id="urn:acme:wsdl:purchaseOrder.wsdl"/>

</rim:ObjectRefList>

</ValidateObjectsRequest>

5.1.1.3 Description

5.1.1.4 Response

This request returns ValidateObjectsResponse as response.

5.1.1.5 Exceptions

In addition to the common exceptions, the following exceptions MAY be returned:

5.1.2 ValidateObjectsResponse

Currently ValidateObjectsResponse is a simple extension to RegistryResponseType and does not define additional attributes or elements.

5.2 Validator Plugins

Validator plugins allow a server to use specialized extension modules to validate specific types of objects during the processing of a SubmitObjectsRequest, UpdateObjectsRequest or a ValidateObjectsRequest.

A specific instance of a Validator plugin is designed and configured to validate a specific type of object. For example, the canonical XML Validator plugin is designed and configured to validate XML Objects using Schematron documents as InvocationControlFile.

5.2.1 Validator Plugin Interface

A Validator plugin implements the Validator interface. The server's Validator endpoint SHOULD delegate a validateObjects operation to any number of Validator plugins using the following algorithm:

5.2.2 Canonical XML Validator Plugin

The canonical XML Validator plugin is a validator plugin that validates XML content using a Schematron file as InvocationControlFile. The Schematron file specifies validation rules using [Schematron] language to validate XML content. The server may configure the canonical XML Validator plugin such that it is invoked with an appropriate schematron file as InvocationControlFile based upon the objectType of the object being validated.

6 Cataloger Interface

The Cataloger interface allows a client to catalog or index objects already in the server. The interface may be used by clients to catalog objects already published to the server or may be used by the server to catalog objects during the processing of the submitObjects or updateObjects protocol .

A server MUST implement the Cataloger interface as an endpoint. The Cataloger interface catalogs objects using Cataloger Plugins specific to the type of object being cataloged.

6.1 CatalogObjects Protocol

A client catalogs RegistryObjects residing in the server using the CatalogObjects protocol supported by the catalogObjects operation of the Cataloger interface.

The CatalogObjects protocol is initiated by sending an CatalogObjectsRequest message to the Cataloger endpoint.




Illustration 7: CatalogObjects Protocol




The Cataloger endpoint sends a CatalogObjectsResponse back to the client as response.

6.1.1 CatalogObjectsRequest

The CatalogObjectsRequest message initiates the catalogObjects protocol and specifies the objects that need to be cataloged.

6.1.1.1 Syntax

<element name="CatalogObjectsRequest">

<complexType>

<complexContent>

<extension base="rs:RegistryRequestType">

<sequence>

<element name="Query" type="rim:QueryType"

minOccurs="0" maxOccurs="1" />

<element ref="rim:ObjectRefList" minOccurs="0" maxOccurs="1" />

<element name="OriginalObjects" type="rim:RegistryObjectListType"

minOccurs="0" maxOccurs="1"/>

<element name="InvocationControlFile"

type="rim:ExtrinsicObjectType"

minOccurs="0" maxOccurs="unbounded"/>

</sequence>

</extension>

</complexContent>

</complexType>

</element>

6.1.1.2 Example

The following example shows a client request to catalog a specified WSDL file. It assumes that the server will be configured with a Cataloger plugin for WSDL files. It also assumes that the server will specify OriginalObjects and InvocationControlFile elements when it relays the request to the appropriate Cataloger plugin.

<spi:CatalogObjectsRequest ...>

<rim:ObjectRefList>

<rim:ObjectRef id="urn:acme:wsdl:purchaseOrder.wsdl"/>

</rim:ObjectRefList>

</CatalogObjectsRequest>

6.1.1.3 Description



6.1.1.4 Response

This request returns CatalogObjectsResponse as response.

6.1.1.5 Exceptions

In addition to common exceptions, the following exceptions MAY be returned:

6.1.2 CatalogObjectsResponse

The CatalogObjectsResponse message is sent by the Cataloger endpoint in response to an CatalogObjectsRequest.

6.1.2.1 Syntax

<element name="CatalogObjectsResponse">

<complexType>

<complexContent>

<extension base="rs:RegistryResponseType">

</extension>

</complexContent>

</complexType>

</element>

6.1.2.2 Example

The following example shows a CatalogObjectsResponse sent by a server to the client in response to a CatalogedObjectRequest. It shows that the Cataloger augmented the Original object with a new Slot that catalogs the target namespace used by the WSDL file.



<CatalogObjectsResponse status="urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Success">

<rim:RegistryObjectList>

<rim:RegistryObject xsi:type="rim:ExtrinsicObjectType"

mimeType="text/xml"

status="urn:oasis:names:tc:ebxml-regrep:StatusType:Submitted"

objectType="urn:oasis:names:tc:ebxml-regrep:ObjectType:RegistryObject:ExtrinsicObject:XML:WSDL"

lid="urn:acme:wsdl:purchaseOrder.wsdl"

id="urn:acme:wsdl:purchaseOrder.wsdl">

<rim:Slot

name="urn:oasis:names:tc:ebxml-regrep:profile:wsdl:slot:targetNamespace">

<rim:SlotValue xsi:type="rim:StringValueType">

<rim:Value>urn:acme:Service:PurchaseOrder</rim:Value>

</rim:SlotValue>

</rim:Slot>

<rim:RepositoryItem>...binary encoded content...</rim:RepositoryItem>

</rim:RegistryObject>

</rim:RegistryObjectList>

</CatalogObjectsResponse>

6.1.2.3 Description

In addition to elements and attributes defined by RegistryResponseType the following are defined:

6.2 Cataloger Plugins

Cataloger plugins allow a server to use specialized extension modules to catalog specific types of objects during the processing of a SubmitObjectsRequest, UpdateObjectsRequest or a CatalogObjectsRequest.

A specific instance of a Cataloger plugin is designed and configured to catalog a specific type of object. For example, the canonical XML Cataloger plugin is designed and configured to catalog XML Objects using XSLT documents as InvocationControlFile.

6.2.1 Cataloger Plugin Interface

A Cataloger plugin implements the Cataloger interface. The server's Cataloger endpoint SHOULD delegate a catalogObjects operation to any number of Cataloger plugins using the following algorithm:

6.2.2 Canonical XML Cataloger Plugin

The canonical XML Cataloger plugin is a Cataloger plugin that catalogs XML content using an XSLT file as InvocationControlFile. The XSLT file specifies transformations rules using [XSLT] language to catalog XML content. The server may configure the canonical XML Cataloger plugin such that it is invoked with an appropriate XSLT file as InvocationControlFile based upon the objectType of the object being cataloged.

An XSLT file used as InvocationControlFile with the Canonical XML Cataloger MUST meet the following constraints:

A server MUST implement the Canonical XML Cataloger with the following constraints:



7 Subscription and Notification

A client MAY subscribe to events that transpire in the server by creating a Subscription. A server supporting Subscription and Notification feature MUST deliver a Notification to the subscriber when an event transpires that matches the event selection criteria specified by the client.

7.1 Server Events

Activities within the server result in events. [ebRIM] defines the AuditableEvent element, instances of which represent server events. A server creates AuditableEvent instances during the processing of client requests.

7.1.1 Pruning of Events

A server MAY periodically prune AuditableEvents in order to manage its resources. It is up to the server when such pruning occurs. A server SHOULD perform such pruning by removing the older AuditableEvents first.

7.2 Notifications

A Notification message is used by the server to notify clients of events they have subscribed to. A Notification contains the RegistryObjects, or references to the RegistryObjects, that are affected by the event for which the Notification is being sent, based upon the notificationOption within the DeliveryInfo for the subscription.

Details for the Notification element are defined in [ebRIM].

7.3 Creating a Subscription

A client MAY create a subscription within a server if it wishes the server to send it a Notification when a specific type of event transpires. A client creates a subscription by submitting a rim:SubscriptionType instance to the server using the standard SubmitObjects protocol.

Details for the rim:SubscriptionType are defined in [ebRIM].

7.3.1 Subscription Authorization

A deployment MAY use custom Access Control Policies to decide which users are authorized to create a subscription and to what events. A server MUST return an AuthorizationException in the event that an unauthorized user submits a Subscription to a server.

7.3.2 Subscription Quotas

A server MAY use server specific policies to decide an upper limit on the number of Subscriptions a user is allowed to create. A server SHOULD return a QuotaExceededException in the event that an authorized user submits more Subscriptions than allowed by their server-specific quota.

7.3.3 Subscription Expiration

Each subscription MAY define a startTime and endTime attribute which determines the period within which a Subscription is valid. If startTime is unspecified then a server MUST set it to the time of submission of the subscription. If endTime is unspecified then the server MUST choose a default value based on its policies.

Outside the bounds of the valid period, a Subscription MAY exist in an expired state within the server. A server MAY remove an expired Subscription at any time.

A server MUST NOT deliver notifications for an event to an expired Subscriptions. An expired Subscription MAY be renewed by updating the startTime and / or endTime for the Subscription using the UpdateObjects protocol.

7.3.4 Event Selection

A client MUST specify a Selector element within the Subscription to specify its criteria for selecting events of interest. The Selector element is of type rim:QueryType and specifies an parameterized query to be invoked with specified query parameters.

A server MUST process AuditableEvents and determine which Subscriptions match the event using the algorithm illustrated by the following pseudo-code fragment:



//Get objects that match selector query

List<RegistryObjectType> objectsOfInterest =

getObjectsMatchingSelectorQuery(selectorQuery);
        
if (objectsOfInterest.size() > 0) {


  //Now get AuditableEvents that affected objectsOfInterest

//MUST not include AuditableEvents that have already been delivered

//to this subscriber
  List<RegistryObjectType> eventsOfInterest =

getEventsOfInterest(objectsOfInterest);

if (eventsOfInterest.size() > 0) {
//Now create Notification on objectsOfInterest.
    //Notification will include eventsOfInterest that only include objects

//that are affected by the event and are also in objectsOfInterest
NotificationType notification = createNotification(

objectsOfInterest, eventsOfInterest);

    //Now send notification using info in DeliveryInfo
    sendNotification(notification);
  }
}



7.4 Event Delivery

A client MAY specify zero or more DeliveryInfo elements within the Subscription to specify how the server should deliver events matching the subscription to the client. The DeliveryInfo element MUST include a NotifyTo element which specifies an EndPoint Reference (EPR) as defined by [WSA-CORE]. The NotifyTo element contains a <wsa:Address> element which contains a URI to the endpoint.

Details for the DeliveryInfo element are defined in [ebRIM].

7.4.1 Notification Option

A client MAY specify a notificationOption attribute in DeliveryInfo element of a Subscription. The notificationOption attribute specifies how the client wishes to be notified of events. This attribute controls whether the Event within a Notification contains complete RegistryObjectType instances or only ObjectRefType instances. It is defined in detail in ebRIM.

7.4.2 Delivery to NotificationListener Web Service

If the <wsa:Address> element has a rim:endpointType attribute value of “urn:oasis:names:tc:ebxml-regrep:endPointType:soap”, then the server MUST use the specified address as the web service endpoint URL to deliver the Notification to. The target web service in this case MUST implement the NotificationListener interface.

7.4.3 Delivery to Email Address

If the <wsa:Address> element has a rim:endpointType attribute value of “urn:oasis:names:tc:ebxml-regrep:endPointType:rest”, then the server MUST use the specified address as the email address to deliver the Notification via email. This specification does not define how a server is configured to send Notifications via email.

7.4.4 Delivery to a NotificationListener Plugin

If the <wsa:Address> element has a rim:endpointType attribute value of “urn:oasis:names:tc:ebxml-regrep:endPointType:plugin”, then the server MUST use the specified address as a Notification plugin identifier and deliver the Notification via local call to the plugin. This specification does not define how a server is configured for Notification plugins.

7.4.4.1 Processing Email Notification Via XSLT

A client MAY specify an XSLT style sheet within a DeliveryInfo element to process a Notification prior to it being delivered to an email address. The XSLT style sheet MAY be specified using a Slot in DeliveryInfo element where the Slot's name is “urn:oasis:names:tc:ebxml-regrep:rim:DeliveryInfo:emailNotificationFormatter” and the Slots value is the id of an ExtrinsicObject whose repository item is the XSLT. The ExtrinsicObject and repository item MUST be submitted prior to or at the same time as the Subscription.

7.5 NotificationListener Interface

The NotificationListener interface allows a client to receive Notifications from the server for their Subscriptions. A client MUST implement the NotificationListener interface as an endpoint if they wish to receive Notifications via SOAP or REST. A server MUST implement a NotificationListener interface as an endpoint if it supports the object replication feature as this endpoint will be used by remote servers to deliver Notification of changes to replicated objects.

7.6 Notification Protocol

A server sends a Notification to an endpoint using the Notification protocol supported by the onNotification operation of the NotificationListener interface.

A server initiates the Notification protocol by sending a Notification message to the NotificationListener endpoint registered within the Subscription for which the Notification is being delivered.


Illustration 8: Notification Protocol


The onNotification operation does not send a response back to the server.

7.6.1 Notification

The Notification message is sent by client to the NotificationListener interface deliver an event notification for a subscription. It is a one-way request pattern and produces no response. The syntax and semantics of the Notification message is described in detail in ebRIM.

7.7 Pulling Notification on Demand

A client MAY “pull” Notifications for a Subscription by invoking the GetNotification canonical query. A client MAY specify a startTime since which it wishes to include events within the pulled Notification. If client does not specify a startTime then all events since the last “push” delivery to that client's NotifyTo endpoint MUST be included in the Notification. If Subscription does not define any “push” delivery for that client's NotifyTo endpoint then a client MUST use startTime parameter to avoid getting the same events within the Notification returned by the GetNotification query.

Pulling a Notification leaves the Notification intact on the server for any potential pushing of the Notification to endpoints defined in DeliveryInfo elements of the Subscription.

7.8 Deleting a Subscription

A client MAY terminate a Subscription with a server if it no longer wishes to be notified of events related to that Subscription. A client terminates a Subscription by deleting the corresponding Subscription object using the standard RemoveObjects protocol.

8 Multi-Server Features

This chapter describes features of ebXML RegRep that involve more than one ebXML RegRep server instances. These features include:

8.1 Remote Objects Reference

A RegistryObject in one ebXML RegRep server MAY contain a reference to a RegistryObject in any other ebXML RegRep server that is compatible with ebXML RegRep specifications of a compatible version number as the source server. Remote object reference feature does not require the local and remote servers to be part of the same federation. Remote object references are described in detail in [ebRIM].



Frame11

8.2 Local Replication of Remote Objects

RegistryObjects within a server MAY be replicated in another server. A replicated copy of a remote object is referred to as its replica. The remote object MAY be an original object or it MAY be a replica. A replica from an original is referred to as a first-generation replica. A replica of a replica is referred to as a second-generation replica (and so on).

A server that replicates a remote object locally is referred to as the local server for the replication. The server that contains the remote object being replicated is referred to as the remote server for the replication.

Frame10

The following rules govern replication of remote objects:

8.2.1 Creating Local Replica and Keeping it Synchronized

Replication feature relies upon the Subscription and Notification feature to keep replicas synchronized with changes to the remote object. A local replica of a remote objects is created as follows:

A server MUST use standard QueryManager interface to read the state of a remote object. No prior registration or contract is needed for a server to read the state of a remote object if that object is readable by anyone, as is the case with the default access control policy.

Once the state of the remote object has been read, a server MAY use server specific means to create a local replica of the remote object.

A server MUST set a Slot with name “urn:oasis:names:tc:ebxml-regrep:rim:RegistryObject:home” on a local replica. The value of the Slot MUST be a StringValueType that specifies the base URL of the home server for the remote object that is the source of the local replica. A server MUST NOT set a Slot with name “urn:oasis:names:tc:ebxml-regrep:rim:RegistryObject:home” on a local object within its home server. The presence of this slot distinguished a local replica of a remote object from a local object.

8.2.2 Removing a Local Replica

An authorized client can remove a local replica in the same manner as removal of local objects using the standard RemoveObjects protocol.

8.2.3 Removing Subscription With Remote Server

An authorized client can remove the Subscription at the remote server that was created on behalf of the local server using the standard RemoveObjects protocol with the remote server.

8.3 Registry Federations

A server federation is a set of ebXML RegRep servers that have voluntarily agreed to form a loosely coupled union. Such a federation may be based on common business interests or membership in a community-of-interest. Registry federations enabled clients to query the content of their member servers using federated queries as if they are a single logical server.

Frame8

8.3.1 Federation Configuration

A deployment MAY configure a set of related ebXML RegRep servers as a Federation using the Registry and Federation classes defined in detail by [ebRIM]. Instances of these classes and the associations between these instances describe a federation and its members.

The Federation information model is described in [ebRIM].

8.3.1.1 Creating a Federation

The following rules govern how a federation is created:

8.3.1.2 Joining a Federation

The following rules govern how a server joins a federation:

8.3.1.3 Leaving a Federation

The following rules govern how a server leaves a federation:

8.3.1.4 Dissolving a Federation

The following rules govern how a federation is dissolved:

8.3.2 Local Vs. Federated Queries

A client MAY query a federation as a single unified logical server. A QueryRequest sent by a client to a federation member MAY be local or federated depending upon the value of the federated attribute of the QueryRequest.

8.3.2.1 Local Queries

When the federated attribute of QueryRequest has the value of false (default) then the query is a local query.

A local QueryRequest is only processed by the server that receives the request.

8.3.2.2 Federated Queries

When the federated attribute of QueryRequest has the value of true then the query is a federated query.

A server MUST route a federated query received by it to all servers that are represented by RegistryType instances in the membership tree of the federation(s) that is the target of the federated query on a best attempt basis.

If an exception is encountered while dispatching a query to a federation member the server MUST return a QueryResponse as follows:

When a server routes a federated query to a federation member server then it MUST set the federated attribute value of the QueryRequest to false and the federation attribute value to null to avoid infinite loops.

A federated query operates on data that is distributed across all the members of the target federation.

When a client submits a federated query to a server and no federations exist in the server, then the server MUST treat it as a local query.

The following rules apply to the treatment of iterative queries when the query is federated:

8.3.3 Local Replication of Federation Configuration

A federation member is required to locally cache the federation configuration metadata in the Federation home server for each federation that it is a member of. A server SHOULD use the replication feature for locally caching the Federation configuration.

The federation member MUST keep the cached federation configuration synchronized with the original object in the Federation home.

8.3.4 Time Synchronization Between Federation Members

Federation members are not required to synchronize their system clocks with each other. However, each Federation member SHOULD keep its clock synchronized with an atomic clock server within the latency described by the replicationSyncLatency attribute of the Federation.

9 Governance Features

This chapter specifies how a server supports governance of RegistryObjects.

Governance is defined as the enforcement of business processes and policies defined by a Community of Practice, that guide, direct, and control how its members collaborate to achieve its business goals.

Within this specification, governance is defined as the enforcement of collaborative business processes and policies defined by a Community of Practice to manage the end-to-end life cycle of RegistryObjects within the server. Such collaborative business processes will be referred to as “governance collaborations”.

The remainder of this chapter specifies:



9.1 Representing a Governance Collaboration

This specification makes use of BPMN 2.01 [BPMN2] to represent business collaborations that govern RegistryObjects as follows:

A governance collaboration consists of one or more participants where each participant's activities within the collaboration is described by a separate BPMN process and the interaction between the participants' processes is described by a single BPMN collaboration.

Detailed specification of how to describe governance collaborations in BPMN 2.0 XML format and how a server executes them in a BPMN process engine are provided later in this chapter.


Illustration 12: Default Governance Collaboration





Illustration 12 below provides an example of the Default Governance Collaboration represented by a BPMN 2.0 diagram notation. The Default Governance Collaboration is provided as a standard governance collaboration readily available for use in any server. It is described in detail later in this chapter.



9.1.1 Content of Governance Collaboration BPMN Files

The collective content of the Governance Collaboration BPMN files, whether organized as a set of related modular files or a single monolithic file, MUST meet the following requirements:



9.2 Scope of Governance Collaborations

A governance collaboration may govern a single RegistryObject or it may govern a set of related RegistryObjects packaged together within a RegistryPackage as a single unit of governance. In either case, the target object of the governance collaboration is referred to as the governed object.

9.2.1 Packaging Related Objects as a Governance Unit

A client MUST publish a set of related RegistryObjects that are to be governed by the server as a single unit as follows:

A server MUST treat RegistryPackages with a canonical slot with name “urn:oasis:names:tc:ebxml-regrep:rim:RegistryPackage:packageType” as the governed object.

9.3 Assigning a Governance Collaboration

A governance collaboration as represented by a BPMN2 XML file is not directly assigned to a RegistryObject. Instead it is assigned to a RegistryPackage and is implicitly applicable to RegistryObjects that are members of the RegistryPackage.

Governance collaboration MAY be assigned to a specific RegistryPackage using a “GovernedBy” Association as follows:

9.4 Determining Applicable Governance Collaboration

For any given RegistryObject, a server MUST use the following algorithm to determine the applicable governance collaboration (if any):

  1. Check if objects is an immediate member of a RegistryPackage that has a canonical slot with name “urn:oasis:names:tc:ebxml-regrep:rim:RegistryPackage:packageType”.

    1. If it is so, then the object is not governed directly and instead its parent RegistryObjects is the governed object

    2. Otherwise, proceed to next step

  2. Check if there is a governance collaboration assigned to a RegistryPackage ancestor using the canonical “HasGovernance” Association as follows:

    1. Do a breadth-first traversal of the tree consisting of all RegistryPackage ancestors of the object and for each RegistryPackage see if it has a governance collaboration assigned to it

    2. Stop when you find the first such governance collaboration

    3. If a governance collaboration is found then use it as applicable governance collaboration

  3. If no RegistryPackage-specific governance collaboration is found then the object is not governed by any governance collaboration

9.5 Determining the Registry Process in a Governance Collaboration

For any given governance collaboration, a server MUST use the following algorithm to determine the special Registry process:

  1. Find the participant element within the collaboration whose id is the canonical “registryParticipant”

  2. Find the processRef attribute of the “registryParticipant” and use the referenced process as the Registry process

9.6 Starting the Registry Process for a Governance Collaboration

The BPMN process for the “registryParticipant” within a governance collaboration is the only process in the collaboration that is required to be executed by the server within a BPMN process engine. This section specifies when and how a server starts this process.

9.6.1 Starting Registry Process By WorkflowAction

A server MAY start the Registry process for a governance collaboration in response to the publishing of a WorkflowAction object. This is specified in detail in 10.8.1.1 Server Processing of WorkflowAction.

9.7 Incoming messageFlows to Registry Process

Within a governance collaboration, a server MUST support incoming messageFlows to the Registry process from other processes in the collaboration that meet the following requirements:



A server MAY support other types of incoming messages.

9.8 Outgoing messageFlows from Registry Process

A Registry process communicates with non-Registry processes by sending them notification messages. These messages may be an email message to an email endpoint for a person or a rim:NotificationType message to a service endpoint. Details are provided in the specification for the SendNotification task pattern.

A server MAY support other types of outgoing messages.

9.9 Canonical Task Patterns

This section specifies a set of canonical task patterns that may be used within participant processes in a governance collaboration. Some of these task patterns can only be used within the Registry process while some may only be used in the non-Registry processes of a governance collaboration.

The following table provides a brief summary each of the canonical tasks defined by this specification. Subsequent sections specify these tasks in more detail.



Task Pattern

Task Type

Used
In

Description

SendWorkflow
Action

sendTask

Non-Registry Process

Sends a WorkflowAction message to the Registry process

ReceiveWorkflow
Action

receiveTask

Registry Process

Waits until a WorkflowAction message is received from a non-Registry process

SendNotification

scriptTask

Registry Process

Sends a Notification message to a non-Registry process

ReceiveNotification

receiveTask

Non-Registry Process

Receives a Notification message from the Registry process

SetStatus

scriptTask

Registry Process

Sets the status of the specified RegistryObject

Validate

serviceTask

Any Process

Validates a RegistryObject

Catalog

serviceTask

Any Process

Catalogs a RegistryObject



9.9.1 SendWorkflowAction Task Pattern

This canonical task pattern is used by a sendTask to represent the performing of a process-specific action upon the governed object. This task pattern is the primary means for a non-Registry process to send a message to the Registry process to trigger the Registry process forward.

Task Inputs: The task has the following inputs as defined by dataInput elements in its ioSpecification:

Task Outputs:The task has no outputs.

Task Actors: This task SHOULD be performed by a role other than Registry role to indicate that some external action (e.g. “approval”) has been performed on the targetObject specified by the WorkflowAction.

Description: To perform this task the actor submits a WorkflowAction to the server using the standard SubmitObjects protocol. The name of the task SHOULD reflect the action being performed by the task (e.g. name='SendWorkflowAction(RequestForReview)'. The WorkflowAction MUST specify:

9.9.1.1 Server Processing of WorkflowAction

Upon publishing of a WorkflowAction a server MUST process it as shown in the following pseudo-code and explained further below:



WorkflowActionType workflowAction = ...;

Collaboration collaboration =

getApplicableGovernanceCollaboration(workflowAction.getTargetObject());


if (collaboration != null) {

Process registryProcess = collaboration.getRegistryProcess();

if (registryProcess != null) {

if (!registryProcess.isActive()) {

registryProcess.start();

}

registryProcess.deliverMessage(workflowAction);

}

}



  1. Determine and get the applicable Governance Collaboration (as defined in 10.3 Determining Applicable Governance Collaboration)

  2. Determine and get the applicable Registry process for the collaboration (as defined in 10.4 Determining the Registry Process in a Governance Collaboration)

  3. If the Registry process has not yet been started then start it within the BPMN process engine

  4. Deliver the WorkflowAction message to the Registry process where presumably a receiveTask based on the ReceiveWorkflowAction task pattern is waiting for it



9.9.2 ReceiveWorkflowAction Task Pattern

This canonical task pattern is used by a receiveTask that waits for a process-specific action to be performed upon the governed object. This task pattern is the primary means for the Registry process to receive a message from a non-Registry process to trigger the Registry process forward.

Task Inputs: The task has the following inputs as defined by dataInput elements in its ioSpecification:

Task Outputs:The task has no outputs.

Task Actors: This task MUST be performed by the Registry role to wait until some external action (e.g. “approval”) has been performed on the targetObject specified by the WorkflowAction.

Description: This task waits until the server delivers a WorkflowAction message to the Registry process. The name of the task SHOULD reflect the action being performed (e.g. name='ReceiveWorkflowAction(RequestForReview)'. The task is typically followed by sequenceFlow elements that have a conditionExpression that predicate on the value of the action attribute of the WorkflowAction.

9.9.3 SendNotification Task Pattern

This canonical task pattern is used by a scriptTask to send a Notification message regarding the governed object to the roles and email addresses specified for the task. This task pattern is the primary means for the Registry process to send a message to a non-Registry process to trigger the non-Registry process forward.

Task Inputs: None

Task Outputs: None

Task Actors: This task MUST be performed by the Registry role to keep governance roles for the governed object informed of important changes (e.g. status attribute changes) during the course of the life cycle of the governed object.

Description: To perform this task the actor uses the sendNotification canonical XPATH extension function defined later in this chapter. The name of the task SHOULD reflect the nature of the notification being sent by the task (e.g. name='SendNotification(Accept)'.

9.9.4 ReceiveNotification Task Pattern

This canonical task pattern is used by a receiveTask that waits for a Notification message to be delivered. This task pattern is the primary means for a non-Registry process to receive a message from the Registry process to trigger the non-Registry process forward.

Task Inputs: The task has the following inputs as defined by dataInput elements in its ioSpecification:

Task Outputs:The task has no outputs.

Task Actors: This task MUST be performed by a non-Registry role

Description: This task waits until the server delivers a Notification message. The name of the task SHOULD reflect the nature of the notification being received by the task (e.g. name='ReceiveNotification(Accept)'.

9.9.5 SetStatus Task

This canonical task pattern is used by a scripTask that updates the status of the specified object to a specified status value.

Task Inputs: None

Task Outputs: None

Task Actors: This task MUST be performed by the Registry role to reflect changes in life cycle status during the course of the life cycle of the governed object.

Description: To perform this task the actor uses the setStatus canonical XPATH extension function defined later in this chapter. The name of the task SHOULD reflect the status being set by the task (e.g. name='SendStatus(Approved)'.

9.9.6 Validate Task

This canonical task represents the validation of the governed object.

Task Inputs: The task has no explicit inputs.

Task Outputs:The task has no outputs.

Task Actors: This task SHOULD be performed by the Registry role in response to the creation or updating of the governed object.

Description: To perform this task the actor validates the governed object using the standard ValidateObjects protocol. The name of the task SHOULD be 'Validate' or an equivalent native language translation.

9.9.7 Catalog Task

This canonical task represents the cataloging of the governed object.

Task Inputs: The task has no explicit inputs.

Task Outputs: The task has no outputs.

Task Actors: This task SHOULD be performed by the Registry role in response to the creation or updating of the governed object.

Description: To perform this task the actor catalogs the governed object using the standard CatalogObjects protocol. The name of the task SHOULD be 'Catalog' or an equivalent native language translation.

9.10 XPATH Extension Functions

The following table specifies XPATH extension functions that MUST be supported by the BPMN process engine used by the server. The function signatures are described using the same conventions as used in section 1.4 of [XPATHFUNC].

These functions MAY be used within XPATH expressions in a BPMN file wherever a tExpression type is supported by the BPMN schema.



XPATH Extension Function

Description

rs:generateId() as xs:string

Returns a newly generated unique id for a RegistryObject. This SHOULD be a URN in the urn:uuid namespace

rs:getRegistryObject(id as xs:string) as element()

Returns the RegistryObject element for the RegistryObject that matches the specified id after retrieving it from the server. This is typically used to get the governed object.

rs:setStatus(targetObject as xs:string, status as xs:string) as none

Sets the status of the object matching targetObject with the specified status. Used by the SetStatus task pattern. This function returns no value.

rs:sendNotification(toRoles as xs:string*, toEmails as xs:string*, subject as xs:string?, message as xs:string) as none

Send a notification message using an optional subject to specified roles and email addresses. If toRoles is specified then the server MUST be able to resolve each role to a target person or service instances and determine a delivery endpoint for the target. The message SHOULD be specified as a CDATA if it contains any special characters used by XML. This function returns no value. Used by the SendNotification task pattern.



In addition to the functions described in table above, all canonical query functions supported by the server MUST also be supported by the server as XPATH functions.

9.11 Default Governance Collaboration

This section defines a canonical governance collaboration called the “Default Governance Collaboration”. The Default Governance Collaboration is defined by this specification to provide a standard governance process that can be supported by all implementations and may be assigned to specific RegistryPackages.

The Default Governance Collaboration is represented by a canonical ExtrinsicObjectType instance with id “urn:oasis:names:tc:ebxml-regrep:collaboration:DefaultGovernanceCollaboration”.

A BPMN diagram for the Default Governance Collaboration has been provided in Illustration 12 earlier.

The Default Governance Collaboration is summarized as follows:

10 Security Features

This chapter describes the security features of ebXML RegRep. A glossary of security terms can be referenced from [RFC 2828]. This specification incorporates by reference the following specifications:



10.1 Message Integrity

A server MUST provide for message integrity to ensure that client requests and server responses are not tampered with during transmission (man-in-the-middle attack).

10.1.1 Transport Layer Security

A server SHOULD support HTTP/S protocol for all ebXML RegRep protocols defined by this specification. HTTP/S protocol support SHOULD allow for both SSL and TLS as transport protocols.

10.1.2 SOAP Message Security

A server MUST support soap message security for all ebXML RegRep protocols defined by this specification when those protocols are bound to SOAP.

SOAP message security MUST conform to [WSS-CORE].

The [WSS-CORE] has several profiles for supporting various types of security tokens in a standard manner. A server MUST support at least one of the following types of security token:

10.2 Message Confidentiality

A server SHOULD support encryption of protocol messages as defined by section 9 of [WSS-CORE] as a mechanism to support confidentiality of all ebXML RegRep protocols defined by this specification when those protocols are bound to SOAP.

10.3 User Registration and Identity Management

A server MUST provide a user registration mechanism to register and manage authorized users of the server. A server MUST also provide an identity management mechanism to register and manage the security tokens associated with registered users. This specification does not define how a server provides user registration and identity management mechanisms.

10.4 Authentication

A server MUST support authentication of the client requests based on the security tokens provided by the client and supported by the server. This specification does not specify the mechanism used by a server to authenticate client requests. Server implementations MAY use any means to provide authentication capability.

10.5 Authorization and Access Control

A server MUST control access by client to resources it manages based upon:

A server MUST provide an access control and authorization mechanism based upon chapter titled “Access Control Information Model” in [ebRIM]. This model defines a default access control policy that MUST be supported by the server. In addition it also defines a binding to [XACML] that allows fine-grained access control policies to be defined.

10.6 Audit Trail

A server MUST keep a journal or audit trail of all operations that result in changing the state of its resources. This provides a basic form of non-repudiation where a client cannot repudiate that it performed actions that are logged in the Audit Trail.

A server MUST create an audit trail for each request that affected the state of server resources. A server MUST create this audit trail using AuditableEventType instances as define by the chapter title “Event Information Model” of [ebRIM].

Details of how a server maintains an Audit Trail of client requests is described in the chapter title “Event Information Model” of [ebRIM].

11 Native Language Support (NLS)

This chapter describes the Native Languages Support (NLS) features of ebXML RegRep.

11.1 Terminology

The following terms are used in NLS.

NLS Term

Description

Coded Character Set (CCS)

CCS is a mapping from a set of abstract characters to a set of integers. [RFC 2130]. Examples of CCS are ISO-10646, US-ASCII, ISO-8859-1, and so on.

Character Encoding Scheme (CES)

CES is a mapping from a CCS (or several) to a set of octets. [RFC 2130]. Examples of CES are ISO-2022, UTF-8.

Character Set (charset)

  • Charset is a set of rules for mapping from a sequence of octets to a sequence of characters.[RFC 2277],[RFC 2278]. Examples of character set are ISO-2022-JP, EUC-KR.

  • A list of registered character sets can be found at [IANA].



11.2 NLS and Registry Protocol Messages

For the accurate processing of data in both client and server, it is essential for the recipient of a protocol message to know the character set being used by it.

A client SHOULD specify charset parameter in MIME header when they specify text/xml as Content-Type.

The following is an example of specifying the character set in the MIME header.


Content-Type: text/xml; charset=ISO-2022-JP




If a server receives a protocol message with the charset parameter omitted then it MUST use the default charset value of "us-ascii" as defined in [RFC 3023].

Also, when an application/xml entity is used, the charset parameter is optional, and client and server MUST follow the requirements in Section 4.3.3 of [REC-XML] which directly address this contingency.

If another Content-Type is used, then usage of charset MUST follow [RFC 3023].

11.3 NLS Support in RegistryObjects

The information model XML Schema [RR-RIM-XSD] defines the rim:InternationalStringType for defining elements that contains a locale sensitive string value.



<complexType name="InternationalStringType">

<sequence>

<element name="LocalizedString" type="tns:LocalizedStringType"

minOccurs="0" maxOccurs="unbounded" />

</sequence>

</complexType>



An InternationalStringType may contain zero or more rim:LocalizedString elements within it where each LocalizedString contain a string value is a specified local language.

<complexType name="LocalizedStringType">

<attribute ref="xml:lang" use="optional" default="en-US"/>

<attribute name="value" type="tns:FreeFormText" use="required"/>

</complexType>



Examples of such elements are the “Name” and “Description” elements of the RegistryObject class defined by [ebRIM].

An element InternationalString is capable of supporting multiple locales within its collection of LocalizedStrings.

The schema allows a single RegistryObject instance to include values for any NLS sensitive element in multiple locales.

The following example illustrates how a single RegistryObject can contain NLS sensitive <rim:Name> and “<rim:Description> elements with their value specified in multiple locales. Note that the <rim:Name> and <rim:Description> use the rim:InternationalStringType as their type.

<rim:RegistryObject xsi:type="rim:ExtrinsicObjectType"...>

<rim:Name>

<rim:LocalizedString xml:lang="en-US" value="customACP1.xml"/>

<rim:LocalizedString xml:lang="fi-FI" value="customACP1.xml"/>

<rim:LocalizedString xml:lang="pt-BR" value="customACP1.xml"/>

</rim:Name>

<rim:Description>

<rim:LocalizedString xml:lang="en-US" value="A sample custom ACP"/>

<rim:LocalizedString xml:lang="fi-FI" value="Esimerkki custom ACP"/>

<rim:LocalizedString xml:lang="pt-BR" value="Exemplo de ACP customizado"/>

</rim:Description>

</rim:RegistryObjectType>



Since locale information is specified at the sub-element level there is no language associated with a specific RegistryObject instance.

11.3.1 Language of a LocalizedString

The language MAY be specified in xml:lang attribute (Section 2.12 [REC-XML]).

11.3.2 Character Set of RegistryObject

The character set used by a RegistryObjects is defined by the charset attribute within the Content-Type mime header for the XML document containing the RegistryObject as shown below:



Content-Type: text/xml; charset="UTF-8"





Clients SHOULD specify UTF-8 or UTF-16 as the value of the charset attribute of LocalizedStrings for maximum interoperability. A server MUST preserve the charset of a repository item as it is originally specified when it is submitted to the server.

11.4 NLS and Repository Items

While a single instance of an ExtrinsicObject is capable of supporting multiple locales, it is always associated with a single repository item. The repository item MAY be in a single locale or MAY be in multiple locales. This specification does not specify any NLS requirements for repository items.

11.4.1 Character Set of Repository Items

When a submitter submits a repository item, they MAY specify the character set used by the repository item using the MIME Content-Type mime header for the mime multipart containing the repository item as shown below:



Content-Type: text/xml; charset="UTF-8"



A server MUST preserve the charset of a repository item as it is originally specified when it is submitted to the server.

11.4.2 Language of Repository Items

This specification currently does not provide for a mechanism to specify the language of a RepositoryItem.

This document currently specifies only the method of sending the information of character set and language, and how it is stored in a server. However, the language information MAY be used as one of the query criteria, such as retrieving only DTD written in French. Furthermore, a language negotiation procedure, like client asking a preferred language for messages from server, could be functionality for a future revision of this document.

12 REST Binding

This chapter specifies a minimal REST binding for the QueryManager interface. This binding will be referred to as Core REST binding. Additional, more detailed REST bindings such as binding for ATOM, ATOM Pub, Open Search etc. will be defined by separate specifications. These additional specification will also provide a RESTFul interface to the LifecycleManager interface.

12.1 Canonical URL

The canonical URL is an HTTP GET URL that MAY be used to reference or access RegistryObjectType instance in a RESTful manner. The canonical URL provides a simple universally supported means to access the object via HTTP GET. A server MUST provide access to its RegistryObjectType instances and repository items via canonical URLs as defined in sections below. Access to such resources MUST be controlled by the applicable access control policies associated with these resources as defined by ebRIM under the chapter titled Access Control Information Model.

12.1.1 Canonical URL for RegistryObjects

The canonical URL for RegistryObjectType has the following pattern:

//The {id} parameter specifies the id of a RegistryObject

GET /rest/registryObjects/{id}



The following are examples of valid canonical URLs for RegistryObjectType instances. Note that for readability we do not encode special characters in the id attribute value.



//Get RegistryObject with id: urn:acme:pictures:danyal.jpg
GET http://acme.com/myregistry/rest/registryObjects/urn:acme:pictures:danyal.jpg

//Get RegistryObject id: http://www.acme.com/pictures/danyal.jpg
GET http://acme.com/myregistry/rest/registryObjects/http://www.acme.com/pictures/danyal.jpg



12.1.2 Canonical URL for Repository Items

The canonical URL for repository items has the following pattern:

//The {id} parameter specifies the id of a RegistryObject for repository item

GET /rest/repositoryItems/{id}



The following are examples of valid canonical URLs for RegistryObjectType instances. Note that for readability we do not encode special characters in the id attribute value.



//Get repository item associated with

//ExtrinsicObject with id: urn:acme:pictures:danyal.jpg
GET http://acme.com/myregistry/rest/repositoryItems/urn:acme:pictures:danyal.jpg

//Get repository item associated with

//ExtrinsicObject with id: http://www.acme.com/pictures/danyal.jpg
GET http://acme.com/myregistry/rest/repositoryItems/http://www.acme.com/pictures/danyal.jpg



12.2 Query Protocol REST Binding

A server MUST implement a REST Binding for the Query Protocol of the Query Manager interface as specified in this section. This binding allows a client to invoke any parameterized query supported by the server in a RESTful manner.

The URL pattern or template for the parameterized query invocation is as follows:



#Template URL for parameterized query invocation

<server base url>/rest/search?queryId={the query id}(&{<param-name>=<param-value>})*




The following example shows the use of the FindObjectsByIdAndType canonical query using the REST binding.

#Get RegistryObject with id: urn:acme:pictures:danyal.jpg
GET http://acme.com/myregistry/rest/search?queryId=urn:oasis:names:tc:ebxml-regrep:query:FindObjectById&id=urn:acme:pictures:danyal.jpg



12.2.1 Parameter queryId

The queryId parameter MUST specify the id of a parameterized stored query while zero or more additional parameters MAY provide parameter name and value pairs for parameters supported by the query. If the queryId is unspecified then it implicitly specifies the value “urn:oasis:names:tc:ebxml-regrep:query:FindObjectById” as the default queryId.

12.2.2 Query Specific Parameters

A parameterized query MAY define any number of query-specific parameters. A client MAY specify values for these parameters MAY as additional options to the URL. For example, the id=urn:acme:pictures:danyal.jpg part in example URL above supplies a value for the id query-specific parameter defined by the FindObjectsByIdAndType query.

In addition to query-specific parameters, every query invocation URL MUST also support one or more canonical query parameters. These are described in subsequent sections.

12.2.3 Canonical Query Parameter: depth

This canonical query parameter represents the same named attribute and associated semantics as defined for Query Request.



#Example: Find objects matching specifies keywords and also return

#related objects reachable by up to 10 levels of references

/rest/search/?queryId=urn:oasis:names:tc:ebxml-regrep:query:FindObjectByKeywords&keywords=automobile;japan&depth=10

12.2.4 Canonical Query Parameter: format

This canonical query parameter represents the same named attribute and associated semantics as defined for Query Request.



#Example: Find 10 resources by keywords using en-us language and ebRS format

/rest/search/?queryId=urn:oasis:names:tc:ebxml-regrep:query:FindObjectByKeywords&keywords=automobile;japan&lang=en-us&format=application/x-ebrs+xml



12.2.5 Canonical Query Parameter: federated

This canonical query parameter represents the same named attribute and associated semantics as defined for Query Request.



#Example: Perform a federated query across members of all configured federations

/rest/search/?queryId=urn:oasis:names:tc:ebxml-regrep:query:FindObjectByKeywords&keywords=automobile;japan&federated=true



12.2.6 Canonical Query Parameter: federation

This canonical query parameter represents the same named attribute and associated semantics as defined for Query Request.



#Example: Perform a federated query across members of specified federation

/rest/search/?queryId=urn:oasis:names:tc:ebxml-regrep:query:FindObjectByKeywords&keywords=automobile;japan&federated=true&federation=urn:acme:federation:acme-partners



12.2.7 Canonical Query Parameter: matchOlderVersions

This canonical query parameter represents the same named attribute and associated semantics as defined for Query Request.



#Example: Find objects matching specified name and include older versions of matched objects if they match

/rest/search/?queryId=urn:oasis:names:tc:ebxml-regrep:query:BasicQuery&name=TestRegister1&matchOlderVersionsOnQuery=true

12.2.8 Canonical Query Parameter: startIndex

This canonical query parameter represents the same named attribute and associated semantics as defined for Query Request.



#Example: Find 10 resources by keywords starting at index 30

/rest/search/?queryId=urn:oasis:names:tc:ebxml-regrep:query:FindObjectByKeywords&keywords=automobile;japan&maxResults=10&startIndex=30



12.2.9 Canonical Query Parameter: lang

This canonical query parameter represents the same named attribute and associated semantics as defined for Query Request.



#Example: Find resources by keywords using en-us language

/rest/search/?queryId=urn:oasis:names:tc:ebxml-regrep:query:FindObjectByKeywords&keywords=automobile;japan&lang=en-us



12.2.10 Canonical Query Parameter: maxResults

This canonical query parameter represents the same named attribute and associated semantics as defined for Query Request.



#Example: Find 10 resources by keywords

/rest/search/?queryId=urn:oasis:names:tc:ebxml-regrep:query:FindObjectByKeywords&keywords=automobile;japan&maxResults=10

12.2.11 Use of Functions in Query Parameters

Query functions may be used in query parameters as defined in Query Function. The only caveat is that the special characters such as the special sequences “#@” and “@#”, special characters “(“, “)” etc. MUST be specified in their URL encoded representation as defined by RFC 3986 and RFC 3629.

For example a query parameter “#@'@#rs:currentTime#@'@#” would evaluate to the current time as a quoted timestamp string in ISO 8601 format such as “#@'@#2010-08-05T17:14:18.866#@'@#”. Such a query parameter in REST interface would have to be URL encoded to be as shown in the following example:

http://localhost:8080/omar-server/rest/search?queryId=urn:ogc:specification:regrep:profile:ISO19139:query:DatasetDiscoveryQuery&title=%23%40%%2740%23ebrs:currentTime%28%29%23%40%%2740%23

12.2.12 Query Response

The response document returned by the Query Protocol REST binding MUST be a QueryResponse document. If the format parameter value is unspecified or if it is specified as “application/x-ebrs+xml” then the response document must have query:QueryResponse element as its root element.



13 SOAP Binding

This chapter specifies the requirements for SOAP Binding that a regrep server or client must adhere to. The normative definition of service endpoint, protocols and their SOAP binding is contained within the WSDL 1.1 definition available at http://www.oasis-open.org/committees/regrep/documents/4.0/ wsdl/1.1. A WSDL 2.0 definition is also available at http://www.oasis-open.org/committees/regrep/documents/4.0/ wsdl/2.0.

The following additional requirements are defined by this specification for the SOAP binding:

13.1 WS-Addressing SOAP Headers

The following rules apply to a server when sending a Notification message to a SOAP endpoint for the NotificationListener.

The following example shows a SOAP message containing a Notification intended for a NotificationListener SOAP endpoint.



<env:Envelope>

<env:Header>

<wsa:MessageID>

urn:uuid:3e79348f-d696-4fac-a015-a4bae0bf83c5

</wsa:MessageID>

<wsa:ReplyTo>

<wsa:Address>http://www.acme.com/regrep</wsa:Address>

</wsa:ReplyTo>

<wsa:To>http://www.client.com/notificationListener</wsa:To>

<wsa:Action>urn:oasis:names:tc:ebxml-regrep:wsdl:NotificationListener:bindings:4.0:NotificationListener:onNotification</wsa:Action>

</env:Header>

<env:Body>

<rim:Notification .../>

</env:Body>

</env:Envelope>



  1. Protocol Exceptions

This appendix defines the standard exception that may be returned by various protocols defined in this specification. These exceptions MUST be returned as SOAP fault messages in the SOAP binding for the protocols. Implementations SHOULD provide relevant details regarding the exception within the Detail element of the fault.

XSD Element Name

Description

AuthenticationException

Generated by server when a client sends a request with authentication credentials and the authentication fails for any reason.

AuthorizationException

Generated by server when a client sends a request to the server for which it is not authorized.

CatalogingException

Generated by server when a problem is encountered during the processing of a CatalogObjectsRequest.

InvalidRequestException

Generated by server when a client sends a request that is syntactically or semantically invalid.

ObjectExistsException

Generated by the server when a SubmitObjectsRequest attempts to create an object with the same id as an existing object and the mode is “CreateOnly”.

ObjectNotFoundException

Generated by the server when a QueryRequest expects an object but it is not found in server.

QueryException

Generated by server when when a problem is encountered during the processing of a QueryRequest.

QuotaExceededException

Generated by server when a a request exceeds a server specific quota for the client.

ReferencesExistException

Generated by server when a RemoveObjectRequest attempts to remove a RegistryObject while references to it still exist.

TimeoutException

Generated by server when a the processing of a request exceeds a server specific timeout period.

UnresolvedReferenceException

Generated by the server when a request references an object that cannot be resolved within the request or to an existing object in the server.

UnsupportedCapabilityException

Generated by server when when a request attempts to use an optional feature or capability that the server does not support.

ValidationException

Generated by server when a problem is encountered during the processing of a ValidateObjectsRequest.



1 Composed object types are identified in class diagrams in [ebRIM] as classes with composition or “solid diamond” relationship with a RegistryObject type.

1At the time of this writing BPMN 2.0 is not final yet. This specification uses the BPMN 2.0 Beta 2 specification as a reference at this time since BPMN 2.0 is not final yet.

1This is also referred to as a “Layer 1”, representation layer or presentation layer

2This is also referred to as a “Layer 2” or analytical layer

3This is also referred to as a “Layer 3” or executable layer

regrep-core-rs-v4.0-csd01 24 March 2011
Copyright © OASIS Open 2010-2011. All Rights Reserved. Standards Track Work Product. Page 96 of 96