Current Design of the ebxmlrr Server

Introduction

The structure of this document is based on a software architecture specification template by Donald Firesmith for the OPEN Process Framework.

The target audience for this document are:

  • Developers who work on the implementation of the ebxmlrr server and client
  • Users of ebXML registries and clients who want to gain a deeper understanding of the server design

Software Component Architecture

Overview

Here is a graph that shows the top physical packages and interfaces and their dependencies. The graph was generated by

Pasta

package dependencies

The registry is entirely implemented in Java. It provides two interfaces to access its functions: SOAP/HTTP and REST/HTTP. The HTTP interfaces are implemented as servlets that are hosted by a web container like Tomcat. The registry data is stored in a relational database. The repository data is stored as files in the regular OS filesystem.

The following sections describe the components of the registry server.

SOAP Servlet (package interfaces)

Implements the normative binding for SOAP/HTTP. The servlet checks the authorization of the message sender, translates the SOAP message into a registry operation and returns the result.

REST Servlet (package interfaces)

Implements a plain HTTP binding for the registry service. It uses an architectural style for creating requests called Representational State Transfer (REST). This style mandates how service calls and parameters are passed through HTTP. It also requires that the operations are stateless.

The servlet decodes the REST requests, invokes the corresponding registry operation and returns the result.

Life Cycle Manager (package lcm)

Provides the ebXML LifeCycleManager registry service.

Query Manager (package query)

The Query Manager supports both filter queries and SQL queries.

Filter Query Manager

Provides the ebXML QueryManager filter query registry service. The queries are translated to SQL queries and forwarded to the SQL Query Manager component.

SQL Query Manager

Provides the ebXML QueryManager SQL query registry service and supports the execution of SQL queries. This component parses incoming ebXML SQL queries and generates SQL queries that take the user permissions into account.

Authentication and Authorization (package security)

Provides utility methods to authenticate users and check their authorization. The ebxmlrr client provides a basic tool to maintain users.

Repository (package repository)

Implements a repository that holds the repository items. There is a generic interface to the repository. The current implementation stores all items in the file system.

Registry Data Layer (package persistence)

This component provides a data access layer to a relational database. It tries to use fairly generic SQL statements that are compatible to the major databases. The database holds all registry items.

3 party application dependencies

  • J2DSK 1.4.1_01 for running ebxmlrr (xalan.jar needs to be updated)
  • JWSDP 1.0_01 (contains JAXR API and JAXM implementation)
  • Tomcat 4 (or a compatible web container) for running ebxmlrr
  • Apache Jakarta Commons Logging 1.0
  • (development only: ANT 1.4 or 1.5)
  • (development only: JavaCC 2.1)

Mechanisms

Startup and Shutdown

The server is deployed to a web container that supports the Java Servlet specification, version 2.2. The web container creates an instance of the servlet when a request arrives. After the request is processed, the instance gets recycled, i.e. it may get cached and reused or it is removed. When the web container is shut down properly, it discards all servlets after all requests were processed.

Ebxmlrr can pool database connections so that it does not have to create a new connection every time that a request is processed.

Error Handling

All components in the server throw RegistryExceptions when an error is encountered. Every component specializes the RegistryException for every type of error. This helps to provide clearer error reports and pinpoints the component that created the exception. All registry exceptions are caught by the servlets and reported back to the client through the ebXML status.

Errors that occur outside of the regular servlet operation, e.g. at start up or shut down are logged by the web container and can be monitored by the registry operator.

Logging

The registry server uses the Jakarta Commons Logging API to log all events and errors. Every Java package uses its package name when logging an event. The web container may use its own logging.

The Commons Logging API allows to configure the log implementation. That enables the web container and the ebxmlrr server to write to the same log.

Persistence

Ebxmlrr distinguishes two data types that are stored persistently, registry items and repository items. Repository items are the actual business data, e.g. contracts, and registry items are metadata that mainly serves to categorize the repository items.

Both registry items and repository items are managed through the Life Cycle Manager. It provides methods to store new items, update existing items and remove items.

The current repository implementation provides a generic interface to the repository but implements only a file-based repository. Every repository item is stored as a separate file. The Universally Unique Identifier (UUID) of the item is used as its filename.

Registry items are stored in a relational database. Ebxmlrr relies on data access objects (DAO) that provide an object-oriented interface to the registry items. Inside the DAO, the operations are translated into SQL statements.

Concurrency

The web container manages concurrent requests. It instantiates a new servlet for every request which prevents thread synchronization issues on that level.

None of the component interfaces contain state. All of the interfaces are implemented as singletons that are instantiated in a thread-safe manner. That makes access to the components thread-safe.

The DAOs use transactions by default. If an item is manipulated more than once concurrently, one of the transactions fails.

Distribution

The ebxmlrr core components may not be distributed. It would probably be possible to access the database from more than one ebxmlrr instance, however the file repository is not designed to allow access from separate ebxmlrr instances. The SQL database may run on any host. Ebxmlrr can only use one database instance.