Skip to main content

Getting started

This page shows how to implement an IndexType and register it as a Spring bean so it is picked up by the jEAP OpenSearch infrastructure. For an overview of all types in this library see Domain model.

1. Add the dependency​

<dependency>
    <groupId>ch.admin.bit.jeap</groupId>
    <artifactId>jeap-opensearch-index-type</artifactId>
</dependency>

The version is managed by the jEAP Spring Boot parent.

Note: In practice, IndexType implementations are generated by the jeap-opensearch-index-type-registry-maven-plugin and published as individual Maven artifacts. You only implement IndexType manually in the registry project itself or in tests.

2. Define the data class​

The data class is a Java record whose fields correspond to the data.properties section of the OpenSearch mapping. Field names must be snake_case — annotate each field with @JsonProperty("snake_case_name") to ensure correct serialisation:

public record MyDocumentData(
    @JsonProperty("document_id")   String documentId,
    @JsonProperty("document_title") String documentTitle,
    @JsonProperty("created_at")    Instant createdAt
) {}

3. Implement IndexType​

Implement IndexType<T> and register it as a Spring bean:

@Component
public class MyDocumentIndexTypeV1 implements IndexType<MyDocumentData> {

    public static final MyDocumentIndexTypeV1 INSTANCE = new MyDocumentIndexTypeV1();

    @Override public String system()           { return "MySystem"; }
    @Override public String originType()       { return "MyDocument"; }
    @Override public int    majorVersion()     { return 1; }
    @Override public int    minorVersion()     { return 0; }
    @Override public List<String> roles()      { return List.of("mysystem_read"); }
    @Override public String indexWriteAlias()  { return "mysystem_my_document_v1_write"; }
    @Override public String indexReadAlias()   { return "mysystem_my_document_read"; }
    @Override public Class<MyDocumentData> dataClass() { return MyDocumentData.class; }
    @Override public Supplier<InputStream> mappingDefinition() {
        return () -> getClass().getResourceAsStream("/opensearch/MyDocument_mapping_v1_0.json");
    }
}

4. Provide the mapping file​

Place the OpenSearch mapping JSON on the classpath under opensearch/. The mapping must include search_item, origin, and data sections:

{
  "mappings": {
    "dynamic": false,
    "_meta": { "schema_version": 0 },
    "properties": {
      "search_item": {
        "type": "object",
        "properties": {
          "upserted_at":   { "type": "date", "format": "strict_date_optional_time||epoch_millis" },
          "major_version": { "type": "integer" },
          "minor_version": { "type": "integer" }
        }
      },
      "origin": {
        "type": "object",
        "properties": {
          "id":       { "type": "keyword" },
          "version":  { "type": "keyword" },
          "bp_id":    { "type": "keyword" },
          "created":  { "type": "date", "format": "strict_date_optional_time||epoch_millis" },
          "modified": { "type": "date", "format": "strict_date_optional_time||epoch_millis" },
          "reference": { "type": "object", "enabled": false }
        }
      },
      "data": {
        "type": "object",
        "properties": {
          "document_id":    { "type": "keyword" },
          "document_title": { "type": "text" },
          "created_at":     { "type": "date", "format": "strict_date_optional_time||epoch_millis" }
        }
      }
    }
  }
}

5. Register as ServiceLoader service​

For IndexType.loadAll() to discover the implementation, add a ServiceLoader registration:

# src/main/resources/META-INF/services/ch.admin.bit.jeap.opensearch.indextype.IndexType
com.example.MyDocumentIndexTypeV1

The registry Maven plugin generates this file automatically for all plugin-generated types.