Add value attribute on provider annotations

Related with gh-1279

Author: kazuki43zoo

src/main/java/org/apache/ibatis/annotations/DeleteProvider.java

@@ -33,8 +33,20 @@
    * Specify a type that implements an SQL provider method.
    *
    * @return a type that implements an SQL provider method
+   * @since 3.5.2
+   * @see #type()
    */
-  Class<?> type();
+  Class<?> value() default void.class;
+
+  /**
+   * Specify a type that implements an SQL provider method.
+   * <p>
+   * This attribute is alias of {@link #value()}.
+   * </p>
+   * @return a type that implements an SQL provider method
+   * @see #value()
+   */
+  Class<?> type() default void.class;
 
   /**
    * Specify a method for providing an SQL.

src/main/java/org/apache/ibatis/annotations/InsertProvider.java

@@ -33,8 +33,21 @@
    * Specify a type that implements an SQL provider method.
    *
    * @return a type that implements an SQL provider method
+   * @since 3.5.2
+   * @see #type()
    */
-  Class<?> type();
+  Class<?> value() default void.class;
+
+  /**
+   * Specify a type that implements an SQL provider method.
+   * <p>
+   * This attribute is alias of {@link #value()}.
+   * </p>
+   *
+   * @return a type that implements an SQL provider method
+   * @see #value()
+   */
+  Class<?> type() default void.class;
 
   /**
    * Specify a method for providing an SQL.

src/main/java/org/apache/ibatis/annotations/SelectProvider.java

@@ -33,8 +33,21 @@
    * Specify a type that implements an SQL provider method.
    *
    * @return a type that implements an SQL provider method
+   * @since 3.5.2
+   * @see #type()
    */
-  Class<?> type();
+  Class<?> value() default void.class;
+
+  /**
+   * Specify a type that implements an SQL provider method.
+   * <p>
+   * This attribute is alias of {@link #value()}.
+   * </p>
+   *
+   * @return a type that implements an SQL provider method
+   * @see #value()
+   */
+  Class<?> type() default void.class;
 
   /**
    * Specify a method for providing an SQL.

src/main/java/org/apache/ibatis/annotations/UpdateProvider.java

@@ -33,8 +33,21 @@
    * Specify a type that implements an SQL provider method.
    *
    * @return a type that implements an SQL provider method
+   * @since 3.5.2
+   * @see #type()
    */
-  Class<?> type();
+  Class<?> value() default void.class;
+
+  /**
+   * Specify a type that implements an SQL provider method.
+   * <p>
+   * This attribute is alias of {@link #value()}.
+   * </p>
+   *
+   * @return a type that implements an SQL provider method
+   * @see #value()
+   */
+  Class<?> type() default void.class;
 
   /**
    * Specify a method for providing an SQL.

src/main/java/org/apache/ibatis/builder/annotation/ProviderSqlSource.java

@@ -15,6 +15,8 @@
  */
 package org.apache.ibatis.builder.annotation;
 
+import java.lang.annotation.Annotation;
+import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
 import java.lang.reflect.Modifier;
 import java.util.Map;
@@ -59,7 +61,7 @@ public ProviderSqlSource(Configuration configuration, Object provider, Class<?>
       this.configuration = configuration;
       Lang lang = mapperMethod == null ? null : mapperMethod.getAnnotation(Lang.class);
       this.languageDriver = configuration.getLanguageDriver(lang == null ? null : lang.value());
-      this.providerType = (Class<?>) provider.getClass().getMethod("type").invoke(provider);
+      this.providerType = getProviderType(provider, mapperMethod);
       providerMethodName = (String) provider.getClass().getMethod("method").invoke(provider);
 
       if (providerMethodName.length() == 0 && ProviderMethodResolver.class.isAssignableFrom(this.providerType)) {
@@ -175,4 +177,21 @@ private String invokeProviderMethod(Object... args) throws Exception {
     return sql != null ? sql.toString() : null;
   }
 
+  private Class<?> getProviderType(Object providerAnnotation, Method mapperMethod)
+      throws NoSuchMethodException, InvocationTargetException, IllegalAccessException {
+    Class<?> type = (Class<?>) providerAnnotation.getClass().getMethod("type").invoke(providerAnnotation);
+    Class<?> value = (Class<?>) providerAnnotation.getClass().getMethod("value").invoke(providerAnnotation);
+    if (value == void.class && type == void.class) {
+      throw new BuilderException("Please specify either 'value' or 'type' attribute of @"
+          + ((Annotation) providerAnnotation).annotationType().getSimpleName()
+          + " at the '" + mapperMethod.toString() + "'.");
+    }
+    if (value != void.class && type != void.class && value != type) {
+      throw new BuilderException("Cannot specify different class on 'value' and 'type' attribute of @"
+          + ((Annotation) providerAnnotation).annotationType().getSimpleName()
+          + " at the '" + mapperMethod.toString() + "'.");
+    }
+    return value == void.class ? type : value;
+  }
+
 }

src/site/es/xdoc/java-api.xml

@@ -466,7 +466,9 @@ try (SqlSession session = sqlSessionFactory.openSession()) {
         <td>Estas anotaciones SQL alternativas te permiten especificar un nombre de clases y un método que devolverán la SQL que debe ejecutarse (Since 3.4.6, you can specify the <code>CharSequence</code> instead of <code>String</code> as a method return type).
           Cuando se ejecute el método MyBatis instanciará la clase y ejecutará el método especificados en el provider. You can pass objects that passed to arguments of a mapper method, "Mapper interface type", "Mapper method" and "Database ID"
           via the <code>ProviderContext</code>(available since MyBatis 3.4.5 or later) as method argument.(In MyBatis 3.4 or later, it's allow multiple parameters)
-          Atributos: type, method.  El atributo type es el nombre completamente cualificado de una clase.
+          Atributos: value, type y method.
+          El atributo value y type es el nombre completamente cualificado de una clase
+          (The <code>type</code> attribute is alias for <code>value</code>, you must be specify either one).
           El method es el nombre un método de dicha clase
           (Since 3.5.1, you can omit <code>method</code> attribute, the MyBatis will resolve a target method via the
           <code>ProviderMethodResolver</code> interface.

src/site/ja/xdoc/java-api.xml

@@ -478,7 +478,10 @@ try (SqlSession session = sqlSessionFactory.openSession()) {
         <td>これらのアノテーションは動的 SQL を生成するためのものです。実行時に指定されたメソッドが呼び出され、メソッドから返された SQL ステートメントが実行されます (MyBatis 3.4.6以降では、メソッドの返り値として <code>String</code> ではなく <code>CharSequence</code> を指定することができます)。
         マップドステートメントを実行する際、プロバイダーによって指定したクラスのインスタンスが作成され、指定されたメソッドが実行されます。
         なお、メソッド引数にはMapperメソッドの引数に渡したオブジェクトに加え、<code>ProviderContext</code>(MyBatis 3.4.5以降で利用可能)を介して「Mapperインタフェースの型」「Mapperメソッド」「データベースID」を渡すことができます。(MyBatis 3.4以降では、複数の引数を渡すことができます)
-        キー: <code>type</code>, <code>method</code>. <code>type</code> にはクラスオブジェクト、<code>method</code> にはメソッド名を指定します
+        キー: <code>value</code>, <code>type</code>, <code>method</code>.
+        <code>value</code> と <code>type</code> にはクラスオブジェクトを指定します
+        (<code>type</code> は <code>value</code> の別名で、どちらか一方を指定する必要があります)。
+        <code>method</code> にはメソッド名を指定します
         (MyBatis 3.5.1以降では、<code>method</code> 属性を省略することができます。その際MyBatisは、<code>ProviderMethodResolver</code> インタフェースを介して対象メソッドの解決を試み、
         対象メソッドが解決できない場合は、<code>provideSql</code>という名前のメソッドを代替メソッドとして利用します)。
         <span class="label important">NOTE</span> 次の章で、クリーンで可読性の高いコードで動的 SQL を構築するためのクラスについて説明します。

src/site/ko/xdoc/java-api.xml

@@ -600,8 +600,8 @@ try (SqlSession session = sqlSessionFactory.openSession()) {
         <td>실행시 SQL 을 리턴할 클래스 과 메소드명을 명시하도록 해주는 대체수단의 애노테이션이다 (Since 3.4.6, you can specify the <code>CharSequence</code> instead of <code>String</code> as a method return type).
 		매핑된 구문을 실행할 때 마이바티스는 클래스의 인스턴스를 만들고 메소드를 실행한다.
     Mapper 메서드의 인수인 "Mapper interface type" and "Database ID" 과 <code>ProviderContext</code>(Mybatis 3.4.5 부터) 를 이용한 "Mapper method" 로 전달 된 객체를 메서드 매개변수로 전달할 수 있다.(마이바티스 3.4이상에서는 복수 파라미터를 허용한다.)
-		사용가능한 속성들 : type, method.
-		type 속성은 클래스.
+		사용가능한 속성들 : value, type, method.
+		value and type 속성은 클래스 (The <code>type</code> attribute is alias for <code>value</code>, you must be specify either one).
 		method 속성은 메소드명이다
     (Since 3.5.1, you can omit <code>method</code> attribute, the MyBatis will resolve a target method via the
     <code>ProviderMethodResolver</code> interface.

src/site/xdoc/java-api.xml

@@ -514,7 +514,9 @@ try (SqlSession session = sqlSessionFactory.openSession()) {
         You can pass objects that passed to arguments of a mapper method, "Mapper interface type", "Mapper method" and "Database ID"
         via the <code>ProviderContext</code>(available since MyBatis 3.4.5 or later) as method argument.
         (In MyBatis 3.4 or later, it's allow multiple parameters)
-        Attributes: <code>type</code>, <code>method</code>. The <code>type</code> attribute is a class.
+        Attributes: <code>value</code>, <code>type</code> and <code>method</code>.
+        The <code>value</code> and <code>type</code> attribute is a class
+        (The <code>type</code> attribute is alias for <code>value</code>, you must be specify either one).
         The <code>method</code> is the name of the method on that class
         (Since 3.5.1, you can omit <code>method</code> attribute, the MyBatis will resolve a target method via the
         <code>ProviderMethodResolver</code> interface.

src/site/zh/xdoc/java-api.xml

@@ -467,8 +467,8 @@ try (SqlSession session = sqlSessionFactory.openSession()) {
           </ul>
         </td>
         <td>允许构建动态 SQL。这些备选的 SQL 注解允许你指定类名和返回在运行时执行的 SQL 语句的方法。（自从MyBatis 3.4.6开始，你可以用 <code>CharSequence</code> 代替 <code>String</code> 来返回类型返回值了。）当执行映射语句的时候，MyBatis 会实例化类并执行方法，类和方法就是填入了注解的值。你可以把已经传递给映射方法了的对象作为参数，"Mapper interface type" 和 "Mapper method" and "Database ID" 会经过 <code>ProviderContext</code> （仅在MyBatis 3.4.5及以上支持）作为参数值。（MyBatis 3.4及以上的版本，支持多参数传入）
-        属性有： <code>type</code>, <code>method</code>。
-        <code>type</code> 属性需填入类。
+        属性有： <code>value</code>, <code>type</code>, <code>method</code>。
+        <code>value</code> and <code>type</code> 属性需填入类(The <code>type</code> attribute is alias for <code>value</code>, you must be specify either one)。
         <code>method</code> 需填入该类定义了的方法名
         (Since 3.5.1, you can omit <code>method</code> attribute, the MyBatis will resolve a target method via the
         <code>ProviderMethodResolver</code> interface.