Server - Planes

Swim developer logo developer.

Overview


A SWIM Plane manages the runtime and provides a shared context for a group of SWIM Services. A Plane's runtime responsibilities include, but are not limited to,

  • Resolving Service and Lane URIs for requests.
  • Maintaining application configurations, including
    • http/https protocol parameters
    • Port bindings
    • TLS parameters
    • Storage directory for lane data
  • Starting and stopping the Swim server.

Instantiation


Instantiating a Plane requires just a few steps.

  1. The Plane object must extend swim.api.AbstractPlane.
  2. For every Service type, declare a ServiceType instance in the Plane, instantiated using this.serviceClass.YourService.class and annotated with @SwimRoute($nodeUri). nodeUri is a String that defines the URI pattern (with colons `:` preceding dynamic components) that identifies instances of this Service.
  3. Identify all desired Plane configuration properties that should be loaded into the application. Refer to the next section on how to configure a Plane.

Configuration


There are two ways to pass configuration properties to a Plane.

Inline

This is the method of choice when there are only a few properties to override. Refer to this example

From a configuration file

All the configuration properties can be specified in a file, the file should be in Recon format. This is the method of choice when you wish to control several aspects. The example here illustrates how to read a .recon file and parse it into a ServerDef class and how the ServerDef is materialized into the SwimServer. A sample .recon configuration is outlined below, it can also be found here.

@server { @plane("plane-name") { class: "ai.swim.App" } @store { # path where the lane data is stored path: "/tmp/swim-join/" } # Specify ports to bind to @http(port:9002) { plane: "plane-name" } # Configuration for TLS #@https(port: 443) { #plane: "plane-name" #@tls(protocol: "TLS") { #clientAuth: none # none | want | need #cipherSuites: {"", ""} # array of JCE cipher suite strings #protocols: # array of JCE crypto protocols #@keyStore(type: "JKS") { #path: "" # file path #resource: "" # -or- classpath resource #password: "" # keystore password #} #@trustStore(type: "JKS") { #path: "" # file path #resource: "" # -or- classpath resource #password: "" # keystore password #} #} #} }
  • HTML
  • recon

Start Server


The main method of a SWIM Plane instance must do the following:

  1. Declare a SwimServer; let's call it server.
  2. Materialize the SwimServer with the desired configurations, including the Plane.
  3. Invoke server.run()
The main() method is inherently tied to the Plane, so to minimize switching among files, we have placed it inside the Plane class in many of our examples.