Helidon Examples

Examples.md

Common rules

• Define logging.properties set to INFO and standard output, with a few examples of configuring relevant modules for finer logging (one or two)
• Use application parent and define the copy-libs execution (except for examples showing standalone project approach)
• Use only junit-jupiter-api for assertions (e.g. do not use hamcrest in examples)
• Define a README.md that describes
  • how to build
  • how to run
  • how to validate (using curl)
• Use a test configuration profile that overrides
  • server.host to localhost - to listen on localhost explicitly
  • server.port to 0 - to use a random listen port
• Examples should use a single package

SE Examples

• Use configuration to load any used component (WebServer, WebClient, Security etc.)
  • There should be a small number (probably just one) of examples that show the builder approach for some reasonably complex application
• Use LogConfig.configureRuntime() to set up logging
• Do not use SE bundle modules (these should be removed in the future)
• Define a main class (and validate the example can be executed using java -jar)
• Use WebClient to test endpoints
• Use services for implementing the example "business functionallity"
• The following section should be used by all SE examples that use WebServer (unless they are dedicated to customize on of these):

    /**
     * Application main entry point.
     * @param args command line arguments.
     */
    public static void main(final String[] args) {
        startServer();
    }
    
    /**
     * Start the server.
     * @return the created and started {@link WebServer} instance
     */
    static WebServer startServer() {

        // load logging configuration
        LogConfig.configureRuntime();

        // By default this will pick up application.yaml from the classpath
        Config config = Config.create();

        // Get webserver config from the "server" section of application.yaml and register JSON support
        WebServer server = WebServer.builder(createRouting(config))
                .config(config.get("server"))
                .addMediaSupport(JsonpSupport.create()) // if needed
                .build()
                .start()
                .await(Duration.ofSeconds(10));

        // this section can be used to print available endpoints
        System.out.println("Example available at http://localhost:" + server.port() + "/example");

        return server;
   }

MP Examples

• Do not use SE components (SE Config, reactive routing)
• Do not use a main class, except for cases where we need to setup custom configuration (such as examples connecting to clouds)
• Do not use an Application class (except for JWT-Auth)
• Only use microprofile-config.properties except for security examples (where application.yaml is better)
• Use helidon-microprofile dependency, unless the example shows customized dependencies based on core or cdi
• Use JAX-RS client to test endpoints