# searchSDK for Java

Java 17+. 14 normalized web-search adapters and 493 retained native bindings across 13 providers; gateway client.

Canonical: https://searchsdk.dev/docs/sdks/java
Markdown: https://searchsdk.dev/docs/sdks/java.md

<a id="install"></a>

## Install from source

Package: `dev.belweave:search-sdk`, version `0.1.0-alpha.0`. This is an alpha source/local-artifact installation. No public registry release or release tag is assumed.

**Get the source**

```bash
git clone https://github.com/Belweave/searchSDK.git
cd searchSDK
# Record this revision with your application's dependency lock.
git rev-parse HEAD
```

**Build or install the local package**

```bash
mvn -T 2 -f packages/java/pom.xml install

# Add this dependency to your application's pom.xml:
# groupId: dev.belweave
# artifactId: search-sdk
# version: 0.1.0-alpha.0
```

Maven install writes to your local Maven repository. It does not publish to Maven Central. The JAR's automatic module is dev.searchsdk, and it has no runtime dependencies. Use Maven 3.9+ and JDK 17+.

<a id="first-search"></a>

## Make a server-side search

Set provider keys in your application's server environment or secret store. The example below makes a real provider request when invoked and can incur charges. Use the package's fixture consumer for a key-free check.

**SearchExample.java**

```java
import dev.searchsdk.*;
import java.time.Duration;

public class SearchExample {
    public static void main(String[] args) {
        var search = SearchClient.builder(
            Providers.exa(System.getenv("EXA_API_KEY")))
            .timeout(Duration.ofSeconds(10))
            .build();
        var response = search.search(new SearchRequest(
            "SQLite write concurrency", 3
        )).toCompletableFuture().join();
        for (var result : response.results()) {
            System.out.println(result.url());
        }
    }
}
```

Add the local Maven dependency, set EXA_API_KEY in the server environment and run this class with that dependency on the classpath. The service API returns CompletionStage.

<a id="scope"></a>

## Supported surface and limits

14 normalized web-search adapters and 493 retained native bindings across 13 providers; gateway client.

- Compressed HTTP responses are rejected by this alpha transport.
- Native wire models do not enforce every JSON Schema constraint or establish provider account entitlement.

Preserve result order, provider-native scores and source provenance. Unknown usage is not zero cost. Cancellation and deadlines cannot undo a request already accepted by a remote system or guarantee exactly-once effects.

<a id="verify"></a>

## Verify without provider keys

**Repository checkout · local checks**

```bash
bash packages/java/scripts/verify.sh
bash packages/java/scripts/verify-maven.sh
```

JDK 17, 21, 25 and 27; packed classpath/module consumers and a separate Maven consumer.

These are deterministic contract and artifact checks. They do not establish live-provider or account-entitlement verification. Read the package README for precise commands, dependencies and runtime coverage.

<a id="next"></a>

## Continue in your language

- [Java package reference](https://github.com/Belweave/searchSDK/tree/main/packages/java#readme): Complete API, errors, streaming, packaging and platform boundaries.
- [Compare SDKs](https://searchsdk.dev/docs/sdks)
- [Choose a provider](https://searchsdk.dev/docs/providers)