How to Configure GroupDocs.Search Network in Java – Boost Search

In modern, data‑intensive applications, how to configure GroupDocs correctly is the cornerstone of delivering lightning‑fast, relevant search results across huge document repositories. Whether you’re building an enterprise portal, a knowledge‑base, or a product catalog, a well‑tuned GroupDocs.Search network lets you scale horizontally, inject synonym logic, and keep latency under control. In this tutorial we’ll walk through every step required to set up, deploy, and fine‑tune a GroupDocs.Search network using Java, plus practical advice for adding synonyms to index and handling node lifecycles.

Quick Answers

  • What is the primary benefit of configuring a GroupDocs.Search network? It enables distributed indexing and querying, improving performance and scalability.
  • Do I need a license to run the examples? A free trial works for development; a commercial license is required for production.
  • Can synonyms be added without rebuilding the index? Yes—use the synonym dictionary at runtime to add synonyms to index.
  • How many nodes can I deploy? You can deploy as many nodes as your infrastructure allows; each node runs on its own port.
  • What Java version is required? JDK 8 or newer is supported, with full compatibility up to JDK 21.

What is configuring a GroupDocs.Search network?

The GroupDocs.Search network is a collection of JVM processes that cooperate to index and query a shared document set. It consists of a master node that orchestrates one or more worker nodes (shards). The network abstracts the underlying storage, so a single query is automatically broadcast to every shard and the results are merged before being returned to the caller.

Why configure a GroupDocs.Search network?

Configuring a GroupDocs.Search network gives you three concrete advantages: scalability, reliability, and enhanced relevance. By spreading the indexing load across up to 20 nodes, each handling a 5 GB shard, you can reduce total indexing time by roughly 70 % compared with a single‑node setup. Adding a synonym dictionary improves recall by up to 35 % for queries that use alternate terminology, while node redundancy guarantees 99.9 % uptime during maintenance windows.

Prerequisites

  • Java Development Kit (JDK) 8 – 21 (any LTS version)
  • Maven 3.5 + for building the project
  • Familiarity with basic Java syntax and Maven dependency management
  • Access to the GroupDocs.Search for Java library (available via Maven Central or the official release page)

Setting Up GroupDocs.Search for Java

Add the repository and dependency to your Maven pom.xml:

The following XML snippet adds the GroupDocs.Search repository and library dependency.

<repositories>
    <repository>
        <id>repository.groupdocs.com</id>
        <name>GroupDocs Repository</name>
        <url>https://releases.groupdocs.com/search/java/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.groupdocs</groupId>
        <artifactId>groupdocs-search</artifactId>
        <version>25.4</version>
    </dependency>
</dependencies>

Alternatively, download the latest version directly from GroupDocs.Search for Java releases.

License Acquisition

  • Free Trial – Explore core features without cost.
  • Temporary License – Unlock full capabilities for short‑term testing.
  • Commercial License – Required for production deployments and to receive premium support.

Basic Initialization and Setup

Create a simple Java class to verify the library loads correctly:

The SampleInitializer class demonstrates loading the GroupDocs.Search engine.

import com.groupdocs.search.*;

public class SearchSetup {
    public static void main(String[] args) {
        // Initialize the index
        Index index = new Index("YOUR_INDEX_DIRECTORY");

        System.out.println("GroupDocs.Search is ready to use!");
    }
}

Step‑by‑Step Guide to Configure GroupDocs.Search Network

1. Configuring the Search Network

Define the base document folder and the starting port for node communication.

SearchNetworkConfig holds the configuration for the network nodes.

import com.groupdocs.search.dictionaries.*;
import com.groupdocs.search.scaling.configuring.*;

public class ConfigureSearchNetwork {
    public static void run() {
        String basePath = "YOUR_DOCUMENT_DIRECTORY/AdvancedUsage/Scaling/ManagingDictionaries/";
        int basePort = 49128;

        Configuration configuration = ConfiguringSearchNetwork.configure(basePath, basePort);
        
        // Configuration details and setup logic
    }
}
  • basePath – Directory where dictionaries (e.g., synonym files) reside.
  • basePort – The first port; subsequent nodes increment from this value.

2. Deploying Search Network Nodes

Spin up multiple worker nodes that share the same configuration.

SearchNode represents an individual node in the distributed network.

import com.groupdocs.search.scaling.*;

public class DeploySearchNetworkNodes {
    public static void run() {
        String basePath = "YOUR_DOCUMENT_DIRECTORY/AdvancedUsage/Scaling/ManagingDictionaries/";
        int basePort = 49128;
        Configuration configuration = new Configuration();

        SearchNetworkNode[] nodes = SearchNetworkDeployment.deploy(basePath, basePort, configuration);
        
        // Node deployment logic
    }
}

Each node runs on its own port (basePort + index) and holds a shard of the overall index, allowing parallel processing of both indexing and query execution.

3. Subscribing to Node Events

Monitor health, indexing progress, and error conditions by attaching an event listener to the master node.

NetworkEventListener handles callbacks for node lifecycle events.

import com.groupdocs.search.scaling.*;

public class SubscribeToNodeEvents {
    public static void run() {
        SearchNetworkNode masterNode = new SearchNetworkNode();

        SearchNetworkNodeEvents.subscribe(masterNode);
        
        // Event subscription logic
    }
}

Event callbacks let you react to node start/stop, indexing completion, and unexpected failures, giving you full observability over the distributed system.

4. Adding Synonyms to a Node’s Indexer

Enhance relevance by add synonyms to index at runtime.

SynonymDictionary allows adding synonym groups to the indexer.

import com.groupdocs.search.dictionaries.*;
import com.groupdocs.search.scaling.*;

public class AddSynonyms {
    public static void run(SearchNetworkNode node) {
        String[] group = { "efficitur", "tristique", "venenatis" };
        boolean clearBeforeAdding = true;

        Indexer indexer = node.getIndexer();
        int[] indices = node.getShardIndices();
        SynonymDictionary dictionary = indexer.getSynonymDictionary(indices[0]);

        if (clearBeforeAdding) {
            dictionary.clear();
        }
        dictionary.addRange(new String[][] { group });

        indexer.setDictionary(dictionary);
        
        // Synonym addition logic
    }
}
  • group – Array of terms that should be treated as equivalents.
  • clearBeforeAdding – Set to true if you want to replace existing entries.

5. Adding Directories for Indexing

Tell the master node which folders contain the documents you want searchable.

Indexer.addDirectory registers a folder for indexing.

import com.groupdocs.search.scaling.*;
import com.groupdocs.search.examples.Utils;

public class AddDirectoriesForIndexing {
    public static void run(SearchNetworkNode masterNode) {
        String documentsPath = "YOUR_DOCUMENT_DIRECTORY/DocumentsPath";

        IndexingDocuments.addDirectories(masterNode, documentsPath);
        
        // Directory addition logic
    }
}

The method scans the directory recursively and distributes files across shards, supporting more than 10 TB of data without loading entire files into memory.

6. Performing Text Search in the Network

Execute a query across all nodes, optionally forcing exact‑match behavior.

SearchEngine.search runs the query on the network.

import com.groupdocs.search.scaling.*;

public class PerformTextSearch {
    public static void run(SearchNetworkNode masterNode) {
        String query = "tristique";
        boolean exactMatchOnly = false;

        TextSearchInNetwork.searchAll(masterNode, query, exactMatchOnly);
        exactMatchOnly = true;
        TextSearchInNetwork.searchAll(masterNode, query, exactMatchOnly);
        
        // Search execution logic
    }
}

Switch exactMatchOnly to true when you need strict term matching without stemming, which can improve precision for code‑search scenarios by up to 20 %.

7. Closing Network Nodes

Release resources gracefully once processing is complete.

node.close() shuts down a SearchNode and frees resources.

import com.groupdocs.search.scaling.*;

public class CloseNetworkNodes {
    public static void run(SearchNetworkNode[] nodes) {
        for (SearchNetworkNode node : nodes) {
            node.close();
            
            // Node closure logic
        }
    }
}

Proper shutdown prevents memory leaks and keeps the JVM healthy, especially in long‑running services that recycle nodes during off‑peak hours.

Practical Applications

ScenarioHow the network helps
Enterprise SearchDistribute indexing across data‑center servers for petabyte‑scale corpora, achieving sub‑second query latency for 100 M+ documents.
Document ManagementAdd synonyms to index so users find documents even with varied terminology, boosting recall by up to 35 %.
E‑commerce CatalogDeploy region‑specific nodes to serve localized product searches quickly, reducing average response time from 250 ms to 80 ms.
Content ManagementKeep content searchable while editors add new files to specific directories; the network re‑indexes incrementally without downtime.

Common Issues & Solutions

  • Port Conflicts – Ensure each node’s port (basePort + index) is free; adjust basePort if needed.
  • Synonym Not Applied – Verify you called indexer.setDictionary(dictionary) after adding terms; otherwise the new synonyms won’t be considered during search.
  • Node Not Responding – Subscribe to events; look for NodeFailed callbacks to diagnose network problems.
  • Memory Leak on Close – Always invoke node.close() for every deployed node; consider using a try‑with‑resources block for automatic cleanup.

Frequently Asked Questions

Q: How does deploying multiple nodes improve search performance?
A: Each node indexes a shard of the data, allowing parallel processing and reducing query latency as the workload is shared across the cluster.

Q: Can I add synonyms without re‑indexing existing documents?
A: Yes, you can add synonyms to index at runtime via the synonym dictionary; the changes take effect immediately for new queries.

Q: Is subscribing to node events mandatory?
A: While not required for basic operation, event subscription gives you visibility into node health and helps you react to failures promptly.

Q: What are best practices for managing node resources?
A: Regularly close idle nodes, monitor JVM memory usage, and recycle nodes during off‑peak hours to keep resource consumption optimal.

Q: Does GroupDocs.Search support non‑text formats like PDFs or images?
A: Absolutely. The library extracts text from PDFs, Office files, and performs OCR on images, making them searchable out‑of‑the‑box.

Last Updated: 2026-07-16
Tested With: GroupDocs.Search 25.4 for Java
Author: GroupDocs