@PublicApi

Package com.yahoo.jdisc

Provides the common classes and interfaces of the jDISC core.

jDISC is a single-process, multi-threaded application container that consists of exactly one Application with an optional Metric configuration, one or more RequestHandlers, one or more ServerProviders, and one or more named BindingSets. When starting an Application, and whenever else the current configuration changes, it is the responsibility of the Application to create and activate a new Container that matches the most recent configuration. The Container itself is an immutable object, ensuring that the context of a Request never changes during its execution. When a new Container is activated, the previous is deactivated and scheduled for shutdown as soon as it finishes processing all previously accepted Requests. At any time, a jDISC process will therefore have zero (typically during application startup and shutdown) or one active Container, and zero or more deactivated Containers. The currently active Container is available to ServerProviders through an application-scoped singleton, making sure that no new Request is ever passed to a deactivated Container.

A Request is created when either a) a ServerProvider accepts an incoming connection, or b) a RequestHandler creates a child Request of another. In the case of the ServerProvider, the CurrentContainer interface provides a reference to the currently active Container, and the Application's BindingSetSelector (provided during configuration) selects a BindingSet based on the Request's URI. The BindingSet is what the Container uses to match a Request's URI to an appropriate RequestHandler. Together, the Container reference and the selected BindingSet make up the context of the Request. When a RequestHandler chooses to create a child Request, it reuses both the Container reference and the BindingSet of the original Request, ensuring that all processing of a single connection happens within the same Container instance. For every dispatched Request there is always exactly one Response. The Response is never routed, it simply follows the call stack of the corresponding Request.

Because BindingSets decide on the RequestHandler which is to process a Request, using multiple BindingSets and a property-specific BindingSetSelector, one is able to create a Container capable of rewiring itself on a per-Request basis. This can be used for running production code in a mock-up environment for offline regression tests, and also for features such as Request bucketing (selecting a bucket BindingSet for n percent of the URIs) and rate-limiting (selecting a rejecting-type RequestHandler if the system is in some specific state).

Finally, the Container provides a minimal Metric API that consists of a Metric producer and a MetricConsumer. Any component may choose to inject and use the Metric API, but all its calls are ignored unless the Application has chosen to inject a MetricConsumer provider during configuration. For efficiency reasons, the Container provides the ContainerThread which offers thread local access to the Metric API. This is a class that needs to be explicitly used in whatever Executor or ThreadFactory the Application chooses to inject into the Container.

For unit testing purposes, the com.yahoo.jdisc.test package provides classes and interfaces to help setup and run a jDISC application in a test environment with as little effort as possible.

See Also:

com.yahoo.jdisc.application, com.yahoo.jdisc.handler, com.yahoo.jdisc.service, com.yahoo.jdisc.test

Interface Summary

Interface	Description
Container	This is the immutable Container.
Metric	This interface provides an API for writing metric data to the configured MetricConsumer.
Metric.Context	Declares the interface for the arbitrary context object to pass to both the Metric.set(String, Number, Context) and Metric.add(String, Number, Context) methods.
ResourceReference	Represents a live reference to a SharedResource.
Response.Status	This interface acts as a namespace for the built-in status codes of the jDISC core.
SharedResource	This interface defines a reference counted resource.
TimeoutManager	This interface provides a callback for when the Request.setTimeout(long, TimeUnit) is invoked.
Timer	This class provides access to the current time in milliseconds, as viewed by the Container.

Class Summary

Class	Description
AbstractResource	This class provides a thread-safe implementation of the SharedResource interface, and should be used for all subclasses of RequestHandler, ClientProvider and ServerProvider.
HeaderFields	This is an encapsulation of the header fields that belong to either a Request or a Response.
NoopSharedResource	An implementation of SharedResource that does not do anything.
ReferencedResource<T extends SharedResource>	Utility class for working with reference-counted SharedResources.
References	Utility class for working with SharedResources and ResourceReferences.
Request	This class represents a single request (which may have any content model that a ServerProvider chooses to implement).
Response	This class represents the single response (which may have any content model that a RequestHandler chooses to implement) of some single request.