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.
-
ClassDescriptionThis class provides a thread-safe implementation of the
SharedResource
interface, and should be used for all subclasses ofRequestHandler
,ClientProvider
andServerProvider
.This is the immutable Container.This interface provides an API for writing metric data to the configuredMetricConsumer
.Declares the interface for the arbitrary context object to pass to both theMetric.set(String, Number, Context)
andMetric.add(String, Number, Context)
methods.An implementation ofSharedResource
that does not do anything.ReferencedResource<T extends SharedResource>Utility class for working with reference-countedSharedResource
s.Utility class for working withSharedResource
s andResourceReference
s.This class represents a single request (which may have any content model that aServerProvider
chooses to implement).Represents a live reference to aSharedResource
.This class represents the single response (which may have any content model that aRequestHandler
chooses to implement) of some single request.This interface acts as a namespace for the built-in status codes of the jDISC core.This interface defines a reference counted resource.This interface provides a callback for when theRequest.setTimeout(long, TimeUnit)
is invoked.This class provides access to the current time in milliseconds, as viewed by theContainer
.