Stored Procedures

JPA 2.1 规范引入了通过使用 JPA criteria query API 调用存储过程的支持。我们引入了 @Procedure 注释，用于在存储库方法上声明存储过程元数据。

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 stored procedure:

Example 1. The definition of the plus1inout procedure in HSQL DB.
/;
DROP procedure IF EXISTS plus1inout
/;
CREATE procedure plus1inout (IN arg int, OUT res int)
BEGIN ATOMIC
 set res = arg + 1;
END
/;

可使用 NamedStoredProcedureQuery 注释对某个实体类型上的存储过程元数据进行配置。

Metadata for stored procedures can be configured by using the NamedStoredProcedureQuery annotation on an entity type.

Example 2. StoredProcedure metadata definitions on an entity.
@Entity
@NamedStoredProcedureQuery(name = "User.plus1", procedureName = "plus1inout", parameters = {
  @StoredProcedureParameter(mode = ParameterMode.IN, name = "arg", type = Integer.class),
  @StoredProcedureParameter(mode = ParameterMode.OUT, name = "res", type = Integer.class) })
public class User {}

请注意， @NamedStoredProcedureQuery 针对存储过程有两个不同的名称。name 是 JPA 所使用的名称。procedureName 是存储过程在数据库中的名称。

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.

可以通过多种方式从存储库方法引用存储过程。可通过使用 @Procedure 注释的 value 或 procedureName 特性直接定义要调用的存储过程。这会直接引用数据库中的存储过程，并忽略通过 @NamedStoredProcedureQuery 进行的任何配置。

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 refers directly to the stored procedure in the database and ignores any configuration via @NamedStoredProcedureQuery.

或者，可以将 @NamedStoredProcedureQuery.name 特性指定为 @Procedure.name 特性。如果未配置 value、procedureName 或 name，则会使用存储库方法的名称作为 name 特性。

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:

Example 3. Referencing explicitly mapped procedure with name "plus1inout" in database.
@Procedure("plus1inout")
Integer explicitlyNamedPlus1inout(Integer arg);

以下示例等同于上一个示例，但它使用了 procedureName 别名：

The following example is equivalent to the previous one but uses the procedureName alias:

Example 4. Referencing implicitly mapped procedure with name "plus1inout" in database via procedureName alias.
@Procedure(procedureName = "plus1inout")
Integer callPlus1InOut(Integer arg);

以下示例又等同于前两个示例，但使用的是方法名而不是明确的注释特性。

The following is again equivalent to the previous two but using the method name instead of an explicite annotation attribute.

Example 5. Referencing implicitly mapped named stored procedure "User.plus1" in EntityManager by using the method name.
@Procedure
Integer plus1inout(@Param("arg") Integer arg);

以下示例展示了如何通过引用 @NamedStoredProcedureQuery.name 特性来引用存储过程。

The following example shows how to reference a stored procedure by referencing the @NamedStoredProcedureQuery.name attribute.

Example 6. Referencing explicitly mapped named stored procedure "User.plus1IO" in EntityManager.
@Procedure(name = "User.plus1IO")
Integer entityAnnotatedCustomNamedProcedurePlus1IO(@Param("arg") Integer arg);

如果所调用的存储过程有一个单一的 out 参数，那么该参数可作为方法的返回值返回。如果在 @NamedStoredProcedureQuery 注释中指定了多个 out 参数，那么这些参数可作为 Map 返回，其中键是由 @NamedStoredProcedureQuery 注释给出的参数名。

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.