Container
A Pedestal application always works in the context of a container such as Jetty 12; the container is responsible for the low-level HTTP/HTTPs networking, including support for Websockets and server-sent events.
Once a request has been received, it is passed through the Servlet Interceptor to be processed using the Interceptors pipeline.
Embedded
Pedestal applications are primarily run in embedded mode, where the container is a library that is part of the runtime classpath.
When the Pedestal service is started, the container is initialized and started; the container will receive incoming requests and pass those along to Pedestal for actual processing.
The service map is used to configure what kinds of container to use, along with all the details of how the container is to be initialized.
Container Type
The ::type key of the service map determined the container [1]; it may be either a simple keyword, or a function (the container function). Its default value is :jetty.
When ::type is a keyword, it is used to locate the container function as io.pedestal.http.<type>/server;
the namespace will be loaded as needed.
Container Contract
The container function is passed the full service map, and the options map.
The options map is a modified version of the service map; the keys have had their namespace removed [2], and only a limited number of keys are present:
-
:host
-
:port (may be nil to disable HTTP)
-
:join? (optional, default true)
-
:websockets (optional)
-
:container-options (optional)
:host and :port will always be provided; the others are optional (only if included in the service map).
:host will default to "localhost", which is acceptible for local development, but not likely the best value for a deployed service.
The service function must create the necessary underlying objects based on the provided options; the :container-options key will have container-specific values.
The service function returns a lifecycle map, with two callback functions: - :start-fn - :stop-fn
The :start-fn will be called to start the container; if the :join? option was true (this is the default if not specified)
then the start-fn callback should not return until the container is shut down.
The stop-fn callback should stop the container, in an orderly manner.
Where possible, the container should be restartable after being stopped.
WAR (Web Application Archive)
The alternate setup for a Pedestal application is a WAR file - a packaged version of an application, its code and libraries, configuration, and public resources - that runs inside a standalone servlet container.
In WAR mode, a pre-build Pedestal servlet is configured (in the web.xml configuration file) and it takes care of
starting the Pedestal application when the WAR is deployed into the servlet container.
This all requires some careful setup, including omitting certain dependencies from the classpath.
| More discussion of WAR deployment is forthcoming. |