Searchable JPA

Searchable JPA is a library that extends Spring Data JPA to provide dynamic search, sorting, and pagination functionality. It allows complex search conditions to be implemented using simple annotations and builder patterns, and supports high-performance cursor-based pagination even for large datasets.

Version Compatibility

Version-Specific Spring Boot Support

Library Version	Spring Boot Version	Jakarta EE	Status
0.1.x	2.7.x	javax.*	Deprecated
1.0.0+	3.2.x+	jakarta.*	Latest

Important: Version Compatibility Notice

• 1.0.0+ versions: Only supports Spring Boot 3.2.x+ (Jakarta EE 9+)
• 0.1.x versions: Only supports Spring Boot 2.7.x (uses javax.* packages)
• No mixing with lower versions: Using different versions simultaneously may cause classpath conflicts

Spring Boot 2.x → 3.x Migration

When upgrading to Spring Boot 3.x, the following changes are required:

1. Dependency Version Changes:

   // 0.1.x version (Spring Boot 2.x)
   implementation 'dev.simplecore.searchable:spring-boot-starter-searchable-jpa:0.1.x'
   
   // 1.0.0+ version (Spring Boot 3.x)
   implementation 'dev.simplecore.searchable:spring-boot-starter-searchable-jpa:1.0.0+'

2. Jakarta EE Migration:

   • Change all javax.* imports to jakarta.*
   • Update JPA-related imports in application code if they are used directly

System Requirements

• Java: 17+
• Spring Boot: 3.2.5+ (1.0.0+ versions)
• Spring Boot: 2.7.x (0.1.x versions)
• Jakarta EE: 9+ (1.0.0+ versions)
• javax. support*: 2.7.x and below (0.1.x versions)

Spring Boot 3.2.5 Migration Completed

Key Features

• Dynamic Search: Supports 20+ search operators (EQUALS, CONTAINS, BETWEEN, etc.)
• Flexible Sorting: Multi-field sorting and dynamic sort conditions
• High-Performance Pagination: Cursor-based pagination for large dataset processing
• Type Safety: Compile-time validation and type-safe builder patterns
• OpenAPI Integration: Automatic Swagger documentation generation
• Multiple Data Types: Support for strings, numbers, dates, enums, and nested objects

Quick Start

1. Add Dependency

implementation 'dev.simplecore.searchable:spring-boot-starter-searchable-jpa:1.0.0-SNAPSHOT'

2. Application Configuration (Optional)

Configure application.yml for library usage:

# Searchable JPA Configuration (All optional, defaults exist)
searchable:
  swagger:
    enabled: true                    # Enable automatic OpenAPI documentation generation (default: true)
  max-page-size: 1000               # Maximum page size (default: 1000)
  default-page-size: 20             # Default page size (default: 20)

3. Define DTO Class

public class PostSearchDTO {
    @SearchableField(operators = {EQUALS, CONTAINS}, sortable = true)
    private String title;

    @SearchableField(operators = {EQUALS}, sortable = true)
    private PostStatus status;

    @SearchableField(operators = {GREATER_THAN, LESS_THAN}, sortable = true)
    private LocalDateTime createdAt;
}

4. Implement Service Class

@Service
public class PostService extends DefaultSearchableService<Post, Long> {
    public PostService(PostRepository repository, EntityManager entityManager) {
        super(repository, entityManager);
    }
}

5. Use in Controller

@RestController
public class PostController {
    @GetMapping("/api/posts/search")
    public Page<Post> searchPosts(
        @RequestParam @SearchableParams(PostSearchDTO.class) Map<String, String> params
    ) {
        SearchCondition<PostSearchDTO> condition =
            new SearchableParamsParser<>(PostSearchDTO.class).convert(params);
        return postService.findAllWithSearch(condition);
    }
}

6. API Call

# Search posts containing "Spring" in title
GET /api/posts/search?title.contains=Spring&sort=createdAt,desc&page=0&size=10

Documentation

Korean Documentation

• Installation Guide - System requirements and installation instructions
• Basic Usage - Basic usage methods and examples
• Search Operators - All supported search operators
• Advanced Features - Complex search conditions and advanced features
• Two-Phase Query Optimization - High-performance cursor-based pagination
• Relational Data and Two-Phase Query - JPA relationship mapping and N+1 problem resolution
• Auto Configuration - Spring Boot auto-configuration settings
• OpenAPI Integration - Automatic Swagger documentation generation
• API Reference - Complete API documentation
• FAQ - Frequently asked questions and troubleshooting

English Documentation

Coming Soon - English documentation is currently being prepared.

License

This project is distributed under the SimpleCORE License 1.0.

---

Try implementing easier and faster search functionality with Searchable JPA!