OMAR Features

The OMAR project implements nearly(*) all the required and optional features defined in the OASIS ebXML Registry 3.0 specifications as defined by the OASIS ebXML Registry Technical Committee .

In addition, the server implementation has several features that are not specified by the specification. Before going through the features, you are recommended to install the OMAR server first.

* The SAML 2 based Single Sign On (SSO) feature of ebXML Registry 3.0 Registry Full Profile is still under development.

Features from Latest ebXML Registry Specifications

The following features have been implemented in the OMAR server from the latest ebXML Registry version specifications.

Role Based Access Control

The OMAR server supports fine-grained or custom Access Control Policies (ACP) including Role Based Access Control (RBAC) as specified in the chapter 9 "Access Control Information Model" of the latest ebXML Registry Information Model Specification.

This features allows clients to specify custom policies (rules) for protecting access to RegistryObjects and repository items submitted by them. For example, it enables a submitter to define a custom access control policy to restrict read access to a resource (RegistryObject or RepositoryItem) to specified user(s), user group(s) and/or user role(s). It also enables a a submitter to grant Update and/or Delete access to specified user(s), user group(s) and/or user role(s).

A RegistryObject may be associated with an Access Control Policy by a special Association with the canonical associationType of "AccessControlPolicyFor". This association has the reference to the ExtrinsicObject representing the Access Control Policy as the value of its sourceObject and has the reference to the RegistryObject as the value of its targetObject attribute. If a RegistryObject does not have an Access Control Policy explicitly associated with it, then it is implicitly associated with the default Access Control Policy defined for the registry.

The OMAR project does not provide a GUI tool for authoring XACML access control policies yet. It also does not provide any special support for associating XACML access control policies to a RegistryObject. However a user may use the Registry Browser Java UI Java UI tool to define a custom ACP as follows:

  1. Create a custom XACML ACP using a text editor, XML Authoring tool or an XACML authoring tool. See files in the misc/samples/acp directory for examples.
  2. Validate the custom ACP using an XML Schema validation tool to avoid obscure problems.
  3. Submit the custom ACP like any other RepositoryItem using Registry Browser. Make sure that its objectType is specified as an XACML Policy or PolicySet.
  4. Perform ad hoc query "Find All My Objects" to find the custom ACP and also the object you wish to assign the ACP to.
  5. Multiple select both objects (resource and policy), using <control><left mouse button>.
  6. Browse both selected objects using <right mouse button>Browse.
  7. Create an Association of caninical associationType AccessControlPolicyFor with ACP as source and resource as target.
  8. Save both selected objects using <right mouse button>Save.

Cataloging of XML Content

The Content Cataloging feature provides the ability to selectively convert submitted RegistryObject and repository items into RegistryObject metadata, in a content specific manner.

Cataloging creates and/or updates RegistryObject metadata such as ExtrinsicObject or Classification instances. The cataloged metadata enables clients to discover the repository item based upon content from the repository item, using standard query capabilities of the registry. This is referred to as Content-based Discovery. The main benefit of the Content Cataloging feature is to enable Content-based Discovery.

The OMAR server supports Canonical XML Content Cataloging Service as defined by section 8.10 of the latest ebXML Registry Services Specification. This service allows an XSLT style to be associated with an ObjectType. Whenever a user submits an ExtrinsicObject matching that ObjectType, the registry automatically applies the style sheet to the repository item associated with the ExtrinsicObject. The output of the style sheet must be RegistryObject instances. These registry stores these objects along with the submitted ExtrinsicObject and repository item.

There are three separate roles of users involved with this feature. Note that these the same users may play multiple roles within a use case scenario.

  • The Catalog Publisher: Defines how content of this type gets cataloged.
  • The Content Publisher: Submits content of this type to registry.
  • The Content Consumer: Discovers and uses content of this type within the registry

Catalog Publisher's Actions

The following steps describe how the Catalog publisher publishes an XSLT style sheet (referred to in abstract as the Catalog Definition File ) that defines how the cataloging for a specific type of content should occur:

  • If needed, create an ObjectType Concept for the type of contentif needed as a descendant of the ExtrinsicObject Concept. This is done using the ClassificationScheme Dialog in the Registry Browser Java UI Java UI (or, using RS, like in the classification nodes request) for the CPPA example
  • Create an XSLT Style Sheet to catalog XML documents that are instance documents for the ObjectType. This is done using any XSLT or XML Authoring tool or text editor. Make sure the XSLT style sheet is valid. Make sure to test it stand alone using a stylesheet aware Web Browser or an XSLT transformer engine such as xalan (shipped with OMAR). For an example of what a "Catalog Definition" XSLT Style sheet looks like you may see:

    Example from HL7 Standard.

    Example from ebXML CPP/A Standard.

  • Submit a sample Registry Browser Java UI UI's configuration file with one or more custom ad hoc parameterized query within the Registry Browser Java UI Java UI. The parameterized query is designed with knowledge of the catalog metadata generated by the XSLT style sheet.
  • Submit the XSLT style sheet like any other RepositoryItem using Registry Browser Java UI Java UI. Make sure that its objectType is specified as XSLT.

    The ExtrinsicObject for the XSLT style sheet must have a required Association with associationType of ?InvocationControlFileFor?. The XSLT style sheet must be the sourceObject while the ClassificationNode in the canonical ObjectType ClassificationScheme representing the ObjectType must be the targetObject.

Content Publisher's Actions

The following steps describe how the Content publisher publishes content (referred to in abstract as the Original Content ) to the registry. Note that the Content Publisher is not aware that the registry automatically catalogs the published content.

  • Create an ExtrinsicObject and assign the content to it using the Registry Browser Java UI Java UI as is normal when submitting content to registry.
  • Assign an ObjectType to the ExtrinsicObject using the Concept defined by the Content Publisher for that type of content within the canonical ObjectType scheme.
  • Save the ExtrinsicObject using <right mouse button>Save in Registry Browser Java UI Java UI. The registry automatically catalogs the content and saves the catalog metadata while saving the content.

Content Consumer's Actions

The following steps describe how the Content Consumer discovers the content using content-based ad hoc queries.

  • Edit their personal Registry Browser Java UI UI configuration file:

    <jaxr>/src/com/sun/xml/registry/client/browser/conf/config.xml and add one or more custom ad hoc parameterized queries using the samples provided by the Catalog Publisher.
  • Restart the Registry Browser Java UI Java UI, select Ad hoc Query panel, choose the newly added content specific ad hoc query. Enter parameter values and select the Find toolbar button. They have now discovered the content published by Content Publisher using the ad hoc query published by the Catalog Publisher and performed a potentially complex ad hoc content-based query without being exposed to all the gory details.

HTTP Interface to Registry

The OMAR server supports the required parts of the HTTP interface specified in section 4 "HTTP Binding" in the latest ebXML Registry Services Specification .

The registry offers the following different ways to access RegistryObjects and RepositoryItems via the HTTP interface:

  • RPC Encoding URL: Allows client access to objects via a URL that is based on encoding a Remote Procedure Call to a registry interface as an HTTP protocol request.
  • Submitter defined URL: Allows clients to access objects via submitter defined URLs.
  • File Path Based URL: Allows clients to access objects via a default URL based upon a file path derived from membership of object in a RegistryPackage membership hierarchy.

Each of the above methods has its advantages and disadvantages and different methods may be better suited for different use cases as described in the latest ebXML Registry Services Specification .

RPC Encoding URL:

To access a RegistryObject with id urn:uuid:e3373a7b-4958-4e55-8820-d03a191fb76a use the following URL in a web browser (replace localhost as needed):

http://localhost:8080/omar/registry/http/?interface=QueryManager&method=getRegistryObject&param-id=urn:uuid:e3373a7b-4958-4e55-8820-d03a191fb76a

To access a RepositoryItem with id urn:uuid:e3373a7b-4958-4e55-8820-d03a191fb76a use the following URL in a web browser (replace localhost as needed):

http://localhost:8080/omar/registry/http/?interface=QueryManager&method=getRepositoryItem&param-id=urn:uuid:e3373a7b-4958-4e55-8820-d03a191fb76a

Submitter Defined URL

The OMAR server supports the ability for a user to specify a URL for any RegistryObject or RepositoryItem that they submit. This URL could then be used to access the object over HTTP interface as an alternative to the QueryManager parameterized URL. The benefit would be that objects could be accessible at a URL that is meaningful and memorable to the user.

Lets see how the HTTP access to the QueryManager interface and the new feature compare. The example below uses the Demo DB database created by the createDemoDB build target of 'omar' module.

For RegistryObjects the new feature enables us to the following URL (replace localhost with a different host if you need):

http://localhost:8080/omar/registry/http/pictures/nikola/zeusDescription

Compare that with pre-existing HTTP interface enabled URL:

http://localhost:8080/omar/registry/http/?interface=QueryManager&method=getRegistryObject&param-id=urn:uuid:e3373a7b-4958-4e55-8820-d03a191fb76a

For RepositoryItem the new feature enables the following URL:

http://localhost:8080/omar/registry/http/pictures/nikola/zeus

Compare that with pre-existing HTTP interface enabled URL:

http://localhost:8080/omar/registry/http/?interface=QueryManager&method=getRepositoryItem&param-id=urn:uuid:e3373a7b-4958-4e55-8820-d03a191fb76a

Here is how to use this new feature.

  • To assign a URL to an RegistryObject a client must add a slot with name:

    urn:oasis:names:tc:ebxml-regrep:rim:RegistryObject:locator

  • To assign a URL to an RepositoryItem a client must add a slot with name:

    urn:oasis:names:tc:ebxml-regrep:rim:RegistryObject:RegistryEntry:ExtrinsicObject:contentLocator

  • The value of the specified Slot specified the URL. This URL suffix must be a relative URL that is relative from the base URL of the registry. For example:

    Base URL for Registry: http://localhost:8080/omar/registry

    Implied Prefix URL for HTTP interface: http://localhost:8080/omar/registry/http

    Relative URL suffix: /pictures/nikola/zeus

    Resource access URL: http://localhost:8080/omar/registry/http/pictures/nikola/zeus
  • An objects may have multiple URLs assigned to it. If so it is accessible from each URL assigned to it.
  • A URL suffix must be unique across all objects within a registry.

File Path Based URL

See the latest ebXML Registry Services Specification for details.

Content-based Event Notification

The OMAR server supports the Content-based Event Notification feature as specified in chapter 7 "Event Notification Protocol" in the latest ebXML Registry Services Specification .

This feature allows clients to be notified automatically when events of interest occur in the registry. This is specially useful when a client wishes to be notified when something changes in the registry.

//TODO: Provide details on configuring notification delivery via email

Cooperating Registries

The OMAR server supports a subset of features from the Cooperating Registries feature set as specified in chapter 9 "Cooperating Registries Support" in the latest ebXML Registry Services Specification. Current features include:

  • Ability to reference an object in one registry from a RegistryObject in another registry (Inter-registry object references)

  • Auto-creating local replicas of remote objects when they are referenced

Registry Managed Version Control

The OMAR server and client support the Registry Managed Version Control feature specified in the latest ebXML Registry Services Specification . Under this feature the registry automatically versions RegistryObjects and RepositoryItems whenever they are updated.

Parameterized Stored Queries

The OMAR server and client support the Stored Query features specified in the latest ebXML Registry Services Specification . This feature allows a capability similar to database stored procedures. Clients may submit a parameterized stored query to the registry and later invoke them by specifying the id of the query and parameter values. See the latest ebXML Registry Services Specification for details.

Value-added Features Not Defined By ebXML Registry Specifications

The following features have been implemented in the OMAR server as above and beyond the features described by the ebXML Registry 3.0 specification.

Automatic user registration

The specifications do not specify how the users register their identities with the registry/repository. The Registry Browser Java UI provided by the OMAR project provides a simple to use User Registration Wizard that can automate the process of user registration.

Although a typical user does not need to know the following gory details, Our implementation uses the following mechanism to register a new user:

1. Check whether the certificate contained in the element of path /Envelope/Header/Signature/KeyInfo/X509Data[0]/X509Certificate in the SubmitObjectsRequest message is already in the server keystore (the path is specified by omar.security.keystoreFile property in omar.properties).

2. If the certificate is already in the server keystore, the user has already registered with registry.

3. If the certificate is not in the keystore, the certificate is verified that it is issued by the most trusted certificate authority. Actually, when calling the SOAPSender class to make a signed request, the whole certificate chain will be attached in the signed request. Each certificate in the chain is attached as a element of path /Envelope/Header/Signature/KeyInfo/X509Data. When verifying the target certificate, a certificate chain path is tried to be built. See the section Configuring OMAR in setup guide to see the configuration related to trust anchors.

4. If the verification fails, user registration fails. If the verification is successful, the server will check whether the SubmitObjectsRequest only has one user object:

When registering a new user, the id of the user object must be real UUID. Temporary id will not be accepted. In the above example SubmitObjectsRequest trying to register a new user, the organization is already existing in the registry. Like other SubmitObjectsRequest, the request can contain other objects. But it must have exactly one user object that represents the information of the newly registered user.

5. If the conditions in 4 are satisfied, the target certificate will be installed in the server keystore. Then, when next time the client submits a request to the server, the server will not start user registration process. In addition, the user object will be also inserted into registry.

JAXR API Support

The freebXML Registry project provides a Java API for XML Registries (JAXR) level 1 provider. This provides a powerful, standards based Java API for ebXML Registry. It is encouraged that you write your custom ebXML Registry client applications using the JAXR API.

Registry Browser - Web UI

The OMAR client includes a thin client UI for the registry that is a JAXR API client to the server.

Registry Browser - Java UI

The OMAR client includes a swing/Java based fat client UI (aka RegistryBrowser) for the registry that is a JAXR API client to the server.

Client-Server Embedded Mode Execution

The JAXR Provider supports the ability to run the server (registry) embedded within the JAXR provider JVM process. This is useful when the client needs to meet a high performance requirements. To run the client with embedded server set the following property to true in conf/jaxr-ebxml.properties:

#

# Determine whether the JAXR provider should use localCall

# or use SOAP to talk to ebXML Registry server.

#

org.freebxml.omar.client.xml.registry.localCall=false

Unsigned registry response

The registry services specification specifies that all responses must be signed. However, OMAR has a option to not sign the request. It is because signing a XML document, particularly if the document is big, too much memory is consumed and it takes a long time. The property omar.interfaces.soap.signedResponse in <your_home_dir>/omar.properties is to control this.

RegistryAdmin Tool

A Registry Administration tool is provided that provides many useful administration and utility capabilities via a command line invocation.

The Administration tool also allows to load multiple files and even entire directories into the ebXML Registry via a single command line invocation.

UUID Generator Service

The OMAR server supports a UUID generator service that is exposed via the HTTP interface.

A request for this service would be made through a URL like:

  • http://localhost:8080/omar/registry/http?interface=QueryManager&method=newUUID
API support for UUID generation is provided by the following call:

  • org.freebxml.omar.common.Utility.getInstance().createId();

Do Not Commit Mode

The OMAR server supports a request mode that allows the server to process the request but not actually commit changes at the last stage. This is good for testing purposes in a safe manner.

The "Do Not Commit" (Bachelor Mode) is specified as a special canonical slot on the request as follows:

<SubmitObjectsRequest ...>

<rim:Slot name="urn:oasis:names:tc:ebxml-regrep::rs:RegistryRequest:doNotCommit">

<rim:ValueList>

<rim:Value>true</rim:Value>

</rim:ValueList>

</rim:Slot>

....

....

</SubmitObjectsRequest>