Package ratpack.core.server

Interface RatpackServer

  • public interface RatpackServer
    The entry point for creating and starting a Ratpack application.

    The of(Action) static method is used to create a server. 

    
 import ratpack.core.server.RatpackServer;
 import ratpack.core.server.ServerConfig;

 import ratpack.test.ServerBackedApplicationUnderTest;
 import static org.junit.jupiter.api.Assertions.*;

 public class Example {
   public static void main(String... args) throws Exception {
     RatpackServer server = RatpackServer.of(s -> s
       .serverConfig(ServerConfig.embedded())            // base server configuration (e.g. port) - optional
       .registryOf(r -> r.add(String.class, "foo"))      // registry of supporting objects - optional
       .handlers(chain -> chain                          // request handlers - required
         .get("a", ctx -> ctx.render(ctx.get(String.class) + " 1"))
         .get("b", ctx -> ctx.render(ctx.get(String.class) + " 2"))
       )
     );

     // this method starts the server, via server.start() and then calls server.stop()
     ServerBackedApplicationUnderTest.of(server).test(httpClient -> {
       assertEquals("foo 1", httpClient.getText("a"));
       assertEquals("foo 2", httpClient.getText("b"));
     });
   }
 }
    Server objects are thread safe in that every instance method is synchronized.
    See Also:
    RatpackServerSpec, Service, of(Action)

    • Method Detail

      • of

        static RatpackServer of​(Action<? super RatpackServerSpec> definition)
                 throws Exception
        Creates a new, unstarted, Ratpack server from the given definition.

        The action argument effectively serves as the definition of the server. It receives a mutable server builder style object, a RatpackServerSpec. The action is retained internally by the server, and invoked again if the reload() method is called.

        Parameters:
        definition - the server definition
        Returns:
        a Ratpack server
        Throws:
        Exception - any thrown by creating the server
        See Also:
        RatpackServerSpec

      • getScheme

        String getScheme()
        The URL scheme the server uses.
        Returns:
        either http or https depending on whether the server is using SSL or not

      • getBindPort

        int getBindPort()
        The actual port that the application is bound to.
        Returns:
        the actual port that the application is bound to, or -1 if the server is not running

      • getBindHost

        @Nullable
String getBindHost()
        The actual host/ip that the application is bound to.
        Returns:
        the actual host/ip that the application is bound to, or null if this server is not running

      • isRunning

        boolean isRunning()
        Returns true if the server is running.
        Returns:
        true if the server is running

      • start

        void start()
    throws Exception
        Starts the server, returning as soon as the server is up and ready to receive requests.

        This will create new threads that are not daemonized. That is, a running Ratpack server will prevent the JVM from shutting down unless System.exit(int) is called. It is generally advisable to stop the server instead of forcefully killing the JVM.

        Calling this method while the server is running has no effect.

        Throws:
        Exception - if the server could not be started

      • stop

        void stop()
   throws Exception
        Stops the server, returning as soon as the server has stopped receiving requests.

        This method will terminate all threads started by the server.

        Throws:
        Exception - if the server could not be stopped cleanly

      • await

        boolean await​(Duration timeout)
       throws InterruptedException
        Blocks until the server stops, returning immediately if not running. This method does not initiate stopping. It can be used when some other event is expected to stop the server.
        Parameters:
        timeout - how long to wait for the server to stop
        Returns:
        whether the server stopped before the timeout was reached or not
        Throws:
        InterruptedException - if the thread is interrupted before the timeout expires
        Since:
        1.10

      • reload

        RatpackServer reload()
              throws Exception
        Reloads the server from its definition function.

        The server definition will be rebuilt by executing the function used to create the server. Depending on the function's implementation, a different definition may result. This is effectively configuration reloading mechanism. 

        
 import ratpack.core.server.RatpackServer;
 import ratpack.test.ApplicationUnderTest;
 import static org.junit.jupiter.api.Assertions.*;

 public class Example {
   public static void main(String... args) throws Exception {
     String[] holder = new String[]{"foo"};

     RatpackServer server = RatpackServer.of(s -> s
       .serverConfig(ServerConfig.embedded())
       .registry(r -> r.add(String.class, holder[0]))
       .all(registry -> (ctx) -> ctx.render(ctx.get(String.class)))
     );

     ApplicationUnderTest.of(server).test(httpClient -> {
       assertEquals("foo", httpClient.getText());

       // change data read in definition function…
       holder[0] = "bar";

       // value unchanged…
       assertEquals("foo", httpClient.getText());

       // reload server…
       server.reload();

       // value has changed…
       assertEquals("bar", httpClient.getText());
     });
   }
 }

        If the server is running, it will be stopped and then started. If it is not running, the definition function will still be executed straight away and the new definition used next time the server is started.

        Returns:
        this
        Throws:
        Exception - any thrown from the definition function, stop() or start() methods.

      • getRegistry

        Optional<Registry> getRegistry()
        Convenience method to provide easy access to the application registry via a server reference.
        Returns:
        a Ratpack registry
        Since:
        1.6