Jetty - FWD - Golden Code Redmine

Being a long-term Eclipse Foundation project Jetty is a Java web server and Java Servlet container providing support for Java Servlet API, HTTP/1.1, HTTP/2, Web Socket and FastCGI. Additionally it provides support for OSGi, JMX, JNDI, JAAS and others.

Golden Code chose Jetty as the HTTP backend as it is easily full-featured and standard based, flexible and extensible, asynchronous, enterprise scalable and has small footprint.

FWD uses Jetty in version 9.4.

Integration¶

Jetty is embedded in the FWD server process. FWD server is fully responsible for its life time. It is initialized and started during FWD server bootstrap and shut down during FWD server tear down. FWD uses the Jetty API.

The main Jetty API class is org.eclipse.jetty.server.Server. It aggregates a thread pool of HTTP request receivers and request handlers. The incoming HTTP requests are dispatched with the receivers and eventually passed to one or more registered handlers. For better illustration see a simple example of an embedded Jetty in a Java process.

public class HelloWorld
extends AbstractHandler
{
    @Override
    public void handle(String target,
                       Request baseRequest,
                       HttpServletRequest request,
                       HttpServletResponse response)
    throws IOException,
           ServletException
    {
        // Declare response encoding and types
        response.setContentType("text/html; charset=utf-8");

        // Declare response status code
        response.setStatus(HttpServletResponse.SC_OK);

        // Write back response
        response.getWriter().println("<h1>Hello World</h1>");

        // Inform Jetty that this request has now been handled
        baseRequest.setHandled(true);
    }

    public static void main(String[] args) 
    throws Exception
    {
        Server server = new Server(8080);
        server.setHandler(new HelloWorld());
        server.start();
        server.join();
    }
}

FWD integrates Jetty in a similar way. It initializes a set of handlers and passes them to a created Server instance.

Handlers are the main integration point in the Jetty API. They implement the "business logic" for every particular request. A handler class is any class implementing the interface org.eclipse.jetty.server.Handler. There are many ready made Jetty API classes implementing various types of handlers. From the simplest ones providing the basic request needs (org.eclipse.jetty.server.handler.AbstractHandler) to the more complex ones like org.eclipse.jetty.server.handler.ContextHandler for handling only a particular subset of the request paths or org.eclipse.jetty.webapp.WebAppContext used to programmatically create a full-featured Java web application. For all the Jetty API details please refer to the Jetty documentation.

Endpoints¶

There are several built-in services exposed by the embedded Jetty instance. These implement some of the 4GL services to support the converted native applications and also extend the capabilities of the converted applications. FWD also allows deploying any compliant Java web application.

Built-in services¶

Name	Context (base URL path)	Handler Class	Description
Admin	/admin	see below	FWD administration UI.
Web UI (ChUI)	/chui	`com.goldencode.p2j.main.WebHandler`	The login page for the character based user interface (FWD client).
Web UI (GUI)	/gui	`com.goldencode.p2j.main.WebHandler`	The login page for the graphic based user interface (FWD client).
Embedded Web GUI	/embedded	`com.goldencode.p2j.main.EmbeddedPageHandler`	The login page for FWD client running in embedded mode.
REST	/rest	`com.goldencode.p2j.rest.RestHandler`	Processes the REST requests and delegates the calls to the mapped service.
SOAP	/ws	`com.goldencode.p2j.soap.SoapHandler`	Processes SOAP service requests and delegate the calls to the mapped service.
Web Service	/web	`com.goldencode.p2j.main.WebServiceHandler`	Processes the HTTP requests and delegates them to the mapped WebHandler legacy classes.

All the built-in services run on the same port number configured in the directory in the hive adminPort.

Custom web application¶

Any Java compliant web application packaged in a web archive (war file) can be deployed in FWD. Every such application runs in its own Jetty server instance with a unique port number.

To deploy a war to FWD follow the steps below.

1. Create a Server hook Java class
2. Add the Server hook entry in the directory
3. Add the required Java web application configuration parameters in the directory

Server hooks allow to execute code during FWD startup or termination. It is responsible with registering the web application with FWD runtime.

The hook may be as simple as:

public class MyAppHook
implements InitTermListener
{
   private GenericWebServer server;

   @Override
   public void initialize()
   {
      server = GenericWebServer.initializeWebApp("MyApp", "myapp.war", "MyAppThread");
   }

   @Override
   public void terminate(Throwable t)
   {
      try
      {
         server.shutdown();
      }
      catch (Exception e)
      {
         e.printStackTrace();
      }
   }
}

The actual registration of the web application with FWD happens in GenericWebServer.initializeWebApp. The method reads the needed configuration parameters from the directory, creates a Jetty server instance and starts it in a new thread. The method takes three arguments web application name, default war file name and Jetty thread name. Web application name is used as the root hive in the directory to read the additional parameters, the passed in thread name value will be set as the name for the thread starting the created Jetty instance.

Directory parameters:

Name	Type	Mandatory	Default value	Description
port	integer	yes	n/a	The port the server will listen on the incoming HTTP requests.
securePort	integer	yes	n/a	The port the server will listen on the incoming HTTPS requests. Use 0 to disable HTTPS for the application.
host	string	no	null	The network interface the Jetty's connector will bind to as an IP address or a hostname. If 0.0.0.0, then it will bind to all interfaces.
basepath	string	no	"/"	The base path (or also known as context) for all the incoming HTTP/HTTPS requests.
warfile	string	no	<war file name passed to `initializeWebApp`>	The web application web archive.
keyStore	string	yes	n/a	Java key store file name with the HTTPS server certificate. This parameter is required only if securePort > 0.
storePassword	string	yes	n/a	The password to decrypt the key store file. This parameter is required only if securePort > 0.
entryPassword	string	yes	n/a	The password to decrypt the private key stored in the key store. This parameter is required only if securePort > 0.

The actual directory hive is in the form "<Web app name>WebApp/<parameter name>" where <Web app name> is the name passed in initializeWebApp and <parameter name> is the name from the table above.

Configuration¶

There are several parameters exposed in the server directory altering the embedded Jetty instance behavior.

Name	Type	Default Value	Description
adminPort	integer	9443	The port number Jetty will listen on for the incoming HTTPS requests of all the build-in services.
maxOutputBufferSize	integer	1048576	The size in bytes of the output buffer used to aggregate HTTP output.
maxOutputAggregationSize	integer	8192	The maximum size in bytes for HTTP output to be aggregated.
maxIdleTimeout	integer	-1	The idle timeout in ms for I/O operations during the handling of an HTTP request. -1 is interpreted as an infinite timeout.
maxResponseHeaderSize	integer	8192	The maximum allowed size in bytes for an HTTP response header.
maxRequestHeaderSize	integer	8192	The maximum allowed size in bytes for an HTTP request header.

Security¶

All the endpoints by default use HTTPS protocol (HTTP over SSL) or can be configured to use HTTPS. FWD supports Conscrypt, Bouncy Castle or the default SSL provider bundled with the Java runtime environment in use.

On top of the channel security protocol all the endpoints integrate with the standard security mechanism provided by FWD server.

The authentication mechanism, which integrates with FWD server security, is implemented in LegacyServiceHandler. Any handler extending this class will also benefit from its security features. These include com.goldencode.p2j.rest.RestHandler, com.goldencode.p2j.soap.SoapHandler and com.goldencode.p2j.main.WebServiceHandler.

If authentication is enabled for the particular handler in server directory (see below the list of security related directory parameters) LegacyServiceHandler will authenticate all the requests in its handle method. It passes the request to one of the subclasses of com.goldencode.p2j.main.WebServiceAuth. Each subclass implements a single authentication mechanism. Currently only BasicAuth is implemented where the client of the service must pass the authentication credentials. BasicAuth uses the credentials and passes them to SecurityManager.authWebRequest. authWebRequest checks the credentials and if it finds a match it considers the request authenticated (the caller successfully identified). In the second step BasicAuth does an authorization of the request by the call to SecurityManager.createWebRequestContext. createWebRequestContext will create an access token, a corresponding security context and will return the access token to BasicAuth. BasicAuth will
check whether the target request is authorized with a call to WebServiceResource and if the authorization is successful stores the access token in the response header. Subsequent requests having this access token will succeed.

Security related directory parameters¶

Hive	Type	Default Value	Description
<type>/authentication/enabled	boolean	false	When set to true enables authentication on the service.
<type>/authentication/type	string	"basic"	Allows to change the type of authentication. Currently only "basic" is supported.
<type>/authentication/timeout	integer	0	Session security context timeout in seconds. After the timeout expires the access token used by the clients of the service and the related security context will no longer be valid. If set to 0 the context will be expired only after an explicit logout.
<type>/authentication/login_path	string	null	The login path recognized by `BasicAuth` class. Request with this path will authenticate the request.
<type>/authentication/logout_path	string	"/fwdlogout"	Invalidates the access token established during authorization and the related security context.

<type> in the table above can be interpreted as the handler type. It is one of "rest", "soap" and "WebHandler" for RestHandler, SoapHandler and WebServiceHandler classes respectively.

Project

General

Profile

FWD

Wiki