InteractionService

A low-level service to programmatically "connect" (or create a session, or interact with; choose your term) the framework’s runtime.

This service is used internally by the framework itself, for example when a viewer receives a request a new InteractionLayer is created for the duration of the users’s interaction. It is also used by integration tests, to be able to connect to the database.

You could think of this as analogous to an HttpRequest , or a JPA EntityManager or JDO PersistenceManager .

There are two main APIs exposed. One is to #openInteraction(InteractionContext) open a new InteractionLayer , to be #closeInteractionLayers() closed later . The other is to execute a Callable or ThrowingRunnable within the duration of an InteractionLayer , wrapping up automatically. This is what is used by org.apache.causeway.applib.services.sudo.SudoService , for example.

API

InteractionService.java
interface InteractionService {
  InteractionLayer openInteraction()     (1)
  InteractionLayer openInteraction(InteractionContext interactionContext)     (2)
  void closeInteractionLayers()     (3)
  boolean isInInteraction()     (4)
  R call(InteractionContext interactionContext, Callable<R> callable)     (5)
  void run(InteractionContext interactionContext, ThrowingRunnable runnable)     (6)
  R callAnonymous(Callable<R> callable)     (7)
  void runAnonymous(ThrowingRunnable runnable)     (8)
  Try<R> callAndCatch(InteractionContext interactionContext, Callable<R> callable)     (9)
  Try<Void> runAndCatch(InteractionContext interactionContext, ThrowingRunnable runnable)     (10)
  Try<R> callAnonymousAndCatch(Callable<R> callable)     (11)
  Try<Void> runAnonymousAndCatch(ThrowingRunnable runnable)     (12)
  InteractionLayer nextInteraction()     (13)
  InteractionLayer nextInteraction(InteractionContext interactionContext)     (14)
}
1 openInteraction()

If present, reuses the current top level InteractionLayer , otherwise creates a new anonymous one.
2 openInteraction(InteractionContext)

Returns a new or reused InteractionLayer that is a holder of the InteractionContext on top of the current thread’s interaction layer stack.
3 closeInteractionLayers()

closes all open InteractionLayer (s) as stacked on the current thread
4 isInInteraction()
5 call(InteractionContext, Callable)

Executes a block of code with a new or reused InteractionContext using a new or reused InteractionLayer .
6 run(InteractionContext, ThrowingRunnable)

Variant of #call(InteractionContext, Callable) that takes a runnable.
7 callAnonymous(Callable)

As per #call(InteractionContext, Callable) , but (normally) using an anonymous InteractionContext .
8 runAnonymous(ThrowingRunnable)

As per #run(InteractionContext, ThrowingRunnable) , but (normally) using an anonymous InteractionContext .
9 callAndCatch(InteractionContext, Callable)

Variant of #call(InteractionContext, Callable) that wraps the return value with a Try , also catching any exception, that might have occurred.
10 runAndCatch(InteractionContext, ThrowingRunnable)

Variant of #run(InteractionContext, ThrowingRunnable) that returns a Try of Result , also catching any exception, that might have occurred.
11 callAnonymousAndCatch(Callable)

Variant of #callAnonymous(Callable) that wraps the return value with a Try , also catching any exception, that might have occurred.
12 runAnonymousAndCatch(ThrowingRunnable)

Variant of #runAnonymous(ThrowingRunnable) that returns a Try of Try , also catching any exception, that might have occurred.
13 nextInteraction()

Primarily for testing, closes the current interaction and opens a new one.
14 nextInteraction(InteractionContext)

Primarily for testing, closes the current interaction and opens a new one with the specified InteractionContext .

Members

openInteraction()

If present, reuses the current top level InteractionLayer , otherwise creates a new anonymous one.

openInteraction(InteractionContext)

Returns a new or reused InteractionLayer that is a holder of the InteractionContext on top of the current thread’s interaction layer stack.

If available reuses an existing InteractionContext , otherwise creates a new one.

The InteractionLayer represents a user’s span of activities interacting with the application. These can be stacked (usually temporarily), for example for a sudo session or to mock the clock. The stack is later closed using #closeInteractionLayers() .

closeInteractionLayers()

closes all open InteractionLayer (s) as stacked on the current thread

isInInteraction()

call(InteractionContext, Callable)

Executes a block of code with a new or reused InteractionContext using a new or reused InteractionLayer .

If there is currently no InteractionLayer a new one is created.

If there is currently an InteractionLayer that has an equal InteractionContext to the given one, it is reused, otherwise a new one is created.

run(InteractionContext, ThrowingRunnable)

Variant of #call(InteractionContext, Callable) that takes a runnable.

callAnonymous(Callable)

As per #call(InteractionContext, Callable) , but (normally) using an anonymous InteractionContext .

However, if an #isInInteraction() interaction (session) already exists (with possibly some other non-anonymous InteractionContext ), then this is used instead.

runAnonymous(ThrowingRunnable)

As per #run(InteractionContext, ThrowingRunnable) , but (normally) using an anonymous InteractionContext .

However, if an #isInInteraction() interaction (session) already exists (with possibly some other non-anonymous InteractionContext ), then this is used instead.

callAndCatch(InteractionContext, Callable)

Variant of #call(InteractionContext, Callable) that wraps the return value with a Try , also catching any exception, that might have occurred.

runAndCatch(InteractionContext, ThrowingRunnable)

Variant of #run(InteractionContext, ThrowingRunnable) that returns a Try of Result , also catching any exception, that might have occurred.

callAnonymousAndCatch(Callable)

Variant of #callAnonymous(Callable) that wraps the return value with a Try , also catching any exception, that might have occurred.

runAnonymousAndCatch(ThrowingRunnable)

Variant of #runAnonymous(ThrowingRunnable) that returns a Try of Try , also catching any exception, that might have occurred.

nextInteraction()

Primarily for testing, closes the current interaction and opens a new one.

In tests, this is a good way to simulate multiple interactions within a scenario. If you use the popular given/when/then structure, consider using at the end of each "given" or "when" block.

nextInteraction(InteractionContext)

Primarily for testing, closes the current interaction and opens a new one with the specified InteractionContext .

Implementation

The Core Runtime Services module provides a default implementation, InteractionServiceDefault.