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.server.RatpackServer;
     import ratpack.server.ServerConfig;
    
     import ratpack.test.ServerBackedApplicationUnderTest;
     import static org.junit.Assert.*;
    
     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 java.lang.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:
        java.lang.Exception - any thrown by creating the server
        See Also:
        RatpackServerSpec
      • start

        static RatpackServer start​(Action<? super RatpackServerSpec> definition)
                            throws java.lang.Exception
        Convenience method to define and start() the server in one go.
        Parameters:
        definition - the server definition
        Returns:
        the newly created and started server
        Throws:
        java.lang.Exception - any thrown by of(Action) or start()
      • getScheme

        java.lang.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
        java.lang.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 java.lang.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:
        java.lang.Exception - if the server could not be started
      • stop

        void stop()
           throws java.lang.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:
        java.lang.Exception - if the server could not be stopped cleanly
      • reload

        RatpackServer reload()
                      throws java.lang.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.server.RatpackServer;
         import ratpack.test.ApplicationUnderTest;
         import static org.junit.Assert.*;
        
         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:
        java.lang.Exception - any thrown from the definition function, stop() or start() methods.
      • getRegistry

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