HV-714 Updating reference guide

documentation/src/main/docbook/en-US/modules/method-constraints.xml

@@ -892,4 +892,40 @@ assertEquals( 0, parameterNode.getParameterIndex() );         </programlisting>
       <literal>arg0</literal>, <literal>arg1</literal> etc.</para>
     </section>
   </section>
+
+  <section id="section-builtin-method-constraints">
+    <title>Built-in method constraints</title>
+
+    <para>In addition to the built-in bean and property-level constraints
+    discussed in <xref linkend="section-builtin-constraints"/>, Hibernate
+    Validator currently provides one method-level constraint,
+    <classname>@ParameterScriptAssert</classname>. This is a generic
+    cross-parameter constraint which allows to implement validation routines
+    using any JSR 223 compatible ("Scripting for the
+    Java<superscript>TM</superscript> Platform") scripting language, provided
+    an engine for this language is available on the classpath.</para>
+
+    <para>To refer to the executable's parameters from within the expression,
+    use their name as obtained from the active parameter name provider (see
+    <xref linkend="section-parameter-name-provider"/>). <xref
+    linkend="example-parameterscriptassert"/> shows how the validation logic
+    of the <classname>@LuggageCountMatchesPassengerCount</classname>
+    constraint from <xref linkend="example-using-cross-parameter-constraint"/>
+    could be expressed with the help of
+    <classname>@ParameterScriptAssert</classname>.</para>
+
+    <example id="example-parameterscriptassert">
+      <title>Using <classname>@ParameterScriptAssert</classname></title>
+
+      <programlisting language="JAVA" role="JAVA">package org.hibernate.validator.referenceguide.chapter03.parametersscriptassert;
+
+public class Car {
+
+	@ParameterScriptAssert(lang = "javascript", script = "arg1.size() &lt;= arg0.size() * 2")
+	public void load(List&lt;Person&gt; passengers, List&lt;PieceOfLuggage&gt; luggage) {
+		//...
+	}
+}     </programlisting>
+    </example>
+  </section>
 </chapter>

documentation/src/test/java/org/hibernate/validator/referenceguide/chapter03/parameterscriptassert/Car.java

@@ -0,0 +1,13 @@
+package org.hibernate.validator.referenceguide.chapter03.parameterscriptassert;
+
+import java.util.List;
+
+import org.hibernate.validator.constraints.ParameterScriptAssert;
+
+public class Car {
+
+	@ParameterScriptAssert(lang = "javascript", script = "arg1.size() <= arg0.size() * 2")
+	public void load(List<Person> passengers, List<PieceOfLuggage> luggage) {
+		//...
+	}
+}

documentation/src/test/java/org/hibernate/validator/referenceguide/chapter03/parameterscriptassert/ParameterScriptAssertTest.java

@@ -0,0 +1,53 @@
+package org.hibernate.validator.referenceguide.chapter03.parameterscriptassert;
+
+import java.lang.annotation.Annotation;
+import java.lang.reflect.Method;
+import java.util.Arrays;
+import java.util.List;
+import java.util.Set;
+import javax.validation.ConstraintViolation;
+import javax.validation.Validation;
+import javax.validation.ValidatorFactory;
+import javax.validation.executable.ExecutableValidator;
+
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import org.hibernate.validator.constraints.ParameterScriptAssert;
+
+import static org.junit.Assert.assertEquals;
+
+public class ParameterScriptAssertTest {
+
+	private static ExecutableValidator executableValidator;
+
+	@BeforeClass
+	public static void setUpValidator() {
+		ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
+		executableValidator = factory.getValidator().forExecutables();
+	}
+
+	@Test
+	public void validateParameters() throws Exception {
+		Car object = new Car();
+		Method method = Car.class.getMethod( "load", List.class, List.class );
+		Object[] parameterValues = {
+				Arrays.asList( new Person() ),
+				Arrays.asList( new PieceOfLuggage(), new PieceOfLuggage(), new PieceOfLuggage() )
+		};
+
+		Set<ConstraintViolation<Car>> violations = executableValidator.validateParameters(
+				object,
+				method,
+				parameterValues
+		);
+
+		assertEquals( 1, violations.size() );
+		Class<? extends Annotation> constraintType = violations.iterator()
+				.next()
+				.getConstraintDescriptor()
+				.getAnnotation()
+				.annotationType();
+		assertEquals( ParameterScriptAssert.class, constraintType );
+	}
+}

documentation/src/test/java/org/hibernate/validator/referenceguide/chapter03/parameterscriptassert/Person.java

@@ -0,0 +1,4 @@
+package org.hibernate.validator.referenceguide.chapter03.parameterscriptassert;
+
+public class Person {
+}

documentation/src/test/java/org/hibernate/validator/referenceguide/chapter03/parameterscriptassert/PieceOfLuggage.java

@@ -0,0 +1,4 @@
+package org.hibernate.validator.referenceguide.chapter03.parameterscriptassert;
+
+public class PieceOfLuggage {
+}