OFBIZ-13457 : Add generic REST collection query, filter, sort, and pagination helpers

[diveshdut]

Jira Ticket:

https://issues.apache.org/jira/browse/OFBIZ-13457

Summary

Adds generic framework support in framework/rest-api for REST collection query handling and paged response construction.

This contribution introduces reusable helpers for:

• normalized paging parameter parsing
• generic direct-parameter filter preservation
• sort expression validation
• optional endpoint validation for supported sort/filter fields
• optional endpoint validation for repeated filter values and filter value formats
• top-level pagination metadata
• body pagination links
• HTTP Link header generation for paged REST responses
• centralized 400 Bad Request mapping for malformed or unsupported query-contract input

The implementation is intended to be reusable across OFBiz REST endpoints while keeping endpoint-specific query policies optional.

What’s Included

• support for pageIndex / pageSize
• support for OFBiz-compatible aliases VIEW_INDEX / VIEW_SIZE
• default paging values and max page size enforcement
• validation of malformed or invalid paging input
• preservation of non-reserved query parameters as generic direct filter parameters
• generic sort validation helper for comma-separated sort expressions with optional - prefix
• sort validation for:
  • empty sort tokens
  • malformed tokens such as -
  • duplicate sort fields
  • unsupported sort fields when an endpoint provides an allowlist
• optional endpoint validation of allowed filter fields
• optional endpoint validation of repeated filter values
• optional endpoint validation of filter value format through per-field validators
• top-level response metadata:
  • pageIndex
  • pageSize
  • totalCount
  • totalPages
  • hasNext
• body pagination links:
  • self
  • prev
  • next
  • first
  • last
• omission of unavailable links, rather than returning empty placeholders
• omission of links entirely when no request path is available
• preservation of repeated non-reserved query parameters in generated pagination links
• query parameter decoding and re-encoding for generated pagination links
• HTTP Link header generation for paged success responses
• centralized mapping of query-contract IllegalArgumentException failures to HTTP 400 Bad Request
• focused framework tests covering:
  • paging normalization and defaults
  • malformed paging input
  • sort validation
  • duplicate sort rejection
  • optional sort/filter allowlist validation
  • repeated filter value policy
  • filter value-format validation
  • link generation
  • repeated query parameters
  • special-character encoding
  • HTTP Link header behavior
  • HTTP 400 mapping behavior

Query Contract Behavior

Current framework support in this PR is aligned to direct query parameters such as:

• paging:
  • ?pageIndex=0&pageSize=20
• sorting:
  • ?sort=statusId,-createdStamp
• filtering:
  • ?facilityId=WebStoreWarehouse&statusId=PRUN_CREATED

The framework now supports returning 400 Bad Request when the query contract is malformed or unsupported in these areas:

• invalid paging values
• malformed sort expressions
• duplicate sort fields
• unsupported sort fields when an endpoint supplies an allowlist
• unsupported filter fields when an endpoint supplies an allowlist
• repeated filter values when an endpoint does not allow repetition
• invalid filter value formats when an endpoint supplies a validator

Not Included

• no standardized filter= grammar yet
• no generic filtering operators such as eq, ne, gt, lt, etc.
• no generic parser for operator-based filter expressions
• no cursor-based pagination
• no framework-enforced endpoint default ordering
• no framework-mandated sort/filter allowlists for every endpoint
• no automatic endpoint-specific value/type validation unless the endpoint opts into the provided validator hooks

Verification

• compileJava
• test --tests org.apache.ofbiz.ws.rs.util.RestListResponseBuilderTest --tests org.apache.ofbiz.ws.rs.util.RestApiUtilPaginationTest --tests org.apache.ofbiz.ws.rs.util.RestQueryOptionsTest --tests org.apache.ofbiz.ws.rs.spi.impl.GlobalExceptionMapperTest

Compile and focused tests passed locally.