Package ratpack.core.impose

Class Impositions

  • public final class Impositions
extends Object
    A mechanism for imposing things on an application from the outside and typically during testing.

    The impositions mechanism exists primarily to facilitate convenient overriding of configuration and behaviour at test time. MainClassApplicationUnderTest builds upon this mechanism. It uses the impose(Impositions, Factory) to register impositions, while starting up the application under test within the given function.

    Ratpack “components” are explicitly designed to be aware of impositions. Such components obtain the impositions either via the current() method, or via the server registry (e.g. Guice injection). User code does not typically need to be aware of impositions, as impositions are general used to influence upstream configuration. If you do need access to the impositions, prefer obtaining it from the server registry over current() as this method is thread sensitive.

    Actual impositions are implemented as specific classes, known to the consumer. ForceServerListenPortImposition and UserRegistryImposition are both examples of such. The consumers of these impositions simply obtain them from the impositions registry. 

    
 import ratpack.core.server.ServerConfig;
 import ratpack.core.impose.Impositions;
 import ratpack.core.impose.ServerConfigImposition;
 import ratpack.test.embed.EmbeddedApp;

 import static java.util.Collections.singletonMap;
 import static org.junit.jupiter.api.Assertions.*;

 public class Example {
   public static void main(String[] args) throws Exception {
     Impositions.of(i ->
       i.add(ServerConfigImposition.of(s -> s .props(singletonMap("foo", "imposed!"))))
     ).impose(() ->
       EmbeddedApp.of(s -> s
         .serverConfig(c -> c
           .props(singletonMap("foo", "original"))
         )
         .handlers(c -> c
           .get(ctx -> ctx.render(ctx.get(ServerConfig.class).get("/foo", String.class)))
         )
       )
     ).test(testHttpClient ->
       assertEquals("imposed!", testHttpClient.getText())
     );
   }
 }
    Since:
    1.2
    See Also:
    ServerConfigImposition, ForceServerListenPortImposition, ForceDevelopmentImposition, UserRegistryImposition

    • Method Detail

      • impose

        public static <T> T impose​(Impositions impositions,
                           Factory<? extends T> during)
                    throws Exception
        Sets impositions that will be available during execution of the given function, from this thread.

        The given impositions will effectively be the value returned by current() during the given function, which is executed immediately.

        The given impositions will only be returned from current() if called from the same thread that is calling this method.

        Type Parameters:
        T - the type of result of the given function
        Parameters:
        impositions - the impositions to impose during the given function
        during - the function to execute while the impositions are imposed
        Returns:
        the result of the given function
        Throws:
        Exception - any thrown by during

      • impose

        public <T> T impose​(Factory<? extends T> during)
             throws Exception
        Delegates to impose(Impositions, Factory), with this as the impositions.
        Type Parameters:
        T - the type of result of the given function
        Parameters:
        during - the function to execute while the impositions are imposed
        Returns:
        the result of the given function
        Throws:
        Exception - any thrown by during

      • current

        public static Impositions current()
        The cumulative currently imposed impositions, for the current thread.

        When multiple impositions have been applied using layered calls to impose(ratpack.core.impose.Impositions, ratpack.func.Factory<? extends T>), the impositions returned here are culmination of all.

        The getAll(Class) used for retrieving certain types of impositions returns objects in order of outer-most-first. This allows a inner-most-wins strategy for impositions of single values (e.g. ForceServerListenPortImposition).

        If no impositions have been imposed at call time, the returned impositions object is effectively empty.

        Returns:
        the currently imposed impositions

      • none

        public static Impositions none()
        An empty set of impositions.

        Possibly useful during testing.

        Returns:
        an empty set of impositions

      • of

        public static Impositions of​(Action<? super ImpositionsSpec> consumer)
                      throws Exception
        Creates an impositions instance of the given imposition objects.

        Possibly useful during testing.

        Returns:
        an impositions instance of the given imposition objects
        Throws:
        Exception

      • get

        @Deprecated
public <T extends Imposition> Optional<T> get​(Class<T> type)
        Deprecated.
        since 1.9, use getAll(Class).
        Return an imposition of the given type, if one is currently imposed.
        Type Parameters:
        T - the type of imposition
        Parameters:
        type - the type of imposition
        Returns:
        the imposition of the given type

      • getAll

        public <T extends Imposition> Iterable<? extends T> getAll​(Class<T> type)
        Return all impositions of the given type.
        Type Parameters:
        T - the type of imposition
        Parameters:
        type - the type of imposition
        Returns:
        the impositions of the given type
        Since:
        1.9