HHH-11186 - Add examples for all Hibernate annotations

Document @NamedStoredProcedureQuery and @StoredProcedureParameter annotations

documentation/src/main/asciidoc/userguide/appendices/Annotations.adoc

@@ -389,7 +389,7 @@ The http://docs.oracle.com/javaee/7/api/javax/persistence/NamedQueries.html[`@Na
 
 The http://docs.oracle.com/javaee/7/api/javax/persistence/NamedQuery.html[`@NamedQuery`] annotation is used to specify a JPQL query that can be retrieved later by its name.
 
-//TODO: Add example
+See the <<chapters/query/hql/HQL.adoc#jpql-api-named-query-example, `@NamedQuery`>> section for more info.
 
 [[annotations-jpa-namedstoredprocedurequeries]]
 ==== `@NamedStoredProcedureQueries`
@@ -401,7 +401,7 @@ The http://docs.oracle.com/javaee/7/api/javax/persistence/NamedStoredProcedureQu
 
 The http://docs.oracle.com/javaee/7/api/javax/persistence/NamedStoredProcedureQuery.html[`@NamedStoredProcedureQuery`] annotation is used to specify a stored procedure query that can be retrieved later by its name.
 
-//TODO: Add example
+See the <<chapters/query/native/Native.adoc#sql-sp-named-query, Using named queries to call stored procedures>> section for more info.
 
 [[annotations-jpa-namedsubgraph]]
 ==== `@NamedSubgraph`
@@ -574,7 +574,7 @@ The http://docs.oracle.com/javaee/7/api/javax/persistence/SqlResultSetMappings.h
 
 The http://docs.oracle.com/javaee/7/api/javax/persistence/StoredProcedureParameter.html[`@StoredProcedureParameter`] annotation is used to specify a parameter of a <<annotations-jpa-namedstoredprocedurequery>>.
 
-//TODO: Add example
+See the <<chapters/query/native/Native.adoc#sql-sp-named-query, Using named queries to call stored procedures>> section for more info.
 
 [[annotations-jpa-table]]
 ==== `@Table`

documentation/src/main/asciidoc/userguide/chapters/query/native/Native.adoc

@@ -832,6 +832,32 @@ Hibernate will iterate the results and take the first result that is a result se
 For SQL Server, if you can enable `SET NOCOUNT ON` in your procedure it will probably be more efficient, but this is not a requirement.
 ====
 
+[[sql-sp-named-query]]
+=== Using named queries to call stored procedures
+
+Just like with SQL statements, you can also use named queries to call stored procedures.
+For this purpose, JPA defines the http://docs.oracle.com/javaee/7/api/javax/persistence/NamedStoredProcedureQuery.html[`@NamedStoredProcedureQuery`] annotation.
+
+[[sql-sp-ref-cursor-oracle-named-query-example]]
+.Oracle `REF_CURSOR` named query stored procedure
+====
+[source, JAVA, indent=0]
+----
+include::{modeldir}/Person.java[tags=sql-sp-ref-cursor-oracle-named-query-example]
+----
+====
+
+Calling this stored procedure is straightforward, as illustrated by the following example.
+
+[[sql-jpa-call-sp-ref-cursor-oracle-named-query-example]]
+.Calling an Oracle `REF_CURSOR` stored procedure using a JPA named query
+====
+[source, JAVA, indent=0]
+----
+include::{sourcedir}/OracleStoredProcedureTest.java[tags=sql-jpa-call-sp-ref-cursor-oracle-named-query-example]
+----
+====
+
 [[sql-crud]]
 === Custom SQL for create, update, and delete
 

documentation/src/main/java/org/hibernate/userguide/model/Person.java

@@ -26,10 +26,14 @@ import javax.persistence.NamedNativeQueries;
 import javax.persistence.NamedNativeQuery;
 import javax.persistence.NamedQueries;
 import javax.persistence.NamedQuery;
+import javax.persistence.NamedStoredProcedureQueries;
+import javax.persistence.NamedStoredProcedureQuery;
 import javax.persistence.OneToMany;
 import javax.persistence.OrderColumn;
+import javax.persistence.ParameterMode;
 import javax.persistence.SqlResultSetMapping;
 import javax.persistence.SqlResultSetMappings;
+import javax.persistence.StoredProcedureParameter;
 import javax.persistence.Temporal;
 import javax.persistence.TemporalType;
 import javax.persistence.Version;
@@ -155,6 +159,26 @@ import javax.persistence.Version;
     )
 )
 //end::jpql-api-named-query-example[]
+//tag::sql-sp-ref-cursor-oracle-named-query-example[]
+@NamedStoredProcedureQueries(
+    @NamedStoredProcedureQuery(
+        name = "sp_person_phones",
+        procedureName = "sp_person_phones",
+        parameters = {
+            @StoredProcedureParameter(
+                name = "personId",
+                type = Long.class,
+                mode = ParameterMode.IN
+            ),
+            @StoredProcedureParameter(
+                name = "personPhones",
+                type = Class.class,
+                mode = ParameterMode.REF_CURSOR
+            )
+        }
+    )
+)
+//end::sql-sp-ref-cursor-oracle-named-query-example[]
 @Entity
 public class Person {
 

documentation/src/test/java/org/hibernate/userguide/sql/OracleStoredProcedureTest.java

@@ -184,6 +184,20 @@ public class OracleStoredProcedureTest extends BaseEntityManagerFunctionalTestCa
         });
     }
 
+    @Test
+    public void testStoredProcedureRefCursorUsingNamedQuery() {
+        doInJPA( this::entityManagerFactory, entityManager -> {
+            //tag::sql-jpa-call-sp-ref-cursor-oracle-named-query-example[]
+            List<Object[]> postComments = entityManager
+            .createNamedStoredProcedureQuery( "sp_person_phones" )
+            .setParameter( "personId", 1L )
+            .getResultList();
+            //end::sql-jpa-call-sp-ref-cursor-oracle-named-query-example[]
+
+            assertNotNull( postComments );
+        });
+    }
+
     @Test
     public void testHibernateProcedureCallRefCursor() {
         doInJPA( this::entityManagerFactory, entityManager -> {