Structure of Helidion Modules

module-structure.md

This is a proposal for structuring Helidon modules. It is based on options in Tomas' gist Options for API module naming -- this aligns with Option 1 in that document (with the small change of spi elevated up one level).

This presents multiple use cases, from simple single module components to multi-module components. This document uses tracing in the examples for all use cases.

Use Case 1: Single Module: All-in-one

In the simplest case there is one module and the API and implementation are in the same module.

There are not multiple implementations, and no good reason for splitting out the implementation.

Module Name	Group ID	Artifact ID	Java Package
helidon-tracing	io.helidon.tracing	helidon-tracing	io.helidon.tracing

        <dependency>
            <groupId>io.helidon.tracing</groupId>
            <artifactId>helidon-tracing</artifactId>
        </dependency>

Use Case 2: Multi Module: Single Seperate Implementation

In this case we want to split the implementation into a seperate module because we have a use case for API only. But practically speaking there is just one implementation. By convention we use the name runtime for this implementation.

Module Name	Group ID	Artifact ID	Java Package
helidon-tracing-api	io.helidon.tracing	helidon-tracing-api	io.helidon.tracing.api, io.helidon.tracing.spi
helidon-tracing-runtime	io.helidon.tracing	helidon-tracing-runtime	io.helidon.tracing.runtime

        <dependency>
            <groupId>io.helidon.tracing</groupId>
            <artifactId>helidon-tracing-api</artifactId>
        </dependency>
        <dependency>
            <groupId>io.helidon.tracing</groupId>
            <artifactId>helidon-tracing-runtime</artifactId>
            <scope>runtime</scope>
        </dependency>

Use Case 3: Multi Module: Multiple Implementations

Like the previous case, but we have multiple implementations. In this case the implementation modules would use names that have some domain specific natural meaning.

Module Name	Group ID	Artifact ID	Java Package
helidon-tracing-api	io.helidon.tracing	helidon-tracing-api	io.helidon.tracing.api, io.helidon.tracing.spi
helidon-tracing-zipkin	io.helidon.tracing	helidon-tracing-zipkin	io.helidon.tracing.zipkin
helidon-tracing-opentelemetry	io.helidon.tracing	helidon-tracing-opentelemetry	io.helidon.tracing.opentelemetry
helidon-tracing-<domainspecific>	io.helidon.tracing	helidon-tracing-<domainspecific>	io.helidon.tracing.<domainspecific>

        <dependency>
            <groupId>io.helidon.tracing</groupId>
            <artifactId>helidon-tracing-api</artifactId>
        </dependency>
        <dependency>
            <groupId>io.helidon.tracing</groupId>
            <artifactId>helidon-tracing-opentelemetry</artifactId>
            <scope>runtime</scope>
        </dependency>

Tomáš likes this!