clarify the parameter order of the locate() function

The current wording is very difficult for non-native speakers to
understand, "located" being almost a synonym for "searched", and
was apparently even misread by the person who wrote CriteriaBuilder,
since CriteriaBuilder.locate() gets the parameters in the "wrong"
order.

api/src/main/java/jakarta/persistence/criteria/CriteriaBuilder.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2008, 2020 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2008, 2022 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0 which is available at
@@ -1170,6 +1170,9 @@ public static enum Trimspec {
      * if found.
      * The first position in a string is denoted by 1.  If the
      * string to be located is not found, 0 is returned.
+     * <p><strong>Warning:</strong> the order of the parameters
+     * of this method is reversed compared to the corresponding
+     * function in JPQL.
      * @param x  expression for string to be searched
      * @param pattern  expression for string to be located
      * @return expression corresponding to position
@@ -1182,6 +1185,9 @@ public static enum Trimspec {
      * if found.
      * The first position in a string is denoted by 1.  If the
      * string to be located is not found, 0 is returned.
+     * <p><strong>Warning:</strong> the order of the parameters
+     * of this method is reversed compared to the corresponding
+     * function in JPQL.
      * @param x  expression for string to be searched
      * @param pattern  string to be located
      * @return expression corresponding to position
@@ -1194,6 +1200,9 @@ public static enum Trimspec {
      * if found.
      * The first position in a string is denoted by 1.  If the
      * string to be located is not found, 0 is returned.
+     * <p><strong>Warning:</strong> the order of the first two
+     * parameters of this method is reversed compared to the
+     * corresponding function in JPQL.
      * @param x  expression for string to be searched
      * @param pattern  expression for string to be located
      * @param from  expression for position at which to start search
@@ -1207,6 +1216,9 @@ public static enum Trimspec {
      * if found.
      * The first position in a string is denoted by 1.  If the
      * string to be located is not found, 0 is returned.
+     * <p><strong>Warning:</strong> the order of the first two
+     * parameters of this method is reversed compared to the
+     * corresponding function in JPQL.
      * @param x  expression for string to be searched
      * @param pattern  string to be located
      * @param from  position at which to start search

spec/src/main/asciidoc/ch04-query-language.adoc

@@ -1708,17 +1708,19 @@ The LOWER and UPPER functions convert a
 string to lower and upper case, respectively, with regard to the locale
 of the database. They return a string.
 
-The LOCATE function returns the
-position of a given string within a string, starting the search at a
-specified position. It returns the first position at which the string
-was found as an integer. The first argument is the string to be located;
-the second argument is the string to be searched; the optional third
-argument is an integer that represents the string position at which the
-search is started (by default, the beginning of the string to be
-searched). The first position in a string is denoted by 1. If the string
-is not found, 0 is returned.footnote:[Note that not all
-databases support the use of the third argument to LOCATE; use of this
-argument may result in queries that are not portable.]
+The LOCATE function returns the position at which one string occurs within
+a second string, optionally ignoring any occurrences that begin before a
+specified character position in the second string. It returns the first
+character position within the second string (after the specified character
+position, if any) at which the first string occurs, as an integer, where
+the first character of the second string is denoted by 1. That is, the first
+argument is the string to be searched for; the second argument is the string
+to be searched in; the optional third argument is an integer representing
+the character position at which the search starts (by default, 1, the first
+character of the second string). If the first string does not occur within
+the second string, 0 is returned.footnote:[Note that not all databases
+support the use of the third argument to LOCATE; use of this argument may
+result in queries that are not portable.]
 
 The LENGTH function returns the length of the
 string in characters as an integer.

spec/src/main/asciidoc/ch06-criteria-api.adoc

@@ -1,5 +1,5 @@
 //
-// Copyright (c) 2017, 2020 Contributors to the Eclipse Foundation
+// Copyright (c) 2017, 2022 Contributors to the Eclipse Foundation
 //
 
 == Criteria API [[a6925]]
@@ -1375,6 +1375,9 @@ public interface CriteriaBuilder {
      * if found.
      * The first position in a string is denoted by 1.  If the
      * string to be located is not found, 0 is returned.
+     * <p><strong>Warning:</strong> the order of the parameters
+     * of this method is reversed compared to the corresponding
+     * function in JPQL.
      * @param x  expression for string to be searched
      * @param pattern  expression for string to be located
      * @return expression corresponding to position
@@ -1387,6 +1390,9 @@ public interface CriteriaBuilder {
      * if found.
      * The first position in a string is denoted by 1.  If the
      * string to be located is not found, 0 is returned.
+     * <p><strong>Warning:</strong> the order of the parameters
+     * of this method is reversed compared to the corresponding
+     * function in JPQL.
      * @param x  expression for string to be searched
      * @param pattern  string to be located
      * @return expression corresponding to position
@@ -1399,6 +1405,9 @@ public interface CriteriaBuilder {
      * if found.
      * The first position in a string is denoted by 1.  If the
      * string to be located is not found, 0 is returned.
+     * <p><strong>Warning:</strong> the order of the first two
+     * parameters of this method is reversed compared to the
+     * corresponding function in JPQL.
      * @param x  expression for string to be searched
      * @param pattern  expression for string to be located
      * @param from  expression for position at which to start search
@@ -1412,6 +1421,9 @@ public interface CriteriaBuilder {
      * if found.
      * The first position in a string is denoted by 1.  If the
      * string to be located is not found, 0 is returned.
+     * <p><strong>Warning:</strong> the order of the first two
+     * parameters of this method is reversed compared to the
+     * corresponding function in JPQL.
      * @param x  expression for string to be searched
      * @param pattern  string to be located
      * @param from  position at which to start search