A reference architecture (Part 1)

Introduction

IT and business needs have changed over the years, demanding system design to follow. In today’s tough economical conditions, there is more than ever the need to control costs and as such it is indispensable that an enterprise has to be able to respond very quickly to change with minimal effort. Traditionally projects start in the IT department, mostly without taking into account business requirements, but this just doesn’t work anymore. Instead, projects should be driven by business needs, and evidently the underlying IT solution has to support this.

I have built a systems architectural design template, adhering to proven SOA guidelines, to tackle this challenge.  Of course, every environment is different – and so is every design – but the idea is to have a template that uses best practises and that is extensible to your own needs. The result is a multi-layered architecture based on resources like Juval Lowy’s master class, the Web Service Software Factory guidelines, feedback from other architects and experiences with developers using this architecture.

Architectural guidelines

To begin, the template below visually represents the multi-layered systems architecture I have developed:

Description of the layers

The client layer represents all components that consume the underlying managers. It’s more than just a presentation layer, because other than graphical user interface clients this layer also contains non-visible clients that can trigger managers (for example, an email or an incoming file on an FTP server). These clients can perform non-business related validation on user input, but they don’t contain other business or data access logic.  A client can never talk directly with agents or utilities, it only talks to managers.

The manager layer contains the top-level coarse-grained systems, and uses the agents/utilities to delegate work:

• Processes:
  • Expose business processes
  • Typically long running (workflow) and invoked using a one-way or notification (reservation) pattern
  • Encapsulates rules particular to the business process
  • Includes transaction control using compensation
  • One process may act as a controller for another and invoke it
  • Can be stateful
  • Invoke underlying agents/utilities
• Activities:
  • Expose business activities that encapsulate calls to multiple agent and/or utilities to perform a single activity
  • Each operation scoped as a logical unit of work
  • Typically immediate request-response pattern
  • Includes rules that are common to the organization

The agent and utility layer contains the low-level granular and fine-grained components. Agents provide business-centric functional context, while utilities are more related to infrastructure functionality like logging and emailing.

An agent:

• Exposes business entity data
• Typically immediate request-response pattern
• Encapsulates data consistency rules and CRUD that are common to the entire organization
• May invoke utilities
• Each operation scoped as a logical unit of work

There are different types of agents, for example:

• Proxy agent: referred to as wrapper, broker, or gateway, they act as a bridge between other members of the service-oriented system and incompatible subsystems
• Device agent: a specialized type of proxy that stands in front of a hardware device.
• Entity agent: exposes a single uncluttered concept that represents a business entity. They are independent from the business processes.

An utility :

• Exposes shared functionality that is not specific to a business process or entity (not domain specific)
• Typically immediate request-response
• Does not invoke other agents

The business entities layer models the real-world, global domain-specific objects, like Customers and Orders.

The resource layer contains resources, which can be a database, external service or any other kind of resource.

Important to know is that managers are service-enabled, and that agents and utilities can be service enabled but don’t have to.

Communication flow

Communication between clients, managers, agents, resource access layer and resource layer is only allowed from top to bottom. These are the rules:

• A client can consume the services from manager layer, but it cannot access the agent or resource access layer directly.
• A component from the manager layer can consume the agent and utility layer, but it cannot access the resource access layer directly.
• The enterprise business entities are used by manager, agent, utility and resource access layer, and so they are never exposed to the outside world.

The layers in detail

The manager layer has the same structure of the agent/utility layer, except that it does not have a resource access layer. So, the manager structure is designed according to the following structure:

Manager layer

And the agent and utility layer is designed according to the following structure:

Agent/Utility layer

Note that for the manager the service interface layer is mandatory: a manager is always exposed as a service to the clients. But for an agent or utility, the service interface layer is optional. This means that:

• The service business layer of a manager can use the service interface layer of an agent
• The service business layer of a manager can use the service business layer of an agent directly (and later, if the agent is service enabled, talk to the service interface layer instead)

Service interface layer

The service contract contains the interface for the service. It defines a logically and semantically related set of operations grouped on an interface and is about how a service behaves.

The data contract contains all data contracts that the service uses. A data contract is a formal agreement between a service and a client that abstractly describes the data to be exchanged. It precisely defines, for each parameter or return type, what data is serialized (turned into XML) to be exchanged. An important characteristic is that a data contract can be reused within the service. To communicate, the client and the service do not have to share the same types, only the same data contracts.

The message contract contains all message contracts needed by the service. A message contract is a wrapper around the data contracts and is mostly used when you need explicit control over the format of the SOAP (Simple Object Access Protocol) message, but in the architecture we always use them for the following reasons:

• clarity and uniformity: use the same approach in all services
• explicit implementation of the Request/Response pattern

An important characteristic is that a message contract is designed not to be reused.

The fault contract contains all fault contracts. A fault contract provides a way to describe faults in a contract and mark certain types of exceptions as appropriate for transmission to the client, shielding underlying system exceptions. As a rule we use fault contracts for errors that are not part of the normal program flow, for example:

• void SendEmail(SendEmailRequest) throws fault exception when subject or other fields are not filled in
• GetCustomersResponse GetCustomers() throws fault exception when underlying data source is unavailable

The service adapter contains the actual implementation of the service interface. It consists of the adapter, which invokes business actions after it uses entity translators to translate between message types or data types and types required by the business actions.

Service business layer

The business layer takes care of enterprise business entity validation and other custom business logic.

Resource access layer

The resource access layer contains the repositories and resource managers. Repositories are abstractions that interact with the resource managers and provide business interfaces to the domain model: so they are coarse-grained and closer to the domain. A repository can work with an underlying resource manager or it can act as a repository to mock data (a convenient way to do unit testing). Using dependency injection techniques, the correct repositories can be invoked at runtime by specifying them in a configuration file. A resource manager is an implementer towards a specific resource, so they are fine-grained and closer to the database. They typically implement the basic CRUD (create, read, update and delete) and other data operations, and use entity translators to do the mapping between data entities and enterprise business entities.

Rules:

• An agent can use its repository (only one!) from the resource access layer, and can consume utilities.
• A utility can only use its own repository (only one!) from the resource access layer.
• A repository will mostly use only one resource manager, but in some cases it can use one or more resource managers as long as they belong to the same business context and business entities (to implement master-data relationships). Example: an OrderRepository can use a resource manager that gets partial order information from one database and another resource manager that gets another part of order information from an xml file, because the same business entity is being constructed out of it. An OrderRepository cannot use a resource manager to get for example customer information; because this does not belong to the OrderRepository’s core tasks (in this case a manager service has to be created to aggregate order and customer information).

Data flow

The following diagram illustrates the request data flow:

Data flow

Continued in part 2.

Advertisement