Starter

• 1: Query by Spec
• 2: Config SpecMapper

<dependency>
  <groupId>tw.com.softleader.data.jakarta</groupId>
  <artifactId>specification-mapper-starter</artifactId>
  <version>${specification-mapper.version}</version>
</dependency>

requires specification.mapper;
requires specification.mapper.starter;
requires jakarta.persistence;

logging:
  level:
    tw.com.softleader.data.jpa.spec.starter: info

spec:
  mapper:
    enabled: false

1 - Query by Spec

Query by Spec (QBS) provides the QueryBySpecExecutor<T> interface, which includes several query methods:

public interface QueryBySpecExecutor<T> {

  List<T> findBySpec(Object spec);
  
  List<T> findBySpec(Object spec, Sort sort);
  
  Page<T> findBySpec(Object spec, Pageable pageable);
  
  // … more functionality omitted.
}

To use these methods, you simply need to extend QueryBySpecExecutor<T> in your existing repository interface:

public interface PersonRepository 
  extends JpaRepository<Person, Long>, QueryBySpecExecutor<Person> {
  ...
}

@Service
public class PersonService {

  @Autowired PersonRepository personRepository;

  public List<Person> findPeople(PersonCriteria criteria) {
    return personRepository.findBySpec(criteria);
  }
}

By inheriting QueryBySpecExecutor<T>, you can directly use the query methods in your repository interface, making it easy to perform queries using specifications.

Customize Base Repository

During the configuration process, QBS automatically configures the Spring Data JPA Base Repository. The default implementation is DefaultQueryBySpecExecutor.

However, since Java only supports single inheritance, and to allow your application to retain its original parent Base Repository, QBS provides an extension point called QueryBySpecExecutorAdapter.

Depending on your application’s needs, you can choose to either extend DefaultQueryBySpecExecutor or implement QueryBySpecExecutorAdapter to customize the Base Repository. For example:

class MyRepositoryImpl<T, ID> extends SimpleJpaRepository<T, ID>
  implements QueryBySpecExecutorAdapter<T> {

  @Setter
  @Getter
  private SpecMapper specMapper;

  private final EntityManager entityManager;

  MyRepositoryImpl(JpaEntityInformation entityInformation,
                          EntityManager entityManager) {
    super(entityInformation, entityManager);

    // Keep the EntityManager around to be used from the newly introduced methods.
    this.entityManager = entityManager;
  }

  @Override
  public Class<T> getDomainClass() {
    return super.getDomainClass();
  }
  
  @Transactional
  public <S extends T> S mySave(S entity) {
    // implementation goes here
  }
}

You can configure your custom Base Repository by setting the spec.mapper.repository-base-class property in your application’s properties file, specifying the full package name of your custom base repository, like this:

spec:
  mapper:
    repository-base-class: com.example.MyRepositoryImpl

2 - Config SpecMapper

During application startup, the starter automatically configures a Default SpecMapper and registers it as a Spring @Bean, allowing you to retrieve it via Autowired.

@Autowired SpecMapper specMapper;

For example, if you want to enhance the specifications before performing the query, you can use the SpecMapper as follows:

class PersonService {

  @Autowired SpecMapper specMapper;
  @Autowired PersonRepository personRepository;

  List<Person> getPersonByCriteria(PersonCriteria criteria) {
    var spec = specMapper.toSpec(criteria);
    
    // Perform additional operations on the spec, ex:
    // spec = spec.and((root, query, criteriaBuilder) ->  {
    //     ...
    // });
    
    return personRepository.findAll(spec);
  }
}

In the above example, the SpecMapper is injected into the PersonService, allowing you to convert the criteria into a specification using specMapper.toSpec(). You can then modify the spec as needed before passing it to the personRepository for querying.

Configuration

The starter provides multiple ways to adjust the configuration of the Default SpecMapper.

SpecificationResolver

SpecificationResolver allows you to add custom Spec annotations. Simply register your custom implementation as a Spring @Bean, and it will be automatically detected and configured during application startup.

@Configuration
class MyConfig {

  @Bean
  SpecificationResolver myResolver() {
    return ...
  }
}

If your SpecificationResolver needs access to the SpecMapper itself, you can wrap it in a SpecificationResolverCodecBuilder. This way, the SpecCodec, which is the interface of SpecMapper, will be passed in when constructing the resolver. Here’s an example:

@Configuration
class MyConfig {

  @Bean
  SpecificationResolverCodecBuilder myResolver() {
    return MySpecificationResolver::new;
  }
}

class MySpecificationResolver implements SpecificationResolver {
  
  private final SpecCodec codec;
  
  MySpecificationResolver(SpecCodec codec) {
    // Keep the SpecCodec around to be used.
    this.codec = codec;
  }
  
  // implementation goes here
}

In the above example, the MySpecificationResolver is constructed with the SpecCodec provided by the SpecMapper. This allows you to access and utilize the SpecMapper functionality within your custom resolver.

SkippingStrategy

SkippingStrategy defines rules for skipping specific fields. By registering your custom implementation as a Spring @Bean, it will be automatically detected and added to the Default SpecMapper during application startup.

Example:

@Configuration
class MyConfig {

  @Bean
  SkippingStrategy mySkippingStrategy() {
    return ...
  }
}

ASTWriterFactory

As described in Logging, different Logger Name strategies are available. You can enable impersonation mode using the spec.mapper.impersonate-logger property. By default, this setting is disabled. To enable it:

spec:
  mapper:
    # Whether to impersonate the logger of the actual object being processed, off by default
    impersonate-logger: true

For full customization, register your own ASTWriterFactory implementation as a Spring @Bean, and it will be automatically detected and added to the Default SpecMapper.

Example:

@Configuration
class MyConfig {

  @Bean
  ASTWriterFactory myASTWriterFactory() {
    return ...
  }
}

Customize SpecMapper

You can also fully customize SpecMapper by registering your own implementation as a Spring @Bean, which will take precedence over the default configuration.

Example:

@Configuration
class MyConfig {

  @Bean
  SpecMapper mySpecMapper() {
    return SpecMapper.builder()
      . ...
      .build();
  }
}