Skip to main content

Getting started

This page shows how to add the jEAP OpenSearch client starter to a Spring Boot service and execute authorization-aware searches against OpenSearch indices. For the full API see SearchItemClient and for configuration see the Configuration reference.

1. Add the dependency​

<dependency>
    <groupId>ch.admin.bit.jeap</groupId>
    <artifactId>jeap-opensearch-client-starter</artifactId>
</dependency>

The version is managed by the jEAP Spring Boot parent. The starter auto-configures an OpenSearchClient and a SearchItemClient.

2. Configure the connection​

Add the OpenSearch cluster URI to application.yml. For AWS OpenSearch Service also set the signing region:

jeap:
  opensearch:
    client:
      connection:
        uri: https://my-domain.eu-central-2.es.amazonaws.com
        aws-signing-region: eu-central-2   # omit for non-AWS deployments

See the Configuration reference for all available properties.

3. Add IndexType dependencies​

Add a dependency for every index type you want to search. Index type artifacts are generated by the jeap-opensearch-index-type-registry-maven-plugin:

<dependency>
    <groupId>ch.admin.bit.jme.indextype.jme</groupId>
    <artifactId>jme-decree-document-v1</artifactId>
    <version>1.2.0</version>
</dependency>

Inject SearchItemClient and call searchMultiVersionWithUserAuth to search with the current user's authorization:

@Service
@RequiredArgsConstructor
class DecreeDocumentSearchService {

    private final SearchItemClient searchItemClient;

    List<SearchItemView> findByDecreeId(String decreeId) {
        Query query = Query.of(q -> q
            .term(t -> t.field("data.document_id").value(decreeId)));

        return searchItemClient.searchMultiVersionWithUserAuth(
            List.of(JmeDecreeDocumentIndexTypeV1.INSTANCE),
            query
        );
    }
}

The returned SearchItemView exposes a type-safe view of each result:

for (SearchItemView view : results) {
    JmeDecreeDocumentDataV1 data = view.dataAs(JmeDecreeDocumentDataV1.class);
    Origin origin = view.origin();
}

When multiple major versions of an index type exist simultaneously, pass all versions to search across them in one query. Deserialization is dispatched per document by search_item.major_version:

List<SearchItemView> results = searchItemClient.searchMultiVersionWithUserAuth(
    List.of(
        JmeDecreeDocumentIndexTypeV1.INSTANCE,
        JmeDecreeDocumentIndexTypeV2.INSTANCE
    ),
    query
);