Definitions

This page documents the various and sundry moving parts of the Web Services initiative. It is mostly for reference so that we can all be using the same terms when discussing pieces of the system. It is, of course, subject to change as the architecture evolves. :-)

General

WSCCI

The short name and tag for the over-arching initiative.

Phase 1

Request

The incoming HTTP request, which wants to be returned some HTTP data. Note that while we're assuming an HTTP baseline, we want the system to be flexible enough that one could fake an HTTP environment quite easily, allowing virtually all code to be successfully run from Drush, a headless Unit Test, or similar.

Context

The context of a request is all of the data and metadata that derives from the incoming request, either directly or indirectly. It represents the environment in which code is being run.

Request context

Request context is information that exists solely in the incoming request or is built exclusively from the incoming request. Examples include the requested URL (or $_GET['q']), the request type (text/html, text/json, etc.) the session ID (not the session data, just the ID), cookies, and so forth. Request context does not require any knowledge of Drupal or Drupal's state to determine.

Derived context

Any other context information is derived from the request context plus information from Drupal. For instance, $_GET['q'] = 'node/5', is request context. "The current node is nid 5, which is this object" is derived context. "The current organic group is node 12" is also derived context, which is derived from the "current node" context. The current user is another example of derived context (which is derived from the session cookie request context, plus Drupal's user records). The current site language is also derived context, as it may come from an HTTP header or from a user preference.

Butler object

The butler object refers to the central, unique object through which all requests for context information flows. It itself does not contain or produce context information, but acts as a broker for contextual information. The butler’s role is to provide a consistent, clean abstraction for all context. This has sometimes been referred to as the "context object" as well. (Which we'll call it in the final implementation is not yet determined.) There is at any given time one definitive context object in Drupal memory; however, that object may change in a controlled fashion throughout the request lifecycle.

Context handler

A context handler object is an object that is responsible for returning contextual information when requested via the butler object/context object. That is, a piece of code that cares about the "current site language" will ask the butler object, which will in turn ask the context handler that is configured to be responsible for answering that question. The response the context handler returns will then be returned to the original caller.

Phase 2

Plugin

A plugin is a self-contained, encapsulated piece of code that may be inserted into another proces. Some plugins may be used individually, such as cache plugins. Others may be joined together in series, such as text formats. Still others may be assembled into large, complex systems, such as Views plugins. In all cases, plugins represent encapulated logic, and should not be used for data storage. To a system that is using a plugin, its implementation should be (reasonably) opaque. In the present architectural plan plugins will be implemented as objects.

Plugin Configuration

Plugin configuration is user- or admin-supplied data that affects the behavior of a plugin. It is context-free, that is, it does not change with the context information but complements it. A plugin's behavior may be affected by context, by configuration, or both. In the present architectural plan plugin configuration will be implemented as an object that is passed to a Plugin. It will be persisted using whatever mechanism is developed by the Configuration Initiative

Plugin Type

A plugin type is the grouping for all plugins that satisfy a particular purpose. All plugins are the members of exactly one plugin type and should be interchangeable with other plugin of the same type. The canonical example here is caching. "Cache storage system" is a plugin type. "Database cache", "Memcache cache", etc. are plugins that conform to that type. In the current architectural plan plugin types will be implemented as a PHP interface, plus additional metadata.

Discovery

Discovery is the process of locating all available plugins of a given type that are available. Depending on the plugin type there may be multiple sensible ways to go about locating available plugins. In the current architectural plan, different discovery methods are possible, but a given plugin type will only support one.

Registration

Registration is the complementary process to discovery, and in some cases may be the exact same process simply viewed from a different angle. It is the process by which a plugin lets the system know it is present so it can be discovered when necessary.

Mapping

Some plugins (or sets of plugins) will be loaded by name directly. Others may require "find me the appropriate implementation, I don't care what it is" logic. The process of combining caller-specified data with contextual information to select the appropriate plugin is known as Mapping. (In earlier discussions it was sometimes called routing, but we decided that was a stupid name.) In the canonical example, the Cache system would have a mapper that combines "I need the page cache plugin object," combines it with the environment setting designating Memcache (with some configuration) as the backend for the page cache bin, and ultimately chooses to "instantiate a Memcache implementation, with this configuration, and return it." Not all plugin types will need mapping.

Service Locator

A service locator is a design pattern in which a mediator object, the service locator, is responsible for finding other service objects on demand. A service object acts as a broker for one logic object that needs another logic object, much in the same way that the butler/context object above acts as a broker between a logic object and request data. At this time we are not planning to implement a universal service locator, but it may be considered at a later date. It should be kept separate from the context object, which provides data, not plugins.

Phase 3

Response Controller

The response controller is a plugin that determines the type of request we have received and what the proper way to handle it is. That is, it determines if we are going to be returning an HTML page, an HTML fragment, a JSON object, a SOAP object, an image file, an HTTP 204 (which returns nothing), an HTTP 403 or 404, etc.

Response Object

We may implement a response object, which is the mirror of the request. It is an object on which we set the HTTP response data (headers, body, CSS and JS files, etc.) that should be returned. Whether or not this will be distinct from the response controller is still an open question.

Phase 4

Block

In the new model, blocks become much smarter and more robust than they are in Drupal 7. Blocks become a renderable plugin, which therefore has both configuration and access to context. Blocks may be cached based on their context. These blocks have more in common with Panes in the Panels module than with blocks as they exist in Drupal in Drupal 7.

Region

A region is a special kind of block that contains other blocks, positioned within a layout.

Layout

A layout is essentially a template plus some metadata. It likely will itself be implemented as a plugin.