# pequenino

`software.visionary.piggies:pequenino:2026.10.13` · https://codeberg.org/piggies/pequenino

Visionary Software Solutions Rooter @Pequenino registration annotations: the user-facing (service, implementation) annotations, split out so adopters can depend on just the annotations without the processor.

<code>@Pequenino</code> is the user-facing registration annotation for the piggies service-provider-registry mechanism — a single <code>(service, implementation)</code> pair, placed on a <code>module-info</code> or <code>package-info</code>, that the <code>human</code> processor picks up at compile time.

## Rationale

**Why.** Bloch's Service Provider Framework (Effective Java, Item 1) needs a registry per service. The piggies mechanism collapses them into one annotation (<code>@Pequenino</code>), one provider processor (<code>human</code>), and one aggregation processor (<code>rooter</code>). This module carries only the annotations, so a module that declares registrations depends on <code>pequenino</code> alone, without the processor.

Both annotations carry <code>@Retention(RUNTIME)</code>, yet a processor consumes them during compilation, so a module wearing them runs without this one on its path.

The <code>human</code> processor reads each <code>@Pequenino</code> and writes one <code>service\timplementation</code> line to <code>META-INF/rooter/registrations</code> in the provider's jar. The <code>rooter</code> processor later reads every such resource across the processor classpath (via <code>getResources</code>) and generates one <code>&lt;Service&gt;MotherTree</code> per service: an <code>enum</code> implementing <code>Registry&lt;Class&lt;? extends S&gt;, Supplier&lt;? extends S&gt;&gt;</code> and <code>Iterable&lt;Supplier&lt;? extends S&gt;&gt;</code>.

The wire-format types (<code>Registrations</code>, <code>Registration</code>, <code>RegistrationSerializationStrategy</code>) live in <code>registrations</code>.

Place <code>@Pequenino</code> on a <code>module-info</code> (module-wide) or a <code>package-info</code> (package-wide). The annotation is <code>@Repeatable</code>, not an array: each <code>@Pequenino</code> names exactly one pair, keeping every registration self-contained and independently readable.

This module contains no processor logic, so declaring a registration costs no processor closure. <code>human</code> validates registrations at build time; misconfiguration fails the build rather than surfacing at runtime.

## Key Concepts

### Pequenino

**Role.** Registers an <code>implementation()</code> of a <code>service()</code> into that service's generated MotherTree registry: names one <code>(service, implementation)</code> pair. <code>@Repeatable</code>, so multiple registrations can stack on one target.

**Pattern.** Annotation

### Pequeninos

**Role.** The <code>@Repeatable</code> container; authored implicitly by the compiler when more than one <code>@Pequenino</code> appears.

**Pattern.** Container annotation

## Lane

**Purpose.** Declaring a service implementation on a module or package, for a compile-time registry to be generated from.

**Alternative.** A <code>provides ... with</code> clause in <code>module-info</code>, when <code>java.util.ServiceLoader</code> finding providers at run time is enough.

## Usage

Usage

```java
// module-info.java — compile-only; the annotation is not needed at runtime
requires static software.visionary.piggies.pequenino;
```

Placement: several registrations stack on one module

```java
// provider-module/src/main/java/module-info.java
@Pequenino(service = Codec.class, implementation = Json.class)
@Pequenino(service = Codec.class, implementation = Yaml.class)
module example.codecs {
    requires static software.visionary.piggies.pequenino;
}
```

## Caveats

- The <code>implementation</code> must be a concrete class with a public no-arg constructor, a class singleton reached through a public static <code>INSTANCE</code> or <code>getInstance()</code>, or an enum singleton. The <code>human</code> processor validates this at build time and fails the build loudly for anything else.