Apache ACE™

Home » Docs » Design

Remote Interfaces Design

Summary

This document describes the generic design of the remote interfaces that can be used to access a system within the ACE topology. The design can be divided into three separate logical components: the connectors, the protocol adapters and session management.

The connectors provide the interfaces to the system. In general, you can have more than one, for example in ACE we can define a client connector that allows us to talk to the ACE server.

The protocol adapters expose interfaces through a specific protocol. A REST adapter provides access through the HTTP protocol, and specific UI adapters can be used to interact with a user using a specific web or desktop framework. In future extensions, adapters can also implement JMX management for example.

Session management is responsible for managing authentication and authorization across all protocol adapters. This makes sessions a first class citizen in the design and abstracts them away from protocol specific sessions.

Design

The design is based on the 4+1 View, which means we look at the logical view, process view, use case design, implementation view and deployment view to arrive at the full design.

Logical View

The design is split into three components:

  1. Protocol Adapters. For every protocol that we support, we have to create a protocol adapter, whose responsibility it is to expose connector interfaces. Connectors are discovered by leveraging the service registry using the whiteboard pattern. The protocol adapter talks to the session manager for managing sessions and making sure certain permissions have been given to the authenticated user. If the protocol itself also supports the notion of sessions, it's the adapters responsibility to ensure that the life cycle of the protocol specific session is aligned with our own sessions.

  2. Connectors. Each connector, which is implemented as a collection of one or more OSGi services, provides a specific API to talk to a system. An example is the client API. Which services make up a connector is specified in the design of a component.

  3. Session Manager. Responsible for managing sessions and the authentication and authorization of actors that use them. The session manager will be invoked by protocol adapters. It leverages the OSGi User Admin service to provide users with credentials, roles and permissions. The session manager is allowed to expire sessions if it needs to, so protocol adapters should always check if a session is still open.

Process View

Incoming calls arrive at a protocol implementation. As soon as they reach one of our adapters, the adapter should synchronously talk to the session manager, because it needs to check for the proper authentication and authorization before it can continue.

A session manager is allowed to spawn a background thread for session expiration purposes, but implementations can also decide to leverage Java features such as "weak" references, or use synchronous expiration as a side effect of incoming calls.

Use Case Design

There are two major use cases that are designed explicitly here:

  1. UC-RI-1 Register Connector Services
  2. UC-RI-2 Invoke Operation

UC-RI-1 Register Connector Services

Normal Flow
  1. A component registers a service in the OSGi service registry.
  2. The protocol adapter, listening whiteboard style, is notified and validates the service.
  3. The protocol adapter hands over the service to a protocol specific factory that creates an adapter.
  4. The protocol adapter registers the created adapter with the protocol implementation.

UC-RI-2 Invoke Operation

Normal Flow
  1. An actor invokes an operation on a service.
  2. The invocation arrives at the protocol adapter, who looks up or creates the session with the session manager.
  3. The protocol adapter checks if the actor is authenticated and authorized to invoke this operation.
  4. The protocol adapter invokes the operation on the connector associated with this adapter.

Implementation View

The implementation views for the different connectors and protocol adapters can be found in the designs of these components.

The implementation view for the session manager consists of:

Note that this current implementation is specific to the client, because for now that is the only place where we have sessions (the other connectors are essentially stateless).

Deployment View

The connectors and protocol adapters are deployed as different bundles: