### Install Project Files with Maven Source: https://github.com/coveo/push-api-client.java/blob/main/README.md Build your Maven project to install the updated project files, including the Coveo dependency. ```bash mvn install ``` -------------------------------- ### Example: Using System Property for Global Batch Size Source: https://github.com/coveo/push-api-client.java/blob/main/CONFIGURATION.md Demonstrates setting the global batch size using a system property and then initializing services that will inherit this setting. This approach is suitable when a consistent batch size is desired across all services. ```java // Configure globally via system property System.setProperty("coveo.push.batchSize", "134217728"); // 128 MB // All services will use 128 MB by default UpdateStreamService updateService = new UpdateStreamService(catalogSource, backoffOptions); PushService pushService = new PushService(pushEnabledSource, backoffOptions); StreamService streamService = new StreamService(streamEnabledSource, backoffOptions); ``` -------------------------------- ### Install Local JAR File to Maven Repository Source: https://github.com/coveo/push-api-client.java/blob/main/README.md Manually install a JAR file to your local Maven repository using the `install:install-file` goal. This is useful when sharing a JAR without publishing it. ```bash mvn install:install-file \ -Dfile=push-api-client.java-.jar \ -DgroupId=com.coveo \ -DartifactId=push-api-client.java \ -Dversion= \ -Dpackaging=jar ``` -------------------------------- ### Install JAR to Local Maven Repository Source: https://github.com/coveo/push-api-client.java/blob/main/README.md Install the built JAR file to your local Maven repository, making it available for other local projects. ```bash mvn clean install -DskipTests ``` -------------------------------- ### Maven Installation for Push API Client Source: https://context7.com/coveo/push-api-client.java/llms.txt Configure Maven to use GitHub Packages and add the push-api-client.java dependency. Ensure your Maven settings.xml includes server credentials for GitHub Packages. ```xml github YOUR_GITHUB_USERNAME YOUR_GITHUB_PAT github https://maven.pkg.github.com/coveo/push-api-client.java com.coveo push-api-client.java 2.8.0 ``` -------------------------------- ### Example: Overriding Global Batch Size Per Service Source: https://github.com/coveo/push-api-client.java/blob/main/CONFIGURATION.md Illustrates setting a global batch size via system property and then overriding it for a specific service using its constructor. This is useful for scenarios where most services should use a default batch size, but one requires a different setting. ```java // Set global default to 128 MB System.setProperty("coveo.push.batchSize", "134217728"); // Update service uses global default (128 MB) UpdateStreamService updateService = new UpdateStreamService(catalogSource, backoffOptions); // Push service overrides with 64 MB PushService pushService = new PushService(pushEnabledSource, backoffOptions, 64 * 1024 * 1024); // Stream service uses global default (128 MB) StreamService streamService = new StreamService(streamEnabledSource, backoffOptions); ``` -------------------------------- ### Obtain GitHub Access Token Source: https://github.com/coveo/push-api-client.java/blob/main/README.md Use this command to obtain an access token from the GitHub API. Replace placeholders with your JWT token and releaser installation ID. ```bash curl -i -X POST \ -H "Authorization: Bearer " \ -H "Accept: application/vnd.github.v3+json" \ https://api.github.com/app/installations//access_tokens ``` -------------------------------- ### Build JAR from Source Source: https://github.com/coveo/push-api-client.java/blob/main/README.md Compile the push-api-client.java library from source using Maven, skipping tests for a faster build. ```bash mvn clean package -DskipTests ``` -------------------------------- ### Run Maven Test Suite Source: https://github.com/coveo/push-api-client.java/blob/main/README.md Execute the test suite for the push-api-client.java project using Maven. ```bash mvn test ``` -------------------------------- ### Configure Maven Server Authentication for GitHub Packages Source: https://github.com/coveo/push-api-client.java/blob/main/README.md Add your GitHub personal access token to your Maven settings.xml for authentication with GitHub Packages. ```xml github USERNAME TOKEN ``` -------------------------------- ### Apply Code Formatting with Maven Source: https://github.com/coveo/push-api-client.java/blob/main/README.md Use the spotless Maven plugin to automatically fix any code formatting issues according to the project's rules. ```bash mvn spotless:apply ``` -------------------------------- ### Check Code Formatting with Maven Source: https://github.com/coveo/push-api-client.java/blob/main/README.md Use the spotless Maven plugin to check if the code adheres to the project's formatting rules. ```bash mvn spotless:check ``` -------------------------------- ### Build Coveo Document with DocumentBuilder Source: https://context7.com/coveo/push-api-client.java/llms.txt Construct Coveo documents using a fluent builder pattern. Supports setting searchable content, dates, permanent IDs, clickable URIs, parent-child relationships, and custom metadata. Use dedicated methods for reserved keys like 'data' and 'permissions'. ```java import com.coveo.pushapiclient.*; import java.util.Map; DocumentBuilder doc = new DocumentBuilder("https://example.com/product/123", "Blue Widget Pro") // Searchable full-text content .withData("The Blue Widget Pro is a high-performance widget suitable for industrial use.") // Dates accept String (ISO 8601), Long (epoch ms), Date, or DateTime .withDate("2024-01-15T10:30:00Z") .withModifiedDate(System.currentTimeMillis()) // Custom permanent ID (auto-generated from URI hash if omitted) .withPermanentId("product-123-stable-id") // Clickable URL shown in search results .withClickableUri("https://shop.example.com/products/blue-widget-pro") .withAuthor("product-catalog-importer") .withFileExtension(".html") // Parent-child relationships .withParentID("https://example.com/products") // Arbitrary metadata (string, string[], int, int[]) .withMetadataValue("sku", "BWP-0042") .withMetadataValue("tags", new String[]{"widget", "industrial", "blue"}) .withMetadataValue("stock_count", 250) // Bulk metadata from a Map .withMetadata(Map.of( "department", "hardware", "weight_kg", 1 )); // Serialize to JSON string (used internally or for debugging) String json = doc.marshal(); System.out.println(json); ``` -------------------------------- ### Add Maven Repository for GitHub Packages Source: https://github.com/coveo/push-api-client.java/blob/main/README.md Configure your Maven settings.xml to include the GitHub Packages repository for the Coveo push-api-client.java. ```xml github https://maven.pkg.github.com/coveo/push-api-client.java true ``` -------------------------------- ### Configure Batch Size via Java Command Line Source: https://github.com/coveo/push-api-client.java/blob/main/CONFIGURATION.md Set the 'coveo.push.batchSize' system property to configure the default batch size globally for all service instances at runtime. This is useful for setting the batch size without modifying application code. ```bash java -Dcoveo.push.batchSize=134217728 -jar your-application.jar ``` -------------------------------- ### Clone Coveo Push API Client Repository Source: https://github.com/coveo/push-api-client.java/blob/main/README.md Clone the Java push-api-client repository from GitHub to build it from source. ```bash git clone https://github.com/coveo/push-api-client.java.git cd push-api-client.java ``` -------------------------------- ### Configure Batch Size within Java Code Source: https://github.com/coveo/push-api-client.java/blob/main/CONFIGURATION.md Set the 'coveo.push.batchSize' system property programmatically before creating any service instances. This allows for dynamic configuration within the application. ```java // Set before creating any service instances System.setProperty("coveo.push.batchSize", "134217728"); // 128 MB in bytes ``` -------------------------------- ### CatalogSource Instance Configuration Source: https://context7.com/coveo/push-api-client.java/llms.txt Configure CatalogSource instances for different environments (default US, EU) or directly from a Stream API URL. Use PlatformClient to create a new Catalog source in an organization. ```java import com.coveo.pushapiclient.*; // Default US production environment CatalogSource sourceDefault = CatalogSource.fromPlatformUrl( "my_api_key", "my_org_id", "my_source_id"); // EU production environment PlatformUrl euPlatformUrl = new PlatformUrlBuilder() .withEnvironment(Environment.PRODUCTION) .withRegion(Region.EU) .build(); CatalogSource sourceEU = CatalogSource.fromPlatformUrl( "my_api_key", "my_org_id", "my_source_id", euPlatformUrl); // From a Stream API URL directly import java.net.URL; CatalogSource sourceFromUrl = new CatalogSource( "my_api_key", new URL("https://api.cloud.coveo.com/push/v1/organizations/my-org-id/sources/my-source-id/stream/open") ); // Create a new Catalog source in the org (returns HTTP 201 with source JSON) PlatformClient client = new PlatformClient("my_api_key", "my_org_id"); var createResp = CatalogSource.create(client, "My Product Catalog", SourceVisibility.SECURED); System.out.println("Created source: " + createResp.body()); ``` -------------------------------- ### Configure Platform URL for Environment and Region Source: https://context7.com/coveo/push-api-client.java/llms.txt Specify the target Coveo deployment environment and region using PlatformUrlBuilder. The US production environment is the default. ```java import com.coveo.pushapiclient.*; // US production (default — no explicit configuration needed) PlatformUrl usProduction = new PlatformUrlBuilder().build(); // resolves to: https://api.cloud.coveo.com // EU production PlatformUrl euProduction = new PlatformUrlBuilder() .withEnvironment(Environment.PRODUCTION) .withRegion(Region.EU) .build(); // resolves to: https://api-eu.cloud.coveo.com // Hipaa environment PlatformUrl hipaa = new PlatformUrlBuilder() .withEnvironment(Environment.HIPAA) .withRegion(Region.US) .build(); // Apply to a PushSource PushSource source = PushSource.fromPlatformUrl( "my_api_key", "my_org_id", "my_source_id", euProduction); ``` -------------------------------- ### Logging Configuration Source: https://context7.com/coveo/push-api-client.java/llms.txt Configure Apache Log4j2 to capture SDK warnings and errors from `PushService`, `StreamService`, and `UpdateStreamService`. ```APIDOC ## Logging Configuration Configure Apache Log4j2 to capture SDK warnings and errors from `PushService`, `StreamService`, and `UpdateStreamService`. ```xml ``` ``` -------------------------------- ### Push a Single Document to Coveo Source: https://github.com/coveo/push-api-client.java/blob/main/README.md Demonstrates how to add or update a single document in Coveo using the Push API client. Ensure you have your API key and organization ID. ```java import com.coveo.pushapiclient.DocumentBuilder; import com.coveo.pushapiclient.Source; import java.io.IOException; import java.net.http.HttpResponse; public class PushOneDocument { public static void main(String[] args) { Source pushSource = new PushSource("my_api_key", "my_org_id"); DocumentBuilder documentBuilder = new DocumentBuilder("https://my.document.uri", "My document title") .withData("these words will be searchable"); try { HttpResponse response = pushSource.addOrUpdateDocument("my_source_id", documentBuilder); System.out.println(String.format("Source creation status: %s", response.statusCode())); System.out.println(String.format("Source creation response: %s", response.body())); } catch (IOException e) { e.printStackTrace(); } catch (InterruptedException e) { e.printStackTrace(); } } } ``` -------------------------------- ### Tag Commit for Release Source: https://github.com/coveo/push-api-client.java/blob/main/README.md Tag the commit according to semantic versioning principles and push the tags to the repository. Replace placeholders with the version and commit SHA. ```bash git tag -a vx.x.x -m "chore(main): release x.x.x (#)" git push --tags ``` -------------------------------- ### Batched Document Push with PushService Source: https://context7.com/coveo/push-api-client.java/llms.txt Use PushService to queue documents for automatic upload in batches. Configure custom backoff options and batch size. Ensure to call close() to flush remaining buffered documents. ```java import com.coveo.pushapiclient.*; public class BatchPushExample { public static void main(String[] args) throws Exception { PushSource pushSource = PushSource.fromPlatformUrl("my_api_key", "my_org_id", "my_source_id"); // Custom backoff + 64 MB batch size BackoffOptions backoff = new BackoffOptionsBuilder() .withMaxRetries(5) .withRetryAfter(3000) .withTimeMultiple(2) .build(); PushService service = new PushService(pushSource, backoff, 64 * 1024 * 1024); // Queue documents — auto-flushes when 64 MB threshold is crossed for (int i = 1; i <= 10000; i++) { DocumentBuilder doc = new DocumentBuilder( "https://example.com/article/" + i, "Article " + i ).withData("Content for article number " + i); service.addOrUpdate(doc); } // Mark a document for deletion in the same batch service.delete(new DeleteDocument("https://example.com/article/stale", true)); // Flush remaining buffered documents service.close(); System.out.println("Batch push complete."); } } ``` -------------------------------- ### Configure Log4j2 for Console Output Source: https://github.com/coveo/push-api-client.java/blob/main/README.md Set up Log4j2 to direct log messages to the console for monitoring push operations. This is useful when pushing multiple documents. ```xml ``` -------------------------------- ### Configure Batch Size for Push API Services Source: https://context7.com/coveo/push-api-client.java/llms.txt Configures the batch size for uploading documents. The SDK accumulates documents in memory before uploading in batches. Configuration priority: constructor parameter > system property > built-in default. ```java import com.coveo.pushapiclient.*; // Option 1: System property (affects all service instances) System.setProperty("coveo.push.batchSize", String.valueOf(128 * 1024 * 1024)); // 128 MB // Option 2: Per-service constructor parameter (overrides system property) CatalogSource source = CatalogSource.fromPlatformUrl("my_api_key", "my_org_id", "my_source_id"); BackoffOptions backoff = new BackoffOptionsBuilder().build(); PushService pushService = new PushService( PushSource.fromPlatformUrl("my_api_key", "my_org_id", "my_source_id"), backoff, 64 * 1024 * 1024 // 64 MB per batch ); StreamService streamService = new StreamService( source, backoff, null, 256 * 1024 * 1024 // 256 MB (maximum) ); UpdateStreamService updateStreamService = new UpdateStreamService( source, backoff, null, 32 * 1024 * 1024 // 32 MB ); // Option 3: JVM flag (e.g., in Maven surefire plugin) // java -Dcoveo.push.batchSize=134217728 -jar app.jar ``` -------------------------------- ### CatalogSource - Catalog Source Instance Source: https://context7.com/coveo/push-api-client.java/llms.txt The CatalogSource class represents a Catalog source instance within Coveo. It can be constructed using explicit IDs or from a Push/Stream API URL and supports both Stream API and Push API operations. ```APIDOC ## `CatalogSource` — Catalog Source Instance `CatalogSource` implements both `StreamEnabledSource` and `PushEnabledSource`. Use it when working with Stream API operations (`StreamService`, `UpdateStreamService`). Can be constructed from explicit IDs or from a Push/Stream API URL. ### Constructors and Factory Methods - **`CatalogSource.fromPlatformUrl(String apiKey, String organizationId, String sourceId)`**: Creates a CatalogSource for the default US production environment. - **`CatalogSource.fromPlatformUrl(String apiKey, String organizationId, String sourceId, PlatformUrl platformUrl)`**: Creates a CatalogSource for a specified platform URL (e.g., EU production). - **`CatalogSource(String apiKey, URL streamApiUrl)`**: Creates a CatalogSource directly from a Stream API URL. - **`CatalogSource.create(PlatformClient client, String sourceName, SourceVisibility visibility)`**: Creates a new Catalog source in the organization. ### Example Usage ```java import com.coveo.pushapiclient.*; // Default US production environment CatalogSource sourceDefault = CatalogSource.fromPlatformUrl( "my_api_key", "my_org_id", "my_source_id"); // EU production environment PlatformUrl euPlatformUrl = new PlatformUrlBuilder() .withEnvironment(Environment.PRODUCTION) .withRegion(Region.EU) .build(); CatalogSource sourceEU = CatalogSource.fromPlatformUrl( "my_api_key", "my_org_id", "my_source_id", euPlatformUrl); // From a Stream API URL directly import java.net.URL; CatalogSource sourceFromUrl = new CatalogSource( "my_api_key", new URL("https://api.cloud.coveo.com/push/v1/organizations/my-org-id/sources/my-source-id/stream/open") ); // Create a new Catalog source in the org (returns HTTP 201 with source JSON) PlatformClient client = new PlatformClient("my_api_key", "my_org_id"); var createResp = CatalogSource.create(client, "My Product Catalog", SourceVisibility.SECURED); System.out.println("Created source: " + createResp.body()); ``` ``` -------------------------------- ### Configure Logging for Push API Client Source: https://context7.com/coveo/push-api-client.java/llms.txt Configures Apache Log4j2 to capture SDK warnings and errors from PushService, StreamService, and UpdateStreamService. Set the logger level to 'debug' for the com.coveo.pushapiclient package. ```xml ``` -------------------------------- ### Batch Size Configuration Source: https://context7.com/coveo/push-api-client.java/llms.txt The SDK accumulates documents in memory before uploading in batches. The default batch threshold is 5 MB; the maximum is 256 MB. Configuration priority: constructor parameter > system property > built-in default. ```APIDOC ## Batch Size Configuration The SDK accumulates documents in memory before uploading in batches. The default batch threshold is **5 MB**; the maximum is **256 MB**. Configuration priority: constructor parameter > system property > built-in default. ```java import com.coveo.pushapiclient.*; // Option 1: System property (affects all service instances) System.setProperty("coveo.push.batchSize", String.valueOf(128 * 1024 * 1024)); // 128 MB // Option 2: Per-service constructor parameter (overrides system property) CatalogSource source = CatalogSource.fromPlatformUrl("my_api_key", "my_org_id", "my_source_id"); BackoffOptions backoff = new BackoffOptionsBuilder().build(); PushService pushService = new PushService( PushSource.fromPlatformUrl("my_api_key", "my_org_id", "my_source_id"), backoff, 64 * 1024 * 1024 // 64 MB per batch ); StreamService streamService = new StreamService( source, backoff, null, 256 * 1024 * 1024 // 256 MB (maximum) ); UpdateStreamService updateStreamService = new UpdateStreamService( source, backoff, null, 32 * 1024 * 1024 // 32 MB ); // Option 3: JVM flag (e.g., in Maven surefire plugin) // java -Dcoveo.push.batchSize=134217728 -jar app.jar ``` ``` -------------------------------- ### Add Coveo Push API Client Dependency to pom.xml Source: https://github.com/coveo/push-api-client.java/blob/main/README.md Include the Coveo push-api-client.java as a dependency in your Maven project's pom.xml file. Remember to replace the version with the latest or your desired version. ```xml com.coveo push-api-client.java 2.6.1 ``` -------------------------------- ### Full Catalog Rebuild with StreamService (Stream API) Source: https://context7.com/coveo/push-api-client.java/llms.txt Use StreamService for full source rebuilds, replacing all existing content upon close(). Ideal for initial catalog loads or complete re-indexing. Ensure to use CatalogSource. ```java import com.coveo.pushapiclient.*; import com.coveo.pushapiclient.exceptions.NoOpenStreamException; import java.util.HashMap; public class StreamRebuildExample { public static void main(String[] args) throws Exception { PlatformUrl platformUrl = new PlatformUrlBuilder() .withEnvironment(Environment.PRODUCTION) .withRegion(Region.US) .build(); CatalogSource catalogSource = CatalogSource.fromPlatformUrl( "my_api_key", "my_org_id", "my_source_id", platformUrl); // StreamService replaces ALL existing source content on close() StreamService streamService = new StreamService(catalogSource); DocumentBuilder doc1 = new DocumentBuilder("https://example.com/product/A", "Product A") .withData("Product A description") .withAuthor("catalog-bot") .withClickableUri("https://shop.example.com/product/A") .withFileExtension(".html") .withMetadata(new HashMap<>() { put("tags", new String[]{"featured", "sale"}); put("price_usd", 49); }); DocumentBuilder doc2 = new DocumentBuilder("https://example.com/product/B", "Product B") .withData("Product B description"); streamService.add(doc1); streamService.add(doc2); // Closes the stream and triggers indexing; old items not in this run are removed streamService.close(); System.out.println("Full stream rebuild complete. Expect ~15 min for old items to be removed."); } } ``` -------------------------------- ### Configure Batch Size in Maven Build Source: https://github.com/coveo/push-api-client.java/blob/main/CONFIGURATION.md Configure the 'coveo.push.batchSize' system property for Maven builds. This ensures the batch size is set correctly when running tests or building the application. ```xml -Dcoveo.push.batchSize=134217728 ``` -------------------------------- ### Add System Scope Dependency to pom.xml Source: https://github.com/coveo/push-api-client.java/blob/main/README.md Include the push-api-client.java JAR using a system scope in your pom.xml. This method is not recommended for production environments. ```xml com.coveo push-api-client.java system ${project.basedir}/lib/push-api-client.java-.jar ``` -------------------------------- ### Configure Batch Size in Gradle Build Source: https://github.com/coveo/push-api-client.java/blob/main/CONFIGURATION.md Configure the 'coveo.push.batchSize' system property for Gradle builds. This is useful for setting the batch size during test execution in a Gradle project. ```groovy // build.gradle test { systemProperty 'coveo.push.batchSize', '134217728' } ``` -------------------------------- ### Create Release Pull Request Source: https://github.com/coveo/push-api-client.java/blob/main/README.md Create a release pull request using the obtained access token. The `--dry-run` flag is recommended for initial testing. Specify the repository URL, release type, and target branch. ```bash release-please release-pr \ --token= \ --repo-url=coveo/push-api-client.java \ --release-type=maven \ --target-branch=main \ ``` -------------------------------- ### PlatformUrl / PlatformUrlBuilder — Environment & Region Source: https://context7.com/coveo/push-api-client.java/llms.txt Specifies the target Coveo deployment environment and region. Use `PlatformUrlBuilder` to fluently configure these settings before passing them to source constructors. ```APIDOC ## `PlatformUrl` / `PlatformUrlBuilder` — Environment & Region `PlatformUrl` specifies the target Coveo deployment environment and region. Use `PlatformUrlBuilder` to fluently configure the environment and region before passing it to source constructors. ```java import com.coveo.pushapiclient.*; // US production (default — no explicit configuration needed) PlatformUrl usProduction = new PlatformUrlBuilder().build(); // resolves to: https://api.cloud.coveo.com // EU production PlatformUrl euProduction = new PlatformUrlBuilder() .withEnvironment(Environment.PRODUCTION) .withRegion(Region.EU) .build(); // resolves to: https://api-eu.cloud.coveo.com // Hipaa environment PlatformUrl hipaa = new PlatformUrlBuilder() .withEnvironment(Environment.HIPAA) .withRegion(Region.US) .build(); // Apply to a PushSource PushSource source = PushSource.fromPlatformUrl( "my_api_key", "my_org_id", "my_source_id", euProduction); ``` ``` -------------------------------- ### Add Local JAR Dependency for Gradle Projects Source: https://github.com/coveo/push-api-client.java/blob/main/README.md For Gradle projects, place the JAR file in a 'libs/' folder and add the dependency using the `files()` method. ```groovy dependencies { implementation files('libs/push-api-client.java-.jar') } ``` -------------------------------- ### Configure Batch Size via StreamService Constructor Source: https://github.com/coveo/push-api-client.java/blob/main/CONFIGURATION.md Pass the 'maxQueueSize' parameter to the StreamService constructor to set a custom batch size for a specific service instance. This allows for fine-grained control over batching for streaming operations. ```java // StreamService with custom batch size StreamService streamService = new StreamService( streamEnabledSource, backoffOptions, null, // userAgents (optional) 128 * 1024 * 1024 // 128 MB ); ``` -------------------------------- ### Configure Batch Size via PushService Constructor Source: https://github.com/coveo/push-api-client.java/blob/main/CONFIGURATION.md Pass the 'maxQueueSize' parameter to the PushService constructor to set a custom batch size for a specific service instance. This is useful when different push operations require different batch sizes. ```java // PushService with custom batch size PushService pushService = new PushService( pushEnabledSource, backoffOptions, 128 * 1024 * 1024 // 128 MB ); ``` -------------------------------- ### Configure Exponential Backoff Retry Options Source: https://github.com/coveo/push-api-client.java/blob/main/README.md Customize retry behavior for throttled requests by configuring exponential backoff parameters. Defaults are 10 retries, 5-second wait, and a time multiple of 2. ```java PushSource pushSource = new PushSource("my_api_key", "my_org_id", new BackoffOptionsBuilder().withMaxRetries(5).withRetryAfter(10000).build()); PushService pushService = new PushService(myPushEnabledSource, new BackoffOptionsBuilder().withMaxRetries(10).build()); StreamService streamService = new StreamService(myStreamEnabledSource, new BackoffOptionsBuilder().withRetryAfter(2000).withTimeMultiple(3).build()); ``` -------------------------------- ### PushSource — Single-Document Push Source: https://context7.com/coveo/push-api-client.java/llms.txt The PushSource class allows for real-time addition, update, or deletion of individual documents. It can be initialized with API keys and source identifiers. ```APIDOC ## PushSource — Single-Document Push `PushSource` represents a Coveo Push source and provides methods to add, update, or delete individual documents in real time. It can be constructed from an API URL or from explicit organization/source IDs using `fromPlatformUrl()`. ```java import com.coveo.pushapiclient.*; import java.net.http.HttpResponse; public class PushOneDocument { public static void main(String[] args) throws Exception { // Construct from org/source IDs (default US production environment) PushSource source = PushSource.fromPlatformUrl("my_api_key", "my_org_id", "my_source_id"); // Build a document with metadata DocumentBuilder doc = new DocumentBuilder("https://example.com/page1", "Getting Started Guide") .withData("Full text content that will be indexed and searchable") .withAuthor("Alice Smith") .withClickableUri("https://example.com/page1") .withFileExtension(".html") .withDate("2024-06-01T00:00:00Z") .withMetadataValue("category", "onboarding") .withMetadataValue("version", 3); // Push the document HttpResponse response = source.addOrUpdateDocument(doc); System.out.println("Status: " + response.statusCode()); // 202 on success System.out.println("Body: " + response.body()); // Delete a document (and its children) HttpResponse deleteResp = source.deleteDocument("https://example.com/old-page", true); System.out.println("Delete status: " + deleteResp.statusCode()); } } ``` ``` -------------------------------- ### Push Single Document with PushSource Source: https://context7.com/coveo/push-api-client.java/llms.txt Use PushSource to add, update, or delete individual documents in real time. Construct the source from API key, organization ID, and source ID. The response status code 202 indicates success. ```java import com.coveo.pushapiclient.*; import java.net.http.HttpResponse; public class PushOneDocument { public static void main(String[] args) throws Exception { // Construct from org/source IDs (default US production environment) PushSource source = PushSource.fromPlatformUrl("my_api_key", "my_org_id", "my_source_id"); // Build a document with metadata DocumentBuilder doc = new DocumentBuilder("https://example.com/page1", "Getting Started Guide") .withData("Full text content that will be indexed and searchable") .withAuthor("Alice Smith") .withClickableUri("https://example.com/page1") .withFileExtension(".html") .withDate("2024-06-01T00:00:00Z") .withMetadataValue("category", "onboarding") .withMetadataValue("version", 3); // Push the document HttpResponse response = source.addOrUpdateDocument(doc); System.out.println("Status: " + response.statusCode()); // 202 on success System.out.println("Body: " + response.body()); // Delete a document (and its children) HttpResponse deleteResp = source.deleteDocument("https://example.com/old-page", true); System.out.println("Delete status: " + deleteResp.statusCode()); } } ``` -------------------------------- ### Manually Create Release Pull Request Source: https://github.com/coveo/push-api-client.java/blob/main/README.md If the automated pull request creation is incorrect, manually create one and perform an empty commit with specific commit messages to prompt `release-please` for the desired version. ```bash git commit --allow-empty -m "chore: release x.x.x" -m "Release-As: x.x.x" ``` -------------------------------- ### Configure Batch Size via UpdateStreamService Constructor Source: https://github.com/coveo/push-api-client.java/blob/main/CONFIGURATION.md Pass the 'maxQueueSize' parameter to the UpdateStreamService constructor to set a custom batch size for a specific service instance. This allows for per-instance configuration. ```java // UpdateStreamService with custom 128 MB batch size UpdateStreamService service = new UpdateStreamService( catalogSource, backoffOptions, null, // userAgents (optional) 128 * 1024 * 1024 // 128 MB in bytes ); ``` -------------------------------- ### Configure Backoff Options for Retries Source: https://context7.com/coveo/push-api-client.java/llms.txt Customize exponential backoff retry behavior for HTTP requests, especially for throttled responses (429). Defaults are retryAfter=5000ms, maxRetries=10, timeMultiple=2. ```java import com.coveo.pushapiclient.*; // Build custom backoff options BackoffOptions backoffOptions = new BackoffOptionsBuilder() .withRetryAfter(2000) // wait 2s after first throttled request .withMaxRetries(8) // retry up to 8 times .withTimeMultiple(3) // triple the wait time on each subsequent retry .build(); // Retry sequence: 2s, 6s, 18s, 54s, 162s, 486s, 1458s, 4374s // Apply to PushSource PushSource pushSource = PushSource.fromPlatformUrl( "my_api_key", "my_org_id", "my_source_id", new PlatformUrlBuilder().build(), backoffOptions); // Apply to StreamService CatalogSource catalog = CatalogSource.fromPlatformUrl("my_api_key", "my_org_id", "my_source_id"); StreamService streamService = new StreamService(catalog, backoffOptions); // Apply to UpdateStreamService UpdateStreamService updateService = new UpdateStreamService(catalog, backoffOptions); ``` -------------------------------- ### Source Status Management Source: https://context7.com/coveo/push-api-client.java/llms.txt Updates the operational status of a Push source. Status values control indexing behavior and should bracket bulk indexing operations (e.g., REBUILD before, IDLE after). ```APIDOC ## `PushSource.updateSourceStatus` — Source Status Management Updates the operational status of a Push source. Status values control indexing behavior and should bracket bulk indexing operations (e.g., `REBUILD` before, `IDLE` after). ```java import com.coveo.pushapiclient.*; import java.net.http.HttpResponse; public class SourceStatusExample { public static void main(String[] args) throws Exception { PushSource source = PushSource.fromPlatformUrl("my_api_key", "my_org_id", "my_source_id"); // Signal a rebuild is starting source.updateSourceStatus(PushAPIStatus.REBUILD); // ... push all documents ... DocumentBuilder doc = new DocumentBuilder("https://example.com/doc1", "Doc 1").withData("content"); source.addOrUpdateDocument(doc); // Signal the rebuild is done HttpResponse idleResp = source.updateSourceStatus(PushAPIStatus.IDLE); System.out.println("Source now IDLE, status: " + idleResp.statusCode()); } } ``` ``` -------------------------------- ### BackoffOptionsBuilder - Retry Configuration Source: https://context7.com/coveo/push-api-client.java/llms.txt Configures the exponential backoff retry behavior for HTTP requests. This is applied to requests that receive a 429 (throttled) response, with increasing wait times between retries. ```APIDOC ## `BackoffOptionsBuilder` — Retry Configuration `BackoffOptionsBuilder` configures the exponential backoff retry behavior applied to all HTTP requests. Requests that receive a `429` (throttled) response are retried with increasing wait times. Defaults: `retryAfter=5000ms`, `maxRetries=10`, `timeMultiple=2`. ```java import com.coveo.pushapiclient.*; // Build custom backoff options BackoffOptions backoffOptions = new BackoffOptionsBuilder() .withRetryAfter(2000) // wait 2s after first throttled request .withMaxRetries(8) // retry up to 8 times .withTimeMultiple(3) // triple the wait time on each subsequent retry .build(); // Retry sequence: 2s, 6s, 18s, 54s, 162s, 486s, 1458s, 4374s // Apply to PushSource PushSource pushSource = PushSource.fromPlatformUrl( "my_api_key", "my_org_id", "my_source_id", new PlatformUrlBuilder().build(), backoffOptions); // Apply to StreamService CatalogSource catalog = CatalogSource.fromPlatformUrl("my_api_key", "my_org_id", "my_source_id"); StreamService streamService = new StreamService(catalog, backoffOptions); // Apply to UpdateStreamService UpdateStreamService updateService = new UpdateStreamService(catalog, backoffOptions); ``` ``` -------------------------------- ### Manage Document Permissions with Security Identities Source: https://context7.com/coveo/push-api-client.java/llms.txt Control access to indexed items by defining allowed and denied users or groups using UserSecurityIdentityBuilder and GroupSecurityIdentityBuilder. These are applied to documents via withAllowedPermissions() and withDeniedPermissions(). ```java import com.coveo.pushapiclient.*; import java.net.http.HttpResponse; public class PermissionsExample { public static void main(String[] args) throws Exception { PushSource source = PushSource.fromPlatformUrl("my_api_key", "my_org_id", "my_source_id"); // Allow specific users (defaults to "Email Security Provider") UserSecurityIdentityBuilder allowedUsers = new UserSecurityIdentityBuilder( new String[]{"alice@example.com", "bob@example.com"} ); // Deny specific users UserSecurityIdentityBuilder deniedUsers = new UserSecurityIdentityBuilder( new String[]{"contractor@external.com"} ); // Allow a group (e.g., an Active Directory group) GroupSecurityIdentityBuilder allowedGroup = new GroupSecurityIdentityBuilder( "engineering-team", "Active Directory Security Provider" ); DocumentBuilder doc = new DocumentBuilder("https://intranet.example.com/internal/roadmap", "2025 Roadmap") .withData("Internal roadmap document — restricted access.") .withAllowAnonymousUsers(false) .withAllowedPermissions(allowedUsers) .withDeniedPermissions(deniedUsers); HttpResponse response = source.addOrUpdateDocument(doc); System.out.println("Push status: " + response.statusCode()); // Manage security identities on the source directly SecurityIdentityModel identityModel = new SecurityIdentityModel(); HttpResponse identityResp = source.createOrUpdateSecurityIdentity( "my_security_provider_id", identityModel); System.out.println("Identity update: " + identityResp.statusCode()); } } ``` -------------------------------- ### Document Permissions — UserSecurityIdentityBuilder / GroupSecurityIdentityBuilder Source: https://context7.com/coveo/push-api-client.java/llms.txt Controls who can see indexed items in search results. `UserSecurityIdentityBuilder` creates `USER`-type identities, and `GroupSecurityIdentityBuilder` creates `GROUP`-type identities. Both are used with `DocumentBuilder.withAllowedPermissions()` and `withDeniedPermissions()`. ```APIDOC ## Document Permissions — `UserSecurityIdentityBuilder` / `GroupSecurityIdentityBuilder` Permission models control who can see indexed items in search results. `UserSecurityIdentityBuilder` creates `USER`-type security identities, and `GroupSecurityIdentityBuilder` creates `GROUP`-type identities. Both are used with `DocumentBuilder.withAllowedPermissions()` and `withDeniedPermissions()`. ```java import com.coveo.pushapiclient.*; import java.net.http.HttpResponse; public class PermissionsExample { public static void main(String[] args) throws Exception { PushSource source = PushSource.fromPlatformUrl("my_api_key", "my_org_id", "my_source_id"); // Allow specific users (defaults to "Email Security Provider") UserSecurityIdentityBuilder allowedUsers = new UserSecurityIdentityBuilder( new String[]{"alice@example.com", "bob@example.com"} ); // Deny specific users UserSecurityIdentityBuilder deniedUsers = new UserSecurityIdentityBuilder( new String[]{"contractor@external.com"} ); // Allow a group (e.g., an Active Directory group) GroupSecurityIdentityBuilder allowedGroup = new GroupSecurityIdentityBuilder( "engineering-team", "Active Directory Security Provider" ); DocumentBuilder doc = new DocumentBuilder("https://intranet.example.com/internal/roadmap", "2025 Roadmap") .withData("Internal roadmap document — restricted access.") .withAllowAnonymousUsers(false) .withAllowedPermissions(allowedUsers) .withDeniedPermissions(deniedUsers); HttpResponse response = source.addOrUpdateDocument(doc); System.out.println("Push status: " + response.statusCode()); // Manage security identities on the source directly SecurityIdentityModel identityModel = new SecurityIdentityModel(); HttpResponse identityResp = source.createOrUpdateSecurityIdentity( "my_security_provider_id", identityModel); System.out.println("Identity update: " + identityResp.statusCode()); } } ``` ``` -------------------------------- ### Incremental Catalog Updates with UpdateStreamService Source: https://context7.com/coveo/push-api-client.java/llms.txt Use UpdateStreamService for incremental catalog updates, including adding/updating documents, deleting documents, and applying partial field-level updates. Ensure to call close() to flush all buffered operations. ```java import com.coveo.pushapiclient.*; import com.coveo.pushapiclient.exceptions.NoOpenFileContainerException; import java.util.HashMap; public class IncrementalUpdateExample { public static void main(String[] args) throws Exception { CatalogSource catalogSource = CatalogSource.fromPlatformUrl( "my_api_key", "my_org_id", "my_source_id"); UpdateStreamService updateService = new UpdateStreamService(catalogSource); // Add or update a full document DocumentBuilder newDoc = new DocumentBuilder("https://example.com/product/C", "Product C") .withData("New product added to catalog") .withMetadataValue("price_usd", 99); updateService.addOrUpdate(newDoc); // Delete a document (and its children) updateService.delete(new DeleteDocument("https://example.com/product/discontinued", true)); // Partial update: replace a single field value PartialUpdateDocument priceUpdate = new PartialUpdateDocument( "https://example.com/product/A", PartialUpdateOperator.FIELD_VALUE_REPLACE, "price_usd", 39 ); updateService.addPartialUpdate(priceUpdate); // Partial update: append values to an array field PartialUpdateDocument tagAppend = new PartialUpdateDocument( "https://example.com/product/A", PartialUpdateOperator.ARRAY_APPEND, "tags", new String[]{"clearance"} ); updateService.addPartialUpdate(tagAppend); // Partial update: put an entry into a dictionary field PartialUpdateDocument dictUpdate = new PartialUpdateDocument( "https://example.com/product/B", PartialUpdateOperator.DICTIONARY_PUT, "regionPricing", new HashMap<>() {{ put("EU", "45"); }} ); updateService.addPartialUpdate(dictUpdate); // Partial update: remove a key from a dictionary field PartialUpdateDocument dictRemove = new PartialUpdateDocument( "https://example.com/product/B", PartialUpdateOperator.DICIONARY_REMOVE, "regionPricing", "CA" ); updateService.addPartialUpdate(dictRemove); // Flush all buffered operations updateService.close(); System.out.println("Incremental update complete."); } } ``` -------------------------------- ### DocumentBuilder — Document Construction Source: https://context7.com/coveo/push-api-client.java/llms.txt DocumentBuilder provides a fluent interface for creating document objects, allowing for the specification of content, metadata, dates, permissions, and relationships. ```APIDOC ## DocumentBuilder — Document Construction `DocumentBuilder` is a fluent builder for constructing Coveo documents. It accepts a URI and title as required fields, and supports chained `with*()` calls for metadata, dates, permissions, compressed content, and more. Reserved key names such as `data`, `permissions`, and `parentId` must be set via their dedicated methods, not via `withMetadataValue`. ```java import com.coveo.pushapiclient.*; import java.util.Map; DocumentBuilder doc = new DocumentBuilder("https://example.com/product/123", "Blue Widget Pro") // Searchable full-text content .withData("The Blue Widget Pro is a high-performance widget suitable for industrial use.") // Dates accept String (ISO 8601), Long (epoch ms), Date, or DateTime .withDate("2024-01-15T10:30:00Z") .withModifiedDate(System.currentTimeMillis()) // Custom permanent ID (auto-generated from URI hash if omitted) .withPermanentId("product-123-stable-id") // Clickable URL shown in search results .withClickableUri("https://shop.example.com/products/blue-widget-pro") .withAuthor("product-catalog-importer") .withFileExtension(".html") // Parent-child relationships .withParentID("https://example.com/products") // Arbitrary metadata (string, string[], int, int[]) .withMetadataValue("sku", "BWP-0042") .withMetadataValue("tags", new String[]{"widget", "industrial", "blue"}) .withMetadataValue("stock_count", 250) // Bulk metadata from a Map .withMetadata(Map.of( "department", "hardware", "weight_kg", 1 )); // Serialize to JSON string (used internally or for debugging) String json = doc.marshal(); System.out.println(json); ``` ```