Spring/spring-data-jpa
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

DATAJPA-707 - Documentation.

Browse Source 
Reworked the stored procedure documentation since it was rather confusing.
Added a paragraph about stored procedures.

Original pull request: #297.
This commit is contained in:
Jens Schauder
2019-06-06 14:43:05 +02:00
parent 2f03fc0067
commit 5ee04edaf9
1 changed files with 28 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
src/main/asciidoc/jpa.adoc
View File

@@ -643,9 +643,10 @@ include::{spring-data-commons-docs}/repository-projections.adoc[leveloffset=+2]
[[jpa.stored-procedures]]
== Stored Procedures
The JPA 2.1 specification introduced support for calling stored procedures by using the JPA criteria query API. We Introduced the `@Procedure` annotation for declaring stored procedure metadata on a repository method.
The JPA 2.1 specification introduced support for calling stored procedures by using the JPA criteria query API.
We Introduced the `@Procedure` annotation for declaring stored procedure metadata on a repository method.
The examples to follow use the following procedure:
The examples to follow use the following stored procedure:
.The definition of the `plus1inout` procedure in HSQL DB.
====
@@ -677,7 +678,15 @@ public class User {}
----
====
You can reference stored procedures from a repository method in multiple ways. The stored procedure to be called can either be defined directly by using the `value` or `procedureName` attribute of the `@Procedure` annotation or indirectly by using the `name` attribute. If no name is configured, the name of the repository method is used as a fallback.
Note that `@NamedStoredProcedureQuery` has two different names for the stored procedure.
`name` is the name JPA uses. `procedureName` is the name the stored procedure has in the database.
You can reference stored procedures from a repository method in multiple ways.
The stored procedure to be called can either be defined directly by using the `value` or `procedureName` attribute of the `@Procedure` annotation.
This referes directly to the stored procedure in the database and ignores any configuration via `@NamedStoredProcedureQuery`.
Alternatively you may specify the `@NamedStoredProcedureQuery.name` attribute as the `@Procedure.name` attribute.
If neither `value`, `procedureName` nor `name` is configured, the name of the repository method is used as the `name` attribute.
The following example shows how to reference an explicitly mapped procedure:
@@ -691,18 +700,29 @@ Integer explicitlyNamedPlus1inout(Integer arg);
----
====
The following example shows how to reference an implicitly mapped procedure by using a `procedureName` alias:
The following example is equivalent to the previous one but uses the `procedureName` alias:
.Referencing implicitly mapped procedure with name "plus1inout" in database via `procedureName` alias.
====
[source, java]
----
@Procedure(procedureName = "plus1inout")
Integer plus1inout(Integer arg);
Integer callPlus1InOut(Integer arg);
----
====
The following example shows how to reference an explicitly mapped named procedure in `EntityManager`:
The following is again equivalent to the previous two but using the method name instead of an explicite annotation attribute.
.Referencing implicitly mapped named stored procedure "User.plus1" in `EntityManager` by using the method name.
====
[source, java]
----
@Procedure
Integer plus1inout(@Param("arg") Integer arg);
----
====
The following example shows how to reference a stored procedure by referencing the `@NamedStoredProcedureQuery.name` attribute.
.Referencing explicitly mapped named stored procedure "User.plus1IO" in `EntityManager`.
====
@@ -713,16 +733,9 @@ Integer entityAnnotatedCustomNamedProcedurePlus1IO(@Param("arg") Integer arg);
----
====
The following example shows how to reference an implicitly named stored procedure in `EntityManager` by using the method name:
If the stored procedure getting called has a single out parameter that parameter may be returned as the return value of the method.
If there are multiple out parameters specified in a `@NamedStoredProcedureQuery` annotation those can be returned as a `Map` with the key being the parameter name given in the `@NamedStoredProcedureQuery` annotation.
.Referencing implicitly mapped named stored procedure "User.plus1" in `EntityManager` by using the method name.
====
[source, java]
----
@Procedure
Integer plus1(@Param("arg") Integer arg);
----
====
[[specifications]]
== Specifications