Citation format:

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

2.24.2.1 Function Semantics

• The server MUST return a string if the query is processed without any exceptions

• The value of the string MUST be “rs:null” if no current user is associated with the RegistryRequest

2.24.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.24.3.1 Parameter Summary

2.24.3.2 Function Semantics

• The server MUST return a string if the query is processed without any exceptions

• The format of the duration parameter MUST conform to the format as specified by the duration type defined by XML Schema duration type otherwise the server MUST return InvalidRequestException

• The value of the string MUST be a time in ISO 8601 format that is offset by the specified period in the future relative to the current time. An example of value returned is “2010-02-25T15:22:14.534Z”

2.24.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.24.4.1 Parameter Summary

2.24.4.2 Function Semantics

• The server MUST return a string if the query is processed without any exceptions

• The string MUST be “rs:null” if no ClassificationNode is found that matches the function parameters

• The string MUST consist of a set of substrings separated by the appropriate delimiter character when any ClassificationNode's are found that match the function parameters:

  • There MUST be a substring for each ClassificationNode matched by the function

  • Each substring MUST conform to the specified template such that all occurrences of ${id} are replaced by the id of a ClassificationNode matched by the function

• The id of the reference ClassificationNode MUST be included if and only if the includeSelf parameter value is true

• A ancestorLevels value of N where N > 0 matches all ClassificationNodes upto the Nth level ancestors of the reference ClassificationNode. A value of 1 matches the immediate parents of the reference ClassificationNode while a value of 2 matches the parents and grandparents of the reference ClassificationNode. A value of -1 matches all ancestors of the reference ClassificationNode

• A descendantsLevels value of N where N > 0 matches all ClassificationNodes upto the Nth level descendants of the reference ClassificationNode. A value of 1 matches the immediate children of the reference ClassificationNode while a value of 2 matches the children and grandchildren of the reference ClassificationNode. A value of -1 matches all descendants of the reference ClassificationNode

• A template value of “rs:null” is implicitly equivalent to a template value of “${id}”

2.25 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.25.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

• Element RegistryObjectList - Specifies a set of RegistryObject instances that are being submitted to the server. The RegistryObjects in the list may be new objects being submitted to the server or they may be current objects already existing in the server.

• Attribute checkReferences – Specifies the reference checking behavior expected of the server

  • true - Specifies that a server MUST check submitted objects and make sure that all references via reference attributes and slots to other RegistryObjects are resolvable. If a reference does not resolve then the server MUST return UnresolvedReferenceException

  • false (default) – Specifies that a server MUST NOT check submitted objects to make sure that all references via reference attributes and slots to other RegistryObjects are resolvable. If a reference does not resolve then the server MUST NOT return UnresolvedReferenceException

• Attribute mode – Specifies the semantics for how the server should handle RegistryObjects being submitted when they already exist in the server:

  • CreateOrReplace (default) - If an object does not exist, server MUST create it as a new object. If an object already exists, server MUST replace the existing object with the submitted object

  • CreateOrVersion - If an object does not exist, server MUST create it as a new object. If an object already exists, server MUST not alter the existing object and instead it MUST create a new version of the existing object using the state of the submitted object

  • CreateOnly - If an object does not exist, server MUST create it as a new object. If an object already exists, the server MUST return an ObjectExistsException fault message

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.

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

• A server MUST return an UnsupportedCapabilityException fault message if the request contains a type that is an extension of types defined by ebRIM and if the server cannot support such extension.

3.1.2 Audit Trail Requirements

• The server MUST create a single AuditableEvent object as follows:

  • If RegistryObjects were created by the request, it contain a single Action sub-element with eventType Created for all the RegistryObjects created during processing of the request

  • If RegistryObjects were updated by the request, it contain a single Action sub-element with eventType Updated for all the RegistryObjects updated during processing of the request

• The server SHOULD create AuditableEvents after successfully processing the request in a separate transaction from the request

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

• Element Query - Specifies a query to be invoked. A server MUST use all objects that match the specified query in addition to any other objects identified by the ObjectRefList element as targets of the update action.

• Element ObjectRefList - Specifies a collection of references to existing RegistryObject instances in the server. A server MUST use all objects that are referenced by this element in addition to any other objects identified by the Query element as targets of the update action.

• Element UpdateAction – Specifies the details of how to update the target objects

• Attribute checkReferences – Specifies the reference checking behavior expected of the server

  • true - Specifies that a server MUST check updated objects and make sure that all references via reference attributes and slots to other RegistryObjects are resolvable. If a reference does not resolve then the server MUST return UnresolvedReferenceException

  • false (default) – Specifies that a server MUST NOT check updated objects to make sure that all references via reference attributes and slots to other RegistryObjects are resolvable. If a reference does not resolve then the server MUST NOT return UnresolvedReferenceException

• Attribute mode – Specifies the semantics for how the server should handle RegistryObjects being updated in the server:

  • CreateOrReplace (default) - If an object does not exist, server MUST return ObjectNotFoundException. If an object already exists, server MUST update the existing object without creating a new version

  • CreateOrVersion - If an object does not exist, server MUST return ObjectNotFoundException. If an object already exists, server MUST create a new version of the existing object before applying the requested update action

  • CreateOnly – This mode does not apply to UpdateObjectsRequest. If specified, server MUST return an InvalidRequestException

3.2.1.3 Returns

This request returns a RegistryResponse.

3.2.1.4 Exceptions

• A server MUST return an UnsupportedCapabilityException fault message if the request contains a type that is an extension of types defined by ebRIM and if the server cannot support such extension.

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

• Element Selector – Is a QueryExpressionType that contains the expression that identifies a node of the resource representation to be updated.
  
  The value of this element MUST conform to the queryLanguage specified in the queryLanguage attribute of the Selector. A resource MUST generate an QueryException fault if the expression is invalid. If the expression syntax is not valid with respect to the queryLanguage then a resource SHOULD specify a fault detail of "InvalidExpressionSyntaxException". If the expression value is not valid for the resource type then the resource SHOULD specify a fault detail of "InvalidExpressionValueException".
  
  A server MUST minimally support XPATH 1.0 as the queryLanguage for Selector element. The scope of the XML document that is processed by the XPATH expression is the RegistryObjectType instance. A server MUST implicitly support the standard namespace prefixes used by RegRep schemas (rim:, query:, rs:, lcm:, spi:) as a notational convenience. These standard namespace prefixes should map to the latest version of the specification supported by the server.
  
  An XPATH selector expression MUST be specified using the RegistryObject being updated as the context node.
  
  An XPATH selector expression may select an attribute or an element relative to the RegistryObject context node. If it selects an attribute then the ValueHolder element should use a ValueType subtype for a primitive type (instead of AnyValueType) that corresponds to the primitive type for the attribute (e.g. StringValueType). The ValueHolder/Value element's content shall contain the attribute value.

• Element ValueHolder - This element contains the value to be written to the target object. If the mode attribute is "Insert" or "Update" then this element MUST be present. If the mode is "Delete" then this element MUST NOT be present.

• Attribute mode – This attribute specifies the semantics for how the server should update target objects:

  • Insert - Indicates that the value provided by ValueHolder MUST be added to the target object. If the selector targets a repeated element (maxOccurs > 1), the node MUST be added at the end. If the selector targets a non-repeated element (maxOccurrs = 1) that already exists, the resource MUST generate an InvalidRequestException with a fault detail of NodeAlreadyExistsException. If the selector targets an existing item of a repeated element, the value provided by ValueHolder MUST be added before the existing item.

  • Update – Indicates that the node identified by selector MUST be replaced by value by the ValueHolder in its place. If the selector resolves to nothing then there should be no change to the target object.

  • Delete - indicates that the node identified by selector MUST be deleted from the target object if it is present.

3.2.3 Audit Trail Requirements

• The server MUST create a single AuditableEvent object as follows:

  • If RegistryObjects were updated by the request, it contain a single Action sub-element with eventType Updated for all the RegistryObjects updated during processing of the request

• The server SHOULD create AuditableEvents after successfully processing the request in a separate transaction from the request

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

• Attribute checkReferences – Specifies the reference checking behavior expected of the server

  • true - Specifies that a server MUST check objects being removed and make sure that there are no references to them from other objects via reference attributes and slots. If a reference exists then the server MUST return ReferencesExistsException

  • false (default) – Specifies that a server MUST NOT check objects being removed to make sure that there are no references to them from other objects via reference attributes and slots. If a reference exists then the server MUST NOT return ReferencesExistsException

• Attribute deleteChildren – This attribute specifies whether or not to delete children of the objects being deleted according to the following behavior:

  • false – Specifies the server MUST NOT delete the children of objects that are specified to be deleted

  • true – Specifies the server MUST delete children of objects being deleted if and only if those children are not children of any other parent objects

• Attribute deletionScope - This attribute specifies the scope of impact of the RemoveObjectsRequest. The value of the deletionScope attribute MUST be a reference to a ClassificationNode within the canonical DeletionScopeType ClassificationScheme as described in ebRIM. A server MUST support the deletionScope types as defined by the canonical DeletionScopeType ClassificationScheme. The canonical DeletionScopeType ClassificationScheme may be extended by adding additional ClassificationNodes to it.
  
  The following canonical ClassificationNodes are defined for the DeletionScopeType ClassificationScheme:

  • DeleteRepositoryItemOnly - Specifies that the server MUST delete the RepositoryItem for the specified ExtrinsicObjects but MUST NOT delete the specified ExtrinsicObjects

  • DeleteAll (default) - Specifies that the request MUST delete both the RegistryObject and the RepositoryItem (if any) for the specified objects

• Element Query - Specifies a query to be invoked. A server MUST remove all objects that match the specified query in addition to any other objects identified by the ObjectRefList element.

• Element ObjectRefList - Specifies a collection of references to existing RegistryObject instances in the server. A server MUST remove all objects that are referenced by this element in addition to any other objects identified by the Query element.

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:

• UnresolvedReferenceException - Indicates that the requestor referenced an object within the request that was not resolved during the processing of the request.

• ReferencesExistException - Indicates that the requestor attempted to remove a RegistryObject while references to it still exist. Note that it is valid to remove a RegistryObject and all RegistryObjects that refer to it within the same request. In such cases the ReferencesExistException MUST not be thrown.

3.3.2 Audit Trail Requirements

• The server MUST create a single AuditableEvent object as follows:

  • If RegistryObjects were removed by the request, it contain a single Action sub-element with eventType Deleted for all the RegistryObjects removed during processing of the request

• The server SHOULD create AuditableEvents after successfully processing the request in a separate transaction from the request

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:

• There is a single root node for the tree

• The root is the original version

• Each non-root node in the tree is a version of the object

• Each version is created from a parent version and is represented in the version tree as a child node of the node representing the parent version node for that version

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 composed¹ 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:

• ClassificationType

• ExternalIdentifierType

• ExternalLinkType

• ServiceEndpointType

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 [regrep-rim-v4.0].

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:

• A server MUST create a new version of a version-controlled, non-composed RegistryObjectType instance in the following cases:

  • An existing object is replaced using the submitObjects protocol with mode of CreateOrVersion

  • An existing object is updated using the updateObjects protocol with mode of CreateOrVersion

• A server MUST NOT create a new version of a composed RegistryObjectType instance when it is updated.

• When creating a new version for a non-composed RegistryObjectType instance, a server MUST create new logical objects for any composed logical objects within the new version of the composed object. Any such new logical object for composed objects MUST have a new server generated universally unique id and lid attribute.

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:

• A server MUST create a new version of an existing ExtrinsicObjectType instance and assign it a new unique versionName within its VersionInfo element when either the ExtrinsicObjectType instance or its RepositoryItem are updated using the submitObjects or updateObjects protocol and the mode is CreateOrVersion

  • A server MUST create a new version of an ExtrinsicObjectType instance and assign it a new unique versionName within its VersionInfo element when the previous version had a RepositoryItem and the new version does not have one (RepositoryItem was deleted).

  • A server MUST create a new version of an ExtrinsicObjectType instance and assign it a new unique versionName within its VersionInfo element when the previous version did not have RepositoryItem and the new version has one (RepositoryItem was added). In such cases the server MUST also create a new version of the RepositoryItem and assign it a new unique versionName within the ContentVersionInfo element.

  • A server MUST create a new version of the RepositoryItem for an existing ExtrinsicObjectType instance and assign it a new unique versionName within the ContentVersionInfo element when the RepositoryItem is updated using the submitObjects or updateObjects protocol and the mode is CreateOrVersion

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:

• The copied Associations MUST be new versions of their original Association (MUST have the same lid)

• The sourceObject of the copied Associations MUST reference the new version of the RegistryPackage rather than the older version

4.8 Versioning and RegistryPackage Membership

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

• A server MUST return an InvalidRequestException fault message if a client attempts to publish more than one version of the same logical object as member of the same RegistryPackage instance

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).

• A server MUST automatically link each new version in the version tree for a RegistryObject to its predecessor using an Association between the two versions

• The type attribute value of the Association MUST reference the canonical AssociationType “Supersedes”

• The sourceObject attribute value of the Association MUST reference the new version

• The targetObject attribute value of the Association MUST reference the old 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.

• A server MAY allow authorized clients to remove specified versions of a RegistryObject

• A server MAY prune older versions of RegistryObjects based upon server specific administrative policies in order to manage storage resources

• When a non-leaf version within a version tree is deleted, a server MUST implicitly delete the entire version sub-tree under that non-leaf version such that no versions created directly or indirectly from the specified remain in the registry

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

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

• Element InvocationControlFile – Specifies an ExtrinsicObject that is used to control the validation process in a type specific manner. See Canonical XML Validator plugin for an example. This element MAY be specified by server when sending the request to the Validator plugin if the Validator plugin requires an invocation control file. It SHOULD NOT be specified by the client.

• Element ObjectRefList - Specifies a collection of references to existing RegistryObject instances in the server. A server MUST validate all objects that are referenced by this element. This element is typically used when a client initiates the validateObjects protocol.

• Element OriginalObjects - Specifies a collection of RegistryObject instances. A server MUST validate all objects that are contained in this element. This element is typically used when a server initiates the validateObjects protocol during the processing of a submitObjects or updateObjects protocol request or when it is delegating a client initiated validateObjects protocol request to a Validator plugin.

• Element Query - Specifies a query to be invoked. A server MUST validate all objects that match the specified query. This element is typically used when a client initiates the validateObjects protocol.

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:

• ValidationException: signifies that an exception was encountered during the validateObjects operation

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:

• The server selects the RegistryObjects that are the target of the validateObjects operations using the <spi:Query> and <rim:ObjectRefList> elements. Any objects specified by the OriginalObjects element MUST be ignored by the server.

• The server partitions the set of target objects into multiple sets based upon the objectType attribute value for the target objects

• The server determines whether there is a Validator plugin configured for each objectType for which there is a set of target objects

• For each set of target objects that share a common objectType and for which there is a configured Validator plugin, the server MUST invoke the Validator plugin. The Validator plugin invocation MUST specify the target objects for that set using the OriginalObjects element. The server MUST NOT specify <spi:Query> and <rim:ObjectRefList> elements when invoking validateObjects operation on a Validator plugin

• Each Validator plugin MUST process the ValidateObjectsRquest and return a ValidateObjectsResponse or fault message to the server's Validator endpoint.

• The server's Validator endpoint MUST then combine the results of the individual ValidateObjectsRequest to Validator plugins into a single unified ValidateObjectsResponse and return it to the client.

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

• Element InvocationControlFile – Specifies an ExtrinsicObject that is used to control the cataloging process in a type specific manner. See Canonical XML Catalogor plugin for an example. This element MAY be specified by server when sending the request to the Cataloger plugin if the Cataloger plugin requires an an invocation control file. It SHOULD NOT be specified by the client.

• Element ObjectRefList - Specifies a collection of references to existing RegistryObject instances in the server. A server MUST catalog all objects that are referenced by this element. This element is typically used when a client initiates the catalogObjects protocol.

• Element OriginalObjects - Specifies a collection of RegistryObject instances. A server MUST catalog all objects that are contained in this element. This element is typically used when a server initiates the catalogObjects protocol during the processing of a submitObjects or updateObjects protocol request or when it is delegating a client initiated catalogObjects protocol request to a Cataloger plugin.

• Element Query - Specifies a query to be invoked. A server MUST catalog all objects that match the specified query. This element is typically used when a client initiates the catalogObjects protocol.

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:

• CatalogingException: signifies that an exception was encountered during the catalogObjects operation

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:

• Element RegistryObjectList (Inherited) – Contains the RegistryObjects that are produced as output of the catalogObjects operation. Typically this list contains the objects that were input to the catalogObjects operation, as well as new objects that were the output of the catalogObjects operation. The input objects MAY be modified by the cataloger as a result of the catalogObjects operation.

  • A cataloger MUST create AssociationType instance between the source object for the catalogObjects operation (specified by OriginalObjects element in CatalogRequest) and each of the cataloged RegistryObjectType instances generated by the cataloger. Each such AssociationType instance

    • MUST have its type attribute reference the canonical AssociationType “urn:oasis:names:tc:ebxml-regrep:AssociationType:HasCatalogedMetadata”

    • MUST have its sourceObject attribute reference the source object for the catalogObjects operation

    • MUST have its targetObject attribute reference a cataloged RegistryObjectType instance generated by the cataloger

  • A cataloger SHOULD assign the same accessControlPolicy to cataloged objects as their source object. A cataloger MAY use a different strategy for assigning access control policy to cataloged objects.

  • A server MUST delete all cataloged metadata generated by a cataloger when the source object is deleted.

  • A server MUST update all cataloged metadata generated by a cataloger when the source object is updated without creating a new version.

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:

• The server selects the RegistryObjects that are the target of the catalogObjects operations using the <spi:Query> and <rim:ObjectRefList> elements. Any objects specified by the OriginalObjects element MUST be ignored by the server.

• The server partitions the set of target objects into multiple sets based upon the objectType attribute value for the target objects

• The server determines whether there is a Cataloger plugin configured for each objectType for which there is a set of target objects

• For each set of target objects that share a common objectType and for which there is a configured Cataloger plugin, the server MUST invoke the Cataloger plugin. The Cataloger plugin invocation MUST specify the target objects for that set using the OriginalObjects element. The server MUST NOT specify <spi:Query> and <rim:ObjectRefList> elements when invoking catalogObjects operation on a Cataloger plugin

• Each Cataloger plugin MUST process the CatalogObjectsRquest and return a CatalogObjectsResponse or fault message to the server's Cataloger endpoint.

• The server's Cataloger endpoint MUST then combine the results of the individual CatalogObjectsRequest to Cataloger plugins and commit these objects as part of the transaction associated with the request. It MUST then combine the individual CatalogObjectsResponse messages into a single unified CatalogObjectsResponse and return it to the client.

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:

• Support an ExtrinsicObject as primary input

• Support an XML RepositoryItem for the ExtrinsicObject object as a secondary input

• The secondary input is specified using an <xsl:param> with name “repositoryItem” and with value that is the id of the ExtrinsicObject for which it is a RepositoryItem

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

• Uses an XSLT processor with the XSLT file specified as InvocationControlFile

• Specifies the ExtrinsicObject being cataloged as the primary input to the XSLT processor

• Specifies the RepositoryItem for the ExtrinsicObject object being cataloged by setting the parameter named “repositoryItem” with a value that is the id of the ExtrinsicObject for which it is a RepositoryItem

• Resolves references to the RepositoryItem via the $repositoryItem parameter value within the XSLT file specified as InvocationControlFile

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. [regrep-rim-v4.0] 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 [regrep-rim-v4.0].

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 [regrep-rim-v4.0].

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);
  }
}

• Objects of interest MUST be those objects that match the selector query for the subscription

• Events of interest MUST have affected at least one object of interest

• Events of interest MUST contain all objects of interest (or references to them) that were affected by the event

• Events of interest MUST NOT contain an object or reference to an object that is not an object of interest

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 [regrep-rim-v4.0].

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

7.6.1 Notification

The Notification message is sent by the server to a NotificationListener interface implemented by the client and delivers 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:

• Remote Object Reference – Allows references between objects residing in different servers

• Object Replication – Allows replication of objects residing in a remote server to a local server

• Federated Queries – Allows queries that execute against, and return results from multiple servers

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 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 [regrep-rim-v4.0].

Illustration 9: Remote Object Reference

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.

Illustration 10: Local Replication of Remote Objects

The following rules govern replication of remote objects:

• A server MUST match local replicas of remote objects in the same manner as local objects within the Query protocol.

• A client MUST NOT perform update operations via SubmitObjects and UpdateObjects operations on a local replica of a remote object.

• A server MUST return an InvalidRequestException fault message if a client attempts to update a replica via SubmitObjects and UpdateObjects operations.

• A server MUST delete a replica if a client uses RemoveObjects operation to remove the replica.

• Objects MAY be replicated from any server to any other server without any requirement that the registries belong to the same federation.

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 client submits a Subscription to the remote server on behalf of the local server.

  • The subscription is published like any other RegistryObjectType instance using the Submit Objects protocol with the LifecycleManager endpoint of the remote server.

  • This typically requires that the client is registered with the remote server and can authenticate with it.

• The Subscription defines a Selector query that matches one or more objects that need to be replicated from remote server to local server.

  • Selector query may match any number of objects using any selection criteria supported by the query.

• The Subscription specifies the address of a NotificationListener endpoint implemented by the local server where the remote server may send Notifications regarding the objects that need to be replicated.

• The local server uses the selector query for the subscription to PULL the initial copy of the remote object(s)

  • A server MUST NOT create a local replica for an object if a local object exists with the same id. In such case the server MUST return an ObjectExistsException fault message.

• Whenever the remote server send Notifications to the local server for the same Subscription, the local server synchronizes the local replica with the remote object.

  • A server MUST delete a local replica when its source object is deleted at the remote server.

  • A server MUST NOT delete a local object that is not a replica of a remote object if a notification arrives regarding the deletion of a remote object with the same id as the local object. In such case the server MUST return an InvalidRequestException fault message.

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.

Illustration 11: Registry Federations

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 [regrep-rim-v4.0]. Instances of these classes and the associations between these instances describe a federation and its members.

The Federation information model is described in [regrep-rim-v4.0].

8.3.1.1 Creating a Federation

The following rules govern how a federation is created:

• A Federation is created by submitting a Federation instance to a server using the SubmitObjects protocol

• The server where the Federation is created is referred to as the federation home

• A federation home MAY contain multiple Federation instances

8.3.1.2 Joining a Federation

The following rules govern how a server joins a federation:

• Each server SHOULD have exactly one local RegistryType instance. Each server MAY have multiple remote RegistryType instances

• A server MAY join an existing federation by submitting an instance of an Association that associates the Federation instance as sourceObject, to the Registry instance representing the server as targetObject, using a type of HasFederationMember. The home server for the Association and the Federation objects MUST be the same

• A Federation (child federation) MAY join an existing federation (parent federation) by submitting an instance of an Association that associates the Federation instance representing the parent federation as sourceObject, to the Federation instance representing the child federation as targetObject, using a type of HasFederationMember. The home server for the Association and the parent Federation objects MUST be the same

8.3.1.3 Leaving a Federation

The following rules govern how a server leaves a federation:

• A server or a federation MAY leave a federation at any time by removing the HasFederationMember Association instance for its RegistryType or FederationType instance that links it with the parent FederationType instance. This is done using the standard RemoveObjects protocol.

8.3.1.4 Dissolving a Federation

The following rules govern how a federation is dissolved:

• A federation is dissolved using the standard RemoveObjects protocol against the Federation's home server and removing its FederationType instance

• The removal of a FederationType instance is governed by Access Control Policies like any other RegistryObject

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:

• The status of the QueryResponse MUST reference the canonical “PartialSuccess” ClassificationNode within the canonical ResponseStatusType ClassificationScheme

• The QueryResponse MUST have a set of Exception sub-elements of type rs:RegistryExceptionType, one for each exception encountered while dispatching a query to a remote server

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:

• 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 within the scope of servers in the federation, starting at startIndex.

• A server MUST return the same result in a deterministic manner for the same federated QueryRequest if no changes have been made in between the request to the federation member servers and their collective state.

• A server MAY choose any implementation specific algorithm to select results from its federation members for each iteration of an iterative query as long as the algorithm is deterministic and repeatably produces the same results for the same set of federation members and their collective state. For example a server MAY use a sequential algorithm that gets as many results from each of its server sequentially until it satisfies the maxResults parameter or until there are no more results. Alternatively, a server MAY use a parallel algorithm that balances the amount of data retrieved from each of its federation members.

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:

• Scope of governance collaborations

• How governance collaborations are represented,

• How representations of governance collaborations are assigned to RegistryObjects, and

• How a server uses the representation of governance collaborations assigned to a RegistryObjects to govern them

9.1 Representing a Governance Collaboration

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

• Uses BPMN 2.0 diagram notation to pictorially represent business collaborations

• Uses BPMN 2.0 XML format to declaratively represent business collaborations in a machine processable syntax

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

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:

• There MUST be exactly one collaboration element

• The collaboration element MUST have at least one participant element

• At least once participant element MUST have id value of “registryPartcipant” and represents the RegRep server as a participant within the governance collaboration

• There MUST be a processRef element for the “registryPartcipant”

• There MUST be a process element for each processRef attribute in each participant element

• The process element for other participants than the “registryPartcipant” participant MAY conform to “Descriptive Conformance Sub-Class ”³ or “Analytic Conformance Sub-Class ”⁴ in [BPMN2] and need not be executed within a BPMN process engine

• The process element for the “registryPartcipant” participant's process MUST conform to “Common Executable Conformance Sub-Class”⁵ in [BPMN2] and MUST be executed by the server in a BPMN process engine

• The process elements SHOULD use tasks that conform to canonical task patterns defined later in this specification whenever possible

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:

• The objects MUST be immediate members of the same RegistryPackage

• The RegistryPackage MUST have a canonical slot with name “urn:oasis:names:tc:ebxml-regrep:rim:RegistryPackage:packageType”

• The value of the packageType slot MUST be a unique identifier for the type of package of which the group of related objects are an instance

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:

• The type attribute value of Association MUST reference the canonical “GovernedBy” ClassificationNode within the canonical AssociationType ClassificationScheme whose id is “urn:oasis:names:tc:ebxml-regrep:AssociationType:GovernedBy”

• The targetObject attribute value of Association MUST reference an ExtrinsicObject with objectType “urn:oasis:names:tc:ebxml-regrep:ObjectType:RegistryObject:ExtrinsicObject:XML:BPMN2”

• The repository item for the ExtrinsicObject MUST be an XML document conforming to the BPMN2 model XML Schema. If the modular approach to BPMN description is used then this file MUST be the collaboration BPMN file. The file MUST import or contain the BPMN process for the “Registry” participant

• The sourceObject attribute value of Association MUST reference the RegistryPackage instance to which the governance collaboration is being assigned

• The RegistryPackage MUST NOT have a canonical slot with name “urn:oasis:names:tc:ebxml-regrep:rim:RegistryPackage:packageType”

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:

• The sourceRef attribute of the messageFlow references a task that conforms to the SendWorkflowAction task template described later in this chapter

• The targetRef attribute of the messageFlow references a task that conforms to the ReceiveWorkflowAction task template described later in this chapter

• The messageRef attribute of the messageFlow is defined and references a message whose itemDefinition has attribute structureRef="rim:WorkflowActionType"

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.

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:

• A dataInput that has an itemSubjectRef attribute that references an itemDefinition element whose structureRef attribute value is “rim:WorkflowActionType”

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:

• An action attribute identifying the action performed

• A targetObject attribute identifying the object that is the target of the action. Typically, this is the governed object

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:

• A dataInput that has an itemSubjectRef attribute that references an itemDefinition element whose structureRef attribute value is “rim:WorkflowActionType”

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:

• A dataInput that has an itemSubjectRef attribute that references an itemDefinition element whose structureRef attribute value is “rim:NotificationType”

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.

• The namespace URI for these functions MUST be "urn:oasis:names:tc:ebxml-regrep:xsd:rs:4.0"

• The namespace prefix SHOULD be “rs”

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:

• The submitter requests review and approval of the governed object using SendWorkflowAction canonical task pattern with action “RequestForReview”

• The server receives the “RequestForReview” WorkflowAction and notifies the reviewer roles of the request for review using Notify canonical task pattern

• A reviewer accepts the request for review using SendWorkflowAction canonical task with WorkflowAction “Accept”

• The server notifies submitter roles that the governed object is under review using the using Notify canonical task

• The reviewer approves or rejects the governed objects using SendWorkflowAction canonical task and actions “Approve” or “Reject”

• The server notifies the submitter of the outcome of the review using the using Notify canonical task

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:

• [WSS-CORE] WS-Security Core Specification 1.1, February 2006.
  http://www.oasis-open.org/committees/download.php/16790/wss-v1.1-spec-os-SOAPMessageSecurity.pdf

• [WSS-UNT] WS-Security Username Token Profile 1.1, February 2006.
  http://www.oasis-open.org/committees/download.php/16782/wss-v1.1-spec-os-UsernameTokenProfile.pdf

• [WSS-X509] WS-Security X.509 Token Profile 1.1, February 2006.
  http://www.oasis-open.org/committees/download.php/16785/wss-v1.1-spec-os-x509TokenProfile.pdf

• [WSS-SAML] WS-Security SAML Token profile 1.1, February 2006.
  http://www.oasis-open.org/committees/download.php/16768/wss-v1.1-spec-os-SAMLTokenProfile.pdf

• [WSS-KRB] WS-Security Kerberos Token Profile 1.1, February 2006.
  http://www.oasis-open.org/committees/download.php/16788/wss-v1.1-spec-os-KerberosTokenProfile.pdf

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:

• Username tokens as specified by [WSS-UNT]

• X509 Certificate tokens as specified by [WSS-X509T]

• SAML tokens as defined by [WSS-SAMLT]

• Kerberos tokens as specified by [WSS-KRBT]

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:

• The access control policy associated with each resource.

• The action the client is performing

• The identity associated with the client as well as any roles assigned to that identity

A server MUST provide an access control and authorization mechanism based upon chapter titled “Access Control Information Model” in [regrep-rim-v4.0]. 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 [regrep-rim-v4.0].

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

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.

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 [regrep-xsd-v4.0] 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 [regrep-rim-v4.0].

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 definitions defined by [regrep-wsdl-v4.0]. A WSDL 2.0 definition is also available in [regrep-wsdl-v4.0].

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

• A server MUST use WS-Addressing SOAP Headers when sending a Notification message to a SOAP endpoint as defined here.

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.

• Use of WS-Addressing SOAP headers MUST conform to [WSA-SOAP].

• A server MUST set the content of the wsa:MessageID element to a unique id. A server SHOULD generate a universally unique id value that conform to the format of a URN that specifies a DCE 128 bit UUID as specified in [UUID] (e.g. urn:uuid:a2345678-1234-1234-123456789012).

• A server MUST set the wsa:ReplyTo SOAP header element

  • The wsa:Address elements content MUST be set to the base URL for the server.

• A server MUST set the content of the wsa:To element to the SOAP endpoint URL where the message is being sent to.

• A server MUST set the content of the wsa:Action element to the value of the soapAction attribute of the soap:operation element for the operation defined for the SOAP binding for the interface's WSDL.

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>

Appens 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.