Add Fluent API for Query Functions in Jakarta NoSQL (e.g., LEFT, UPPER, ABS, etc.) #204

[omatheusmesmo]

Summary

This Pull Request introduces a structured fluent API for using scalar functions in Jakarta NoSQL queries, aligning with the Jakarta Query specification. It allows developers to express richer queries with improved type safety and consistency across NoSQL providers.

---

Fix #204

Key Changes

1. API Core

• Created jakarta.nosql.Function: A new interface providing static factory methods for scalar operations: UPPER(), LOWER(), LEFT(), RIGHT(), LENGTH(), and ABS().
• Created jakarta.nosql.UnsupportedFunctionException: A specialized exception to signal when a specific function is not supported by the underlying database provider.
• Updated jakarta.nosql.QueryMapper: Added overloads for where(Function), and(Function), and or(Function) across SELECT, DELETE, and UPDATE fluent chains.

2. TCK (Compatibility Tests)

• Created Word entity and corresponding ArgumentsProvider suppliers.
• Implemented comprehensive TCK tests in ee.jakarta.tck.nosql.function covering all new scalar functions.
• Ensured 100% coverage for string and numeric function operations.

3. Documentation

• Updated spec/src/main/asciidoc/chapters/api/template.adoc with a new "Query Function Expressions" section.
• Added usage examples and a database support matrix.

Example Usage

// String function example
List<Word> words = template.select(Word.class)
        .where(Function.upper("meaning"))
        .eq("COFFEE")
        .result();

// Numeric function example
List<Word> highScores = template.select(Word.class)
        .where(Function.abs("score"))
        .gt(50)
        .result();

// Complex query with functions
List<Word> result = template.select(Word.class)
        .where(Function.left("term", 2))
        .eq("Ja")
        .and(Function.length("term"))
        .gt(5)
        .result();

Task Checklist (from Issue #204)

• Design the Function API class (static factory methods)
• Integrate Function into WhereClause expressions
• Update the Template.select() fluent chain to accept function expressions
• Add examples and usage documentation in the specification
• Implement TCK tests for:
  • LEFT()
  • RIGHT()
  • UPPER()
  • LOWER()
  • LENGTH()
  • ABS()

Quality Assurance

• mvn clean install passes successfully.
• No PMD violations found.
• Checkstyle rules followed.
• Javadoc generated without errors.
• All TCK tests pass.

[otaviojava]

In general, it is a good step, but I would start on the implementation, JNoSQL, where we can break and get mature, we can promote it as an API.

[omatheusmesmo]

In general, it is a good step, but I would start on the implementation, JNoSQL, where we can break and get mature, we can promote it as an API.

@otaviojava ,
Just to confirm: are you suggesting I should:

1. First implement this feature in the JNoSQL implementation (eclipse/jnosql)?
2. Then, once it's mature and tested, promote it to the Jakarta NoSQL spec?

If so, should I:

• Close this PR for now and open a new one in the JNoSQL repo?
• Or keep this PR as a draft while working on the implementation?

Thank you for your review.

[otaviojava]

In general, it is a good step, but I would start on the implementation, JNoSQL, where we can break and get mature, we can promote it as an API.

@otaviojava , Just to confirm: are you suggesting I should:

1. First implement this feature in the JNoSQL implementation (eclipse/jnosql)?
2. Then, once it's mature and tested, promote it to the Jakarta NoSQL spec?

Yeap!

At the Eclipse JNoSQL, please, do it on baby-steps as well.

1. Include support to the text query
2. implement those new functions at the drivers
3. Move it to the mappers

After testing, we can release a version and promote it to feedback.

Then, finally, we can move to the spec.