Module jakarta.ws.rs
Package jakarta.ws.rs

Interface SeBootstrap

public interface SeBootstrap
Bootstrap class used to startup a JAX-RS application in Java SE environments.

The SeBootstrap class is available in a Jakarta EE container environment as well; however, support for the Java SE bootstrapping APIs is not required in container environments.

In a Java SE environment an application is getting started by the following command using default configuration values (i. e. mounting application at http://localhost:80/ or a different port (there is no particular default port mandated by this specification). As the JAX-RS implementation is free to choose any port by default, the caller will not know the actual port unless explicitly checking the actual configuration of the instance started: 

 Application app = new MyApplication();
 SeBootstrap.Configuration config = SeBootstrap.Configuration.builder().build();
 SeBootstrap.start(app, config).thenAccept(instance -> instance.configuration().port());

Running instances can be instructed to stop serving the application: 

 SeBootstrap.start(app, config).thenAccept(instance -> { ... instance.stop(); } );

A shutdown callback can be registered which will get invoked once the implementation stops serving the application: 

 instance.stop().thenAccept(stopResult -> ...));
stopResult is not further defined but solely acts as a wrapper around a native result provided by the particular JAX-RS implementation. Portable applications should not assume any particular data type or value.

Protocol, host address, port and root path can be overridden explicitly. As the JAX-RS implementation is bound to that values, no querying of the actual configuration is needed in that case: 

 SeBootstrap.Configuration.builder().protocol("HTTPS").host("0.0.0.0").port(8443).rootPath("api").build();

TLS can be configured by explicitly passing a customized SSLContext: 

 SSLContext tls = SSLContext.getInstance("TLSv1.2");
 // ...further initialize context here (see JSSE API)...
 SeBootstrap.Configuration.builder().protocol("HTTPS").sslContext(tls).build();

In case of HTTPS, client authentication can be enforced to ensure that only trustworthy clients can connect: 

 SeBootstrap.Configuration.builder().protocol("HTTPS").sslClientAuthentication(SSLClientAuthentication.MANDATORY).build();

Implementations are free to support more use cases by native properties, which effectively render the application non-portable: 

 SeBootstrap.Configuration.builder().property("productname.foo", "bar").build()

Bulk-loading allows to attach configuration storages easily without the need to write down all properties to be transferred. Hence, even properties unknown to the application author will get channeled into the implementation. This can be done both, explicitly (hence portable) and implicitly (hence not necessarily portable as no particular configuration mechanics are required to be supported by compliant implementations): 

 // Explicit use of particular configuration mechanics is portable
 SeBootstrap.Configuration.builder().from((name, type) -> externalConfigurationSystem.getValue(name, type)).build();

 // Implicitly relying on the support of particular configuration mechanics by
 // the actual JAX-RS implementation is not necessarily portable
 SeBootstrap.Configuration.builder().from(externalConfigurationSystem).build();
Since:
3.1
Author:
Markus KARG (markus@headcrashing.eu)

  • Method Details

    • start

      static CompletionStage<SeBootstrap.Instance> start(Application application, SeBootstrap.Configuration configuration)
      Starts the provided application using the specified configuration.

      This method is intended to be used in Java SE environments only. The outcome of invocations in Jakarta EE container environments is undefined.

      Parameters:
      application - The application to start up.
      configuration - Provides information needed for bootstrapping the application.
      Returns:
      CompletionStage (possibly asynchronously) producing handle of the running application instance.
      Since:
      3.1
      See Also:

    • start

      static CompletionStage<SeBootstrap.Instance> start(Application application)
      Starts the provided application using a default configuration.

      This method is intended to be used in Java SE environments only. The outcome of invocations in Jakarta EE container environments is undefined.

      Parameters:
      application - The application to start up.
      Returns:
      CompletionStage (possibly asynchronously) producing handle of the running application instance.
      Since:
      3.1
      See Also:

    • start

      static CompletionStage<SeBootstrap.Instance> start(Class<? extends Application> clazz, SeBootstrap.Configuration configuration)
      Starts the provided application using the specified configuration. Creates application instance from class using default constructor. Injection is not supported.

      This method is intended to be used in Java SE environments only. The outcome of invocations in Jakarta EE container environments is undefined.

      Parameters:
      clazz - The application class.
      configuration - Provides information needed for bootstrapping the application.
      Returns:
      CompletionStage (possibly asynchronously) producing handle of the running application instance.
      Since:
      3.1
      See Also:

    • start

      static CompletionStage<SeBootstrap.Instance> start(Class<? extends Application> clazz)
      Starts the provided application using a default configuration. Creates application instance from class using default constructor. Injection is not supported.

      This method is intended to be used in Java SE environments only. The outcome of invocations in Jakarta EE container environments is undefined.

      Parameters:
      clazz - The application class.
      Returns:
      CompletionStage (possibly asynchronously) producing handle of the running application instance.
      Since:
      3.1
      See Also: