(causeway) branch master updated: CAUSEWAY-3642: doc update

[ah...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

ahuber pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/causeway.git


The following commit(s) were added to refs/heads/master by this push:
     new c47cda7647 CAUSEWAY-3642: doc update
c47cda7647 is described below

commit c47cda7647896d12342f57fbcad8101584eb8b38
Author: Andi Huber <ah...@apache.org>
AuthorDate: Mon Jun 17 09:42:08 2024 +0200

    CAUSEWAY-3642: doc update
---
 .../CollectionFilterService.adoc}                  | 50 +++++++++++++++++-----
 1 file changed, 39 insertions(+), 11 deletions(-)

diff --git a/antora/components/refguide-index/modules/applib/pages/index/services/search/CollectionSearchService.adoc b/antora/components/refguide-index/modules/applib/pages/index/services/filter/CollectionFilterService.adoc
similarity index 54%
rename from antora/components/refguide-index/modules/applib/pages/index/services/search/CollectionSearchService.adoc
rename to antora/components/refguide-index/modules/applib/pages/index/services/filter/CollectionFilterService.adoc
index 25aee0c3ca..b9ce84e9fe 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/services/search/CollectionSearchService.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/services/filter/CollectionFilterService.adoc
@@ -1,18 +1,20 @@
-= CollectionSearchService
+= CollectionFilterService
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
 
 EXPERIMENTAL/DRAFT
 
-If at least one xref:refguide:applib:index/services/search/CollectionSearchService.adoc[CollectionSearchService] is registered with Spring's context that handles a given domainType, viewer implementations (like Wicket Viewer) should show a quick-search prompt, which is rendered on top of the UI table that presents the collection in question.
+If at least one xref:refguide:applib:index/services/filter/CollectionFilterService.adoc[CollectionFilterService] is registered with Spring's context that handles a given domainType, viewer implementations (like Wicket Viewer) should show a quick-search prompt, which is rendered on top of the UI table that presents the collection in question.
 
 == API
 
 [source,java]
-.CollectionSearchService.java
+.CollectionFilterService.java
 ----
-interface CollectionSearchService {
+interface CollectionFilterService {
   boolean handles(Class<?> domainType)     // <.>
-  BiPredicate<T, String> searchPredicate(Class<T> domainType)     // <.>
+  Function<T, Tokens> tokenizer(Class<T> domainType)     // <.>
+  BiPredicate<Tokens, String> tokenFilter(Class<T> domainType)     // <.>
+  String sanitzeSearchArgument(String searchArg)     // <.>
   TranslatableString searchPromptPlaceholderText(Class<?> domainType)     // <.>
   TranslationContext translationContext(Class<?> domainType)     // <.>
 }
@@ -23,10 +25,20 @@ interface CollectionSearchService {
 --
 Whether this service handles given type.
 --
-<.> xref:#searchPredicate_Class[searchPredicate(Class)]
+<.> xref:#tokenizer_Class[tokenizer(Class)]
 +
 --
-Returns a _BiPredicate_ that filters collections of given _domainType_ by a nullable searchString.
+Returns a function that for a given domainObject returns _Tokens_ (words), that are then matchable by _#tokenFilter(Class)_ .
+--
+<.> xref:#tokenFilter_Class[tokenFilter(Class)]
++
+--
+For given _domainType_ returns a _BiPredicate_ that matches _Tokens_ against a nullable searchString.
+--
+<.> xref:#sanitzeSearchArgument_String[sanitzeSearchArgument(String)]
++
+--
+Pre-process user input before passing it to the matcher.
 --
 <.> xref:#searchPromptPlaceholderText_Class[searchPromptPlaceholderText(Class)]
 +
@@ -46,12 +58,28 @@ Provides the xref:refguide:applib:index/services/i18n/TranslationContext.adoc[Tr
 
 Whether this service handles given type.
 
-[#searchPredicate_Class]
-=== searchPredicate(Class)
+[#tokenizer_Class]
+=== tokenizer(Class)
+
+Returns a function that for a given domainObject returns _Tokens_ (words), that are then matchable by _#tokenFilter(Class)_ .
+
+For example the domain object's title could be tokenized (parsed into tokens).
+
+[#tokenFilter_Class]
+=== tokenFilter(Class)
+
+For given _domainType_ returns a _BiPredicate_ that matches _Tokens_ against a nullable searchString.
+
+For example, the searchString could be tokenized (parsed into tokens), and then matched against the _Tokens_ using either OR or AND semantics.
+
+The default implementation sanitizes the user input (searchArg) then strips any leading or trailing blanks and handles the empty searchArg case.
+
+[#sanitzeSearchArgument_String]
+=== sanitzeSearchArgument(String)
 
-Returns a _BiPredicate_ that filters collections of given _domainType_ by a nullable searchString.
+Pre-process user input before passing it to the matcher.
 
-For example, the searchString could be parsed into tokens, and then matched against the domain object's title say.
+Default behavior is to strip leading or trailing blanks (if any).
 
 [#searchPromptPlaceholderText_Class]
 === searchPromptPlaceholderText(Class)