Backend API. Server-side code: this runs in a Codename One backend, not in the app on the device.

public final class Backend

Object
Backend

A configured, running server: the twenty lines every main used to open with, written once.

Backend.builder()
       .handler(new ApiRouter(new Api()))
       .run();

That reads the configuration, opens the database the deployment named, registers the generated daos, binds the port, installs a shutdown handler that drains what is in flight, and waits. Each of those was previously the developer’s to write and to get wrong – a main that returns ends the process without a word, because the host threads are detached, and a server with no signal handler loses every connection it was serving when the orchestrator stops it.

What comes from where

Anything the builder is TOLD is used as given. Anything it is not told, it reads from Config: the port, the worker count, TLS, static files and the database, in that layered order of system property, environment variable, profile file, base file. The rule is worth stating once because the opposite rule is also defensible: a value in the source wins over a value in the environment, so a port written here is the port, and a port that should follow the deployment is one nobody writes here.

The database is opened when there is one to open: a URL is configured, a pool was handed in, or the build generated at least one entity and the ORM therefore needs one. A server with no database opens none, which is what makes this the same entry point for both kinds.

# a laptop
CN1_PROFILE=dev ./server
# production
DATABASE_URL=postgres://app:[email protected]/app PORT=8080 ./server

Nested types

`interface Backend.Handlers`	Where the handlers are built, once the things they need exist.
`interface Backend.WebSocketEndpoints`	Where a server’s websocket endpoints come from.
`class Backend.Builder`

Methods

`public` `Tracer getTracer()`	The tracer this server installed, or null: its scheduled jobs are traced by it.
`public static` `Backend.Builder builder()`	A builder whose defaults come from the configuration this process sees.
`public static` `Backend.Builder builder(Config config)`	A builder over a configuration the caller already loaded or built.
`public` `String getListenAddress()`	The address a client on this machine reaches the listener at: the one it is bound to (bracketed when IPv6), or 127.0.0.1 when it listens on every interface.
`public` `HttpServer getServer()`	The running server, for its metrics or to stop it.
`public` `DataSource getDataSource()`	The connection pool, or null when this server has no database.
`public` `EntityManager getEntityManager()`	The entity manager, or null when this build generated no entities.
`public` `Config getConfig()`	The configuration this server resolved its settings from.
`public synchronized boolean isReady()`	Whether the server has finished starting and serves its application.
`public void awaitTermination()`	Blocks until the server stops.
`public void stop()`	Stops accepting, lets what is in flight finish, and closes the database.
`public synchronized boolean isStopped()`	Whether `stop` has finished: the beans are destroyed and the pool closed.
`public static` `DataSource requireDataSource(DataSource dataSource, String handler) throws IOException`	The pool, or a refusal naming the handler that asked for one.
`public static` `EntityManager requireEntities(EntityManager entities, String handler) throws IOException`	The entity manager, or a refusal naming the handler that asked for one.
`public static` `HttpServer.Request currentRequest()`	The request the calling thread is serving, or null outside one.

Inherited methods

From Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait, clone, finalize

Method details

getTracer

public Tracer getTracer()

The tracer this server installed, or null: its scheduled jobs are traced by it.

builder

public static Backend.Builder builder()

A builder whose defaults come from the configuration this process sees.

builder

public static Backend.Builder builder(Config config)

A builder over a configuration the caller already loaded or built.

getListenAddress

public String getListenAddress()

The address a client on this machine reaches the listener at: the one it is bound to (bracketed when IPv6), or 127.0.0.1 when it listens on every interface. A listener bound to one address answers on no other.

getServer

public HttpServer getServer()

The running server, for its metrics or to stop it.

getDataSource

public DataSource getDataSource()

The connection pool, or null when this server has no database.

getEntityManager

public EntityManager getEntityManager()

The entity manager, or null when this build generated no entities.

getConfig

public Config getConfig()

The configuration this server resolved its settings from.

isReady

public synchronized boolean isReady()

Whether the server has finished starting and serves its application.

awaitTermination

public void awaitTermination()

Blocks until the server stops.

stop

public void stop()

Stops accepting, lets what is in flight finish, and closes the database.

The order matters and is the reason this exists rather than two calls: closing the pool first would fail the requests that were still being served with it.

isStopped

public synchronized boolean isStopped()

Whether stop has finished: the beans are destroyed and the pool closed.

requireDataSource

public static DataSource requireDataSource(DataSource dataSource, String handler)
throws IOException

The pool, or a refusal naming the handler that asked for one.

Called from generated wiring: a controller declaring a DataSource constructor is declaring a DEPENDENCY, and handing it null because nothing configured a database turns that into a server that starts, reports healthy and fails on the first request that touches the database. The deployment is missing a setting, and start-up is where that is cheap to see.

Throws

IOException

requireEntities

public static EntityManager requireEntities(EntityManager entities, String handler)
throws IOException

The entity manager, or a refusal naming the handler that asked for one.

Throws

IOException

currentRequest

public static HttpServer.Request currentRequest()

The request the calling thread is serving, or null outside one. Maintained only for applications whose build asked for it: one with a request- or session-scoped bean reached from a singleton.