use @Query and @Find for example code in chapter 4

[gavinking]

instead of Query by Method Name, which has been exiled to a separate document.

[njr-11]

Prior to your changes, these examples covered 5 scenarios:

OrderBy keyword + Order param
OrderBy keyword + Sort... param
OrderBy anno + Order param
OrderBy anno + Sort... param
Query without ORDER BY + OrderBy anno + Order param

After changes, it now only covers 2 scenarios with several duplicated:

Query without ORDER BY + OrderBy anno + Order param
Query without ORDER BY + OrderBy anno + Sort... param
Query without ORDER BY + OrderBy anno + Order param
Query without ORDER BY + OrderBy anno + Sort... param
Query without ORDER BY + OrderBy anno + Order param

Adding suggestions to restore to previous:

Suggested change

	@Query("where left(name,length(?1)) = ?1")
	@OrderBy(_User.TYPE)
	Page<User> findByNamePrefix(String namePrefix,
	PageRequest pagination,
	Order<User> sorts);
	Page<User> findByNameStartsWithOrderByType(String namePrefix,
	PageRequest pagination,
	Order<User> sorts);

[njr-11]

Suggested change

	@Query("where left(name,length(?1)) = ?1")
	@OrderBy(_User.TYPE)
	List<User> findByNamePrefix(String namePrefix, Sort<?>... sorts);
	List<User> findByNameStartsWithOrderByType(String namePrefix, Sort<?>... sorts);

[njr-11]

Suggested change

	@Query("where left(name,length(?1)) = ?1")
	@OrderBy(_User.AGE)
	Page<User> findByNamePrefix(String namePrefix,
	PageRequest pagination,
	Order<User> sorts);
	@OrderBy(_User.AGE)
	Page<User> findByNameStartsWith(String namePrefix,
	PageRequest pagination,
	Order<User> sorts);

[njr-11]

Suggested change

	@Query("where left(name,length(?1)) = ?1")
	@OrderBy(_User.AGE)
	List<User> findByNamePrefix(String namePrefix, Sort<?>... sorts);
	@OrderBy(_User.AGE)
	List<User> findByNameStartsWith(String namePrefix, Sort<?>... sorts);

[gavinking]

@njr-11 Again, I don't think we should be having examples with QbMN in the main spec, because the main spec does not define what QbMN is. I agree that there is now duplication in the examples; the best fix to that would be to simply delete a couple of them.

[gavinking]

I mean, a reader of the Jakarta Data spec is going to encounter those examples and think "WTF is this findByNameStartsWithOrderByType stuff?"

[gavinking]

Please see 9c43087, which removes the duplication.

[njr-11]

@njr-11 Again, I don't think we should be having examples with QbMN in the main spec, because the main spec does not define what QbMN is. I agree that there is now duplication in the examples; the best fix to that would be to simply delete a couple of them.

Given that Query by Method Name is still part of Jakarta Data, the spec has an obligation to cover how it behaves with respect to the rest of the specification, regardless of whether it is defined in a separate PDF or not. These examples are probably not that important and it could be stated that OrderBy keyword behaves the same as OrderBy annotation here, but I don't want to start a precedent for neglecting to adequately cover Query by Method Name because of where it appears in the spec.

[gavinking]

@njr-11 Then move the examples to the Query by Method Name document. I'm not sure they're needed, but I don't object to having them. I've put quite a lot of work into improving the material in that document over the weekend, but any help would be appreciated, which includes anything you think is missing and want to add.

But for sure these examples don't belong where they are right now, because the reader has never encountered a Query by Method Name, and will have no idea how to interpret the examples. Examples have to be examples of something you have properly introduced previously. You have to assume that the reader is reading the text in a linear fashion, even if that's not always the case in practice.

[gavinking]

I think this should be merged.

I insist that we should never have examples in the spec which the reader will not understand. What is the point of such an example?

[njr-11]

I insist that we should never have examples in the spec which the reader will not understand. What is the point of such an example?

I don't agree that the user will not understand. Query by Method Name is still part of the spec, whether in one document or the other. If having it in the other document causes this much trouble and is used as justification for not being able to refer to it and use it in examples in the rest of the specification, then it should not have been moved. That said, I do not see anything that is incorrect about your changes, and you have at least one other fix to an error in here so I will agree to approve it.