ratpack.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.server.RatpackServer;
 import ratpack.server.ServerConfig;

 import ratpack.test.ApplicationUnderTest;
 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()
     ApplicationUnderTest.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, of(Action)

Method Summary

Modifier and Type	Method and Description
String	getBindHost() The actual host/ip that the application is bound to.
int	getBindPort() The actual port that the application is bound to.
String	getScheme() The URL scheme the server uses.
boolean	isRunning() Returns true if the server is running.
static RatpackServer	of(Action<? super RatpackServerSpec> definition) Creates a new, unstarted, Ratpack server from the given definition.
RatpackServer	reload() Reloads the server from its definition function.
void	start() Starts the server, returning as soon as the server is up and ready to receive requests.
static void	start(Action<? super RatpackServerSpec> definition) Convenience method to define and start() the server in one go.
void	stop() Stops the server, returning as soon as the server has stopped receiving requests.

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

start

static void start(Action<? super RatpackServerSpec> definition)
           throws Exception

Convenience method to define and start() the server in one go.

Parameters:

definition - the server definition

Throws:

Exception - any thrown by of(Action) or start()

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

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.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]))
       .handler(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.