[clarification]: query by method name method parameters

[gavinking]

Specification

Query by Method Name

I need clarification on ...

The relationship between Query by Method Name operators and the parameters of the repository method.

Additional information

If we're going to keep this as a required part of the spec [now that we have JDQL, @Query, and @Find properly nailed down, I'm ready to have a probably-difficult conversation about that], then we at least need to make sure that this facility is fully-specified.

Reviewing this, it does seem to be mostly sorta OK, but:

• the allowed return types are defined only in module-info, in a very sketchy format, and not in the spec itself, and
• the allowed parameter types, and their relationship to the query itself are, AFICS, completely unspecified. This is less-than-trivial when we have operators like In and Between.

So there is at least some work to do here.

Also I'm also not sure I understand how to interpret shorthands like OrderBy____(Asc|Desc)*(Asc |Desc). Actually that might just be an error.

[njr-11]

Also I'm also not sure I understand how to interpret shorthands like OrderBy____(Asc|Desc)*(Asc |Desc). Actually that might just be an error

I remember needing to ask what that meant as well when I wanted to write valid examples of it to put in module-info. If it doesn't make sense to the authors of the spec, it won't make sense to users either and we should fix it.

I included at least part of an attempt at that in #577

[njr-11]

• the allowed return types are defined only in module-info, in a very sketchy format, and not in the spec itself, and

The JavaDoc in module-info is intended as a quick reference for application developers and often relies on tables and examples that you can copy from to try to visually get the point across. If the information is missing from the specification document, we should make sure to add it there.

[njr-11]

• the allowed parameter types, and their relationship to the query itself are, AFICS, completely unspecified. This is less-than-trivial when we have operators like In and Between.

The table of Query by Method Name keywords reserved for the predicate in module-info was supposed to get across some of that information in a general sense. Here is the information that is currently there for Between,

Keyword: Between

Applies to: numeric, strings, time

Description: Requires that the entity's attribute value be within the range specified by two parameters, inclusive of the parameters. The minimum is listed first, then the maximum.

Example: findByAgeBetween(minAge, maxAge)

One deficiency here is that we never define what "numeric", "strings", and "time" actually mean. We should be more precise and do that.

The description should probably say "...inclusive of the parameter values..."

If adequate information about these keywords and the parameters for them isn't in the specification doc, it needs to be added.

[gavinking]

But also:

• Which operators correspond to parameters, and how many parameters does each operator correspond to?
• What are the types of these parameters? The same as the the entity field? What about In?
• How are parameters correlated with operators? Parameters have the same order as the operators, I assume, but that's not stated.

One deficiency here is that we never define what "numeric", "strings", and "time" actually mean.

Actually this particular issue if more of a failing of section 3.1.3 (Basic Types), which should say that Data considers BigInteger and BigDecimal to be numeric types.

[gavinking]

What are the types of these parameters? The same as the the entity field? What about In?

Alright, so from the TCK I have learned that apparently the parameter type corresponding to In is Set. This isn't defined anywhere outside of the TCK.