Skip to content

devops-thiago/elastikjay

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

20 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

ElastiKJay

ElastiKJay is a Java library that provides annotation-based object mapping and simplified interaction with Elasticsearch. It allows developers to easily map Java POJOs to Elasticsearch indices using annotations, similar to how JPA works with relational databases.

Features

  • Annotation-driven mapping: Use simple annotations to define how your Java objects map to Elasticsearch indices
  • Simplified CRUD operations: Easy-to-use API for creating, reading, updating, and deleting documents
  • Bulk operations: High-performance bulk insert and update operations
  • Index management: Create, delete, and manage Elasticsearch indices programmatically
  • Flexible configuration: Support for both single-node and cluster configurations
  • Type safety: Strongly-typed operations with automatic serialization/deserialization

Getting Started

Prerequisites

  • Java 17 or later
  • Maven 3.6+
  • Elasticsearch 1.2.1+ (compatible)

Installation

Add ElastiKJay to your Maven project:

<dependency>
    <groupId>com.arquivolivre</groupId>
    <artifactId>elastikjay</artifactId>
    <version>1.2.1-SNAPSHOT</version>
</dependency>

Usage Examples

1. Defining Elasticsearch Mappings with Annotations

Use annotations to define how your Java classes map to Elasticsearch:

import com.arquivolivre.elastikjay.annotations.*;

@Index(name = "products", type = "product")
public class Product {
    
    private String id;
    
    @Analyzer("standard")
    private String name;
    
    @NotAnalyzed
    private String category;
    
    @NotIndexed
    private String internalNotes;
    
    private double price;
    
    @Nested
    private List<Review> reviews;
    
    // Getters and setters...
}

public class Review {
    private String author;
    private int rating;
    private String comment;
    
    // Getters and setters...
}

2. Configuring Elasticsearch Connection

Create a properties file es.properties in your resources:

# Single node configuration
elasticsearch.node=localhost
elasticsearch.port=9300

# Or cluster configuration
elasticsearch.cluster.name=my-cluster
elasticsearch.cluster.nodes=node1,node2,node3
elasticsearch.cluster.ports=9300,9301,9302

3. Basic CRUD Operations

import com.arquivolivre.elastikjay.commons.IndexManager;
import com.arquivolivre.elastikjay.commons.IndexManagerImpl;
import com.arquivolivre.elastikjay.config.Configuration;

// Initialize the IndexManager
Configuration config = new Configuration();
IndexManager indexManager = new IndexManagerImpl(config.elasticSearchClient());

// Create an index for your class
Product sampleProduct = new Product();
indexManager.createIndex("products", "product", sampleProduct);

// Insert a document
Product product = new Product();
product.setId("1");
product.setName("Laptop Computer");
product.setCategory("electronics");
product.setPrice(999.99);

indexManager.addToBulk("1", product);
indexManager.executeBulkAdd();

// Retrieve a document
Product retrievedProduct = indexManager.get("1", Product.class);
System.out.println("Product: " + retrievedProduct.getName());

// Check if index exists
boolean exists = indexManager.indexExists("products");

4. Bulk Operations for Performance

// Bulk insert multiple documents
List<Product> products = Arrays.asList(
    new Product("1", "Laptop", "electronics", 999.99),
    new Product("2", "Mouse", "electronics", 29.99),
    new Product("3", "Keyboard", "electronics", 79.99)
);

for (Product product : products) {
    indexManager.addToBulk(product.getId(), product);
}

// Execute all bulk operations at once
indexManager.executeBulkAdd();

5. Index Management

// Create index with custom settings
indexManager.createIndex("products", "product", new Product());

// Delete an index
indexManager.deleteIndex("products");

// Delete multiple indices
indexManager.deleteIndices("products", "orders", "customers");

// Check if index exists
if (!indexManager.indexExists("products")) {
    indexManager.createIndex("products", "product", new Product());
}

Available Annotations

Annotation Description
@Index Defines the Elasticsearch index name and type for a class
@Analyzer Specifies the analyzer to use for text analysis
@NotAnalyzed Marks a field as not analyzed (exact match only)
@NotIndexed Excludes a field from being indexed
@Ignored Completely ignores a field during mapping
@Nested Defines nested object mapping for complex types
@Analysis Configures analysis settings for the field
@Filter Applies filters during analysis

Configuration Options

ElastiKJay supports flexible configuration through properties:

Single Node Setup

elasticsearch.node=localhost
elasticsearch.port=9300

Cluster Setup

elasticsearch.cluster.name=production-cluster
elasticsearch.cluster.nodes=es-node1,es-node2,es-node3
elasticsearch.cluster.ports=9300,9300,9300

Building and Development

Build Commands

# Clean and compile
mvn clean compile

# Run tests
mvn test

# Full build with verification
mvn clean verify

# Run code quality checks
mvn spotbugs:check checkstyle:check

# Generate test coverage report
mvn test
# Report available at: core/target/site/jacoco/index.html

Code Quality Tools

This project uses several tools to maintain code quality:

  • SpotBugs: Static analysis for bug detection
  • Checkstyle: Code style enforcement (Google Java Style)
  • JaCoCo: Test coverage reporting

Dependencies

  • Java: 17 (upgraded from 1.7)
  • Elasticsearch: 1.2.1
  • Log4j: 2.20.0 (security update)
  • Gson: 2.10.1
  • JUnit: 4.13.2

License

This project is licensed under the terms specified in the LICENSE file.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Run tests and code quality checks
  5. Submit a pull request

Author

Thiago da Silva Gonzaga thiagosg@sjrp.unesp.br

About

A developer friendly framework for Elasticsearch Java API

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors

Languages