mdk

Interface Session

All Known Implementing Classes:

SessionImpl

public interface Session

A session provides a lightweight sequential context that a microservice can use in the context of any application framework in order to manage its interactions with other microservices. It provides simple APIs for service resolution, distributed tracing, and circuit breakers. A microservices architecture enables small self contained units of business logic to be implemented by separate teams working on isolated services based on the languages and frameworks best suited for their problem domain. Any given microservice will contain sequential business logic implemented in a variety of ways depending on the application framework chosen. For example it may be a long running thread, a simple blocking request handler, or a chained series of reactive handlers in an async environment. For the most part this business logic can be implemented exactly as prescribed by the application framework of choice, however in a microservices architecture, some special care needs to be taken when this business logic interacts with other microservices. Because microservices are updated with much higher frequency than normal web applications, the interactions between them form key points that require extra care beyond normal web interactions in order to avoid creating a system that is both extremely fragile, unreliable, and opaque. Realtime service resolution, distributed tracing, and resilience heuristics such as circuit breakers provide the foundational behavior required at these interaction points. These capabilites must be combined with the defensive coding practice of intelligent fallback behavior when remote services are unavailable or misbehaving, in order to build a robust microservice application. Because of this, a session is expected to be created and made available to all business logic within a given microservice, e.g. on a per request basis, as a thread local, part of a context object, etc depending on the application framework of choice.

Field Summary

Fields

Modifier and Type	Field and Description
static quark.reflect.Class	mdk_Session_ref

Method Summary

Modifier and Type	Method and Description
LoggedMessageId	critical(java.lang.String category, java.lang.String text) Record a log entry at the CRITICAL logging level.
LoggedMessageId	debug(java.lang.String category, java.lang.String text) Record a log entry at the DEBUG logging level.
LoggedMessageId	error(java.lang.String category, java.lang.String text) Record a log entry at the ERROR logging level.
java.lang.String	externalize() Returns an externalized representation of the distributed session.
void	fail_interaction(java.lang.String message) Record an interaction as failed.
void	finish_interaction() Finish an interaction.
mdk_protocol.OperationalEnvironment	getEnvironment() Return the session's Environment.
java.lang.Object	getProperty(java.lang.String property) Return the value of a property from the distributed session.
java.lang.Double	getRemainingTime() Return how many seconds until the session ought to end.
java.lang.Boolean	hasProperty(java.lang.String property) Return whether the distributed session has a property.
LoggedMessageId	info(java.lang.String category, java.lang.String text) Record a log entry at the INFO logging level.
java.lang.String	inject() Grabs the encoded context.
void	interact(quark.UnaryCallable callable) This is a convenience API that will perform start_interaction() followed by callable(ssn) followed by finish_interaction().
java.lang.Object	resolve_async(java.lang.String service, java.lang.String version) Locate a compatible service instance asynchronously.
mdk_discovery.Node	resolve_until(java.lang.String service, java.lang.String version, java.lang.Double timeout) Locate a compatible service instance with a non-default timeout.
mdk_discovery.Node	resolve(java.lang.String service, java.lang.String version) Locate a compatible service instance.
void	route(java.lang.String service, java.lang.String version, java.lang.String target, java.lang.String targetVersion) EXPERIMENTAL; requires MDK_EXPERIMENTAL=1 environment variable to function.
void	setDeadline(java.lang.Double seconds) Set how many seconds the session is expected to live from this point.
void	setProperty(java.lang.String property, java.lang.Object value) Set a property on the distributed session.
void	setTimeout(java.lang.Double seconds) DEPRECATED, use setDeadline().
void	start_interaction() Start an interaction with a remote service.
void	trace(java.lang.String level) EXPERIMENTAL: Set the logging level for the session.
LoggedMessageId	warn(java.lang.String category, java.lang.String text) Record a log entry at the WARN logging level.

Field Detail

mdk_Session_ref

static final quark.reflect.Class mdk_Session_ref

Method Detail

inject

java.lang.String inject()

Grabs the encoded context.

externalize

java.lang.String externalize()

Returns an externalized representation of the distributed session.

critical

LoggedMessageId critical(java.lang.String category,
                         java.lang.String text)

Record a log entry at the CRITICAL logging level.

error

LoggedMessageId error(java.lang.String category,
                      java.lang.String text)

Record a log entry at the ERROR logging level.

warn

LoggedMessageId warn(java.lang.String category,
                     java.lang.String text)

Record a log entry at the WARN logging level.

info

LoggedMessageId info(java.lang.String category,
                     java.lang.String text)

Record a log entry at the INFO logging level.

debug

LoggedMessageId debug(java.lang.String category,
                      java.lang.String text)

Record a log entry at the DEBUG logging level.

trace

void trace(java.lang.String level)

EXPERIMENTAL: Set the logging level for the session.

route

void route(java.lang.String service,
           java.lang.String version,
           java.lang.String target,
           java.lang.String targetVersion)

EXPERIMENTAL; requires MDK_EXPERIMENTAL=1 environment variable to function. Override service resolution for the current distributed session. All attempts to resolve *service*, *version* will be replaced with an attempt to resolve *target*, *targetVersion*. This effect will be propogated to any downstream services involved in the distributed session.

resolve

mdk_discovery.Node resolve(java.lang.String service,
                           java.lang.String version)

Locate a compatible service instance. Uses a minimum of 10 seconds and the timeout set on the session.

resolve_until

mdk_discovery.Node resolve_until(java.lang.String service,
                                 java.lang.String version,
                                 java.lang.Double timeout)

Locate a compatible service instance with a non-default timeout.

resolve_async

java.lang.Object resolve_async(java.lang.String service,
                               java.lang.String version)

Locate a compatible service instance asynchronously. The result is returned as a promise.

start_interaction

void start_interaction()

Start an interaction with a remote service. The session tracks any nodes resolved during an interactin with a remote service. The service resolution API permits a compatible instance of the service to be located. In addition, it tracks which exact instances are in use during any interaction. Should the interaction fail, circuit breaker state is updated for those nodes, and all involved instances involved are reported to the tracing services. This permits realtime reporting of integration issues when services are updated, and also allows circuit breakers to mitigate the impact of any such issues.

fail_interaction

void fail_interaction(java.lang.String message)

Record an interaction as failed. This will update circuit breaker state for the remote nodes, as well as reporting all nodes involved to the tracing system.

finish_interaction

void finish_interaction()

Finish an interaction. This marks an interaction as completed.

interact

void interact(quark.UnaryCallable callable)

This is a convenience API that will perform start_interaction() followed by callable(ssn) followed by finish_interaction().

setDeadline

void setDeadline(java.lang.Double seconds)

Set how many seconds the session is expected to live from this point. If a timeout has previously been set the new timeout will only be used if it is lower than the existing timeout. The MDK will not enforce the timeout. Rather, it provides the information to any process or server in the same session (even if they are on different machines). By passing this timeout to blocking APIs you can ensure timeouts are enforced across a whole distributed session.

setTimeout

void setTimeout(java.lang.Double seconds)

DEPRECATED, use setDeadline().

getRemainingTime

java.lang.Double getRemainingTime()

Return how many seconds until the session ought to end. This will only be accurate across multiple servers insofar as their clocks are in sync. If a timeout has not been set the result will be null.

getProperty

java.lang.Object getProperty(java.lang.String property)

Return the value of a property from the distributed session.

setProperty

void setProperty(java.lang.String property,
                 java.lang.Object value)

Set a property on the distributed session. The key should be prefixed with a namespace so that it doesn't conflict with built-in properties, e.g. 'examplenamespace:myproperty' instead of 'myproperty'. The value should be JSON serializable.

hasProperty

java.lang.Boolean hasProperty(java.lang.String property)

Return whether the distributed session has a property.

getEnvironment

mdk_protocol.OperationalEnvironment getEnvironment()

Return the session's Environment.