Class Backend.Builder

java.lang.Object
com.codename1.backend.Backend.Builder
Enclosing class:
Backend
public static final class Backend.Builder extends Object
Collects what a server needs and starts one.

  • Method Details

    • handler

      public Backend.Builder handler(HttpServer.Handler handler)
      Adds a handler. They are tried in the order they were added and the first that answers wins, so the generated routers go in before any catch-all.

    • handlers

      public Backend.Builder handlers(Backend.Handlers factory)
      Adds handlers built once the database exists. See Backend.Handlers.

    • webSockets

      public Backend.Builder webSockets(Backend.WebSocketEndpoints endpoints)

      Registers this server's websocket endpoints when it starts.

      Called once, before the listener accepts anything, so there is no window in which a route exists in the application's mind and not in the server's -- which is what a websocket(path, endpoint) setter on a started server left open.

    • port

      public Backend.Builder port(int port)
      The port. Otherwise cn1.server.port, PORT, or 8080.

    • host

      public Backend.Builder host(String host)
      The address to bind, or null for every interface.

    • backlog

      public Backend.Builder backlog(int backlog)
      The listen backlog. Otherwise cn1.server.backlog, or 512.

    • workers

      public Backend.Builder workers(int workers)
      The size of the request thread pool. Otherwise cn1.server.workers, or 16.

    • shutdownTimeoutMillis

      public Backend.Builder shutdownTimeoutMillis(int millis)
      How long a stop waits for requests in flight.

    • tls

      public Backend.Builder tls(String certificatePath, String keyPath)

      Terminates TLS with this certificate and key.

      Drops a context given to the other overload earlier, because resolveTls answers from the context FIRST: without this, a builder configured conditionally kept serving the old certificate and this call did nothing at all -- silently, which is the part that matters, since an obsolete certificate looks like a working server until it expires. The last TLS choice wins, as it does for every other setter here.

      Only when something is actually supplied. tls(null, null) is not a way to turn a context off; it would make an argument nobody meant as a choice erase one that was.

    • tls

      public Backend.Builder tls(Tls tls)

      Terminates TLS with a context the caller built.

      Drops paths given to the other overload earlier, for the reason stated there, and on the same terms: a null context is not a choice and erases nothing.

    • staticFiles

      public Backend.Builder staticFiles(String root, String prefix, String indexFile, String cacheControl) throws IOException
      Serves a directory, after every handler, so a file cannot shadow a route.
      Throws:
      IOException

    • dataSource

      public Backend.Builder dataSource(String url)

      The database, as a SQLite path or a postgres:// or mysql:// URL.

      Drops a pool given to the other overload earlier: openDataSource answers from the pool FIRST, so without this a builder configured conditionally kept the earlier pool and this call was ignored -- which is a server reading and WRITING to the wrong database while its configuration says otherwise. The last choice wins.

      Ownership follows the same rule and stays correct either way: the builder opens this URL itself and therefore closes it, while a pool handed in belongs to the caller.

    • dataSource

      public Backend.Builder dataSource(DataSource dataSource)

      A pool the caller opened. It is closed when this server stops.

      Drops a URL given to the other overload earlier, for the reason stated there. A null pool is not a choice and erases nothing.

    • createTables

      public Backend.Builder createTables(boolean create)
      Whether to create the table of every generated entity at start-up. Otherwise cn1.orm.createTables, which defaults to true on a development profile and false everywhere else.

    • requiresDataSource

      public Backend.Builder requiresDataSource()

      Says that the handlers this server builds need a database, so one is opened even when nothing else asks for it.

      The generated entry point calls this when any controller declares a constructor taking a DataSource or an EntityManager. Without it, a controller that declares a database dependency, has no entities behind it, and runs on a development profile with no URL configured was refused at start-up by Backend.requireDataSource(DataSource, String) -- whose message suggests running on a development profile, which is what was already happening.

      The alternative was to open the development default whenever the profile allows it. That is the wrong fix: it would give a database to every server that has no use for one, which contradicts "a server with no database opens none" and costs a file handle to prove it. What was actually missing is that a DECLARED dependency did not drive the decision, and the build knows exactly which controllers declare one.

    • tracing

      public Backend.Builder tracing(Tracer tracer)
      Traces every request with this tracer, once Tracer.open(Config) has read the configuration and agreed to. The build calls this from the entry point it generates for a project that enables OpenTelemetry, which is why nothing else refers to a tracer implementation.

    • quiet

      public Backend.Builder quiet()
      Suppresses the line this prints when the server comes up.

    • start

      public Backend start() throws Exception
      Starts the server and returns, without installing a signal handler or waiting. Tests want this; a process wants run().
      Throws:
      Exception

    • run

      public void run() throws Exception
      Starts the server, drains it on SIGTERM or SIGINT, and blocks until it stops. This is what a main does.
      Throws:
      Exception