Update JavaDocs and add tests about @ExternalDomain

Author: nakamura-to

doma-core/src/main/java/org/seasar/doma/ExternalDomain.java

@@ -38,6 +38,9 @@
  *     }
  *
  *     public Salary fromValueToDomain(BigDecimal value) {
+ *         if (value == null) {
+ *             return null;
+ *         }
  *         return new Salary(value);
  *     }
  * }
@@ -46,7 +49,6 @@
  * <p>The annotated instance is required to be thread safe.
  *
  * @see DomainConverter
- * @see DomainConverters
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)

doma-core/src/main/java/org/seasar/doma/jdbc/domain/DomainConverter.java

@@ -15,14 +15,12 @@
  */
 package org.seasar.doma.jdbc.domain;
 
-import org.seasar.doma.DomainConverters;
 import org.seasar.doma.ExternalDomain;
 
 /**
- * A converter between domain objects and basic values.
+ * A converter interface for mapping between domain objects and their corresponding basic values.
  *
- * <p>The implementation class should be annotated with {@link ExternalDomain} and be registered to
- * {@link DomainConverters}.
+ * <p>The implementation class should be annotated with {@link ExternalDomain}.
  *
  * <pre>
  * &#064;ExternalDomain
@@ -33,31 +31,33 @@
  *     }
  *
  *     public Salary fromValueToDomain(BigDecimal value) {
+ *         if (value == null) {
+ *             return null;
+ *         }
  *         return new Salary(value);
  *     }
  * }
  * </pre>
  *
  * @see ExternalDomain
- * @see DomainConverters
- * @param <DOMAIN> the domain type
- * @param <BASIC> the basic type
+ * @param <DOMAIN> the type of the domain object
+ * @param <BASIC> the type of the basic value
  */
 public interface DomainConverter<DOMAIN, BASIC> {
 
   /**
-   * Converts from a domain object to a basic value.
+   * Converts a domain object into a basic value.
    *
-   * @param domain the domain object
-   * @return the basic value
+   * @param domain the domain object; must not be null
+   * @return the basic value; can be null
    */
   BASIC fromDomainToValue(DOMAIN domain);
 
   /**
-   * Converts from a basic value to a domain object.
+   * Converts a basic value into a domain object.
    *
-   * @param value the basic value
-   * @return the domain object
+   * @param value the basic value; can be null
+   * @return the domain object; can be null
    */
   DOMAIN fromValueToDomain(BASIC value);
 }

integration-test-common/src/main/resources/META-INF/org/seasar/doma/it/dao/ScriptDao/create-h2.script

@@ -33,6 +33,7 @@ CREATE TABLE TABLE_STRATEGY2(ID INTEGER NOT NULL PRIMARY KEY, "VALUE" VARCHAR(10
 CREATE TABLE TEAM(ID INTEGER NOT NULL PRIMARY KEY, NAME VARCHAR(20));
 CREATE TABLE PLAYER(ID INTEGER NOT NULL PRIMARY KEY, NAME VARCHAR(20), TEAM_ID INTEGER);
 CREATE TABLE COACH(ID INTEGER NOT NULL PRIMARY KEY, NAME VARCHAR(20), TEAM_ID INTEGER);
+CREATE TABLE ANIMAL(ID INTEGER NOT NULL PRIMARY KEY, NAME VARCHAR(20), AGE INTEGER);
 
 INSERT INTO DEPARTMENT VALUES(1,10,'ACCOUNTING','NEW YORK',1);
 INSERT INTO DEPARTMENT VALUES(2,20,'RESEARCH','DALLAS',1);

integration-test-common/src/main/resources/META-INF/org/seasar/doma/it/dao/ScriptDao/create-mssql.script

@@ -30,6 +30,7 @@ CREATE TABLE TABLE_STRATEGY5(ID INT NOT NULL PRIMARY KEY, [VALUE] VARCHAR(10));
 CREATE TABLE TEAM(ID INT NOT NULL PRIMARY KEY, NAME VARCHAR(20));
 CREATE TABLE PLAYER(ID INT NOT NULL PRIMARY KEY, NAME VARCHAR(20), TEAM_ID INT);
 CREATE TABLE COACH(ID INT NOT NULL PRIMARY KEY, NAME VARCHAR(20), TEAM_ID INT);
+CREATE TABLE ANIMAL(ID INT NOT NULL PRIMARY KEY, NAME VARCHAR(20), AGE INT);
 
 INSERT INTO DEPARTMENT VALUES(1,10,'ACCOUNTING','NEW YORK',1);
 INSERT INTO DEPARTMENT VALUES(2,20,'RESEARCH','DALLAS',1);

integration-test-common/src/main/resources/META-INF/org/seasar/doma/it/dao/ScriptDao/create-mssql2008.script

@@ -29,6 +29,7 @@ CREATE TABLE TABLE_STRATEGY5(ID INT NOT NULL PRIMARY KEY, [VALUE] VARCHAR(10));
 CREATE TABLE TEAM(ID INT NOT NULL PRIMARY KEY, NAME VARCHAR(20));
 CREATE TABLE PLAYER(ID INT NOT NULL PRIMARY KEY, NAME VARCHAR(20), TEAM_ID INT);
 CREATE TABLE COACH(ID INT NOT NULL PRIMARY KEY, NAME VARCHAR(20), TEAM_ID INT);
+CREATE TABLE ANIMAL(ID INT NOT NULL PRIMARY KEY, NAME VARCHAR(20), AGE INT);
 
 INSERT INTO DEPARTMENT VALUES(1,10,'ACCOUNTING','NEW YORK',1);
 INSERT INTO DEPARTMENT VALUES(2,20,'RESEARCH','DALLAS',1);

integration-test-common/src/main/resources/META-INF/org/seasar/doma/it/dao/ScriptDao/create-mysql.script

@@ -29,6 +29,7 @@ CREATE TABLE TABLE_STRATEGY2(ID INTEGER NOT NULL PRIMARY KEY, `VALUE` VARCHAR(10
 CREATE TABLE TEAM(ID INTEGER NOT NULL PRIMARY KEY, NAME VARCHAR(20));
 CREATE TABLE PLAYER(ID INTEGER NOT NULL PRIMARY KEY, NAME VARCHAR(20), TEAM_ID INTEGER);
 CREATE TABLE COACH(ID INTEGER NOT NULL PRIMARY KEY, NAME VARCHAR(20), TEAM_ID INTEGER);
+CREATE TABLE ANIMAL(ID INTEGER NOT NULL PRIMARY KEY, NAME VARCHAR(20), AGE INTEGER);
 
 INSERT INTO DEPARTMENT VALUES(1,10,'ACCOUNTING','NEW YORK',1);
 INSERT INTO DEPARTMENT VALUES(2,20,'RESEARCH','DALLAS',1);

integration-test-common/src/main/resources/META-INF/org/seasar/doma/it/dao/ScriptDao/create-oracle.script

@@ -33,6 +33,7 @@ CREATE TABLE TABLE_STRATEGY2(ID NUMERIC(8) NOT NULL PRIMARY KEY, "VALUE" VARCHAR
 CREATE TABLE TEAM(ID NUMERIC(8) NOT NULL PRIMARY KEY, NAME VARCHAR(20));
 CREATE TABLE PLAYER(ID NUMERIC(8) NOT NULL PRIMARY KEY, NAME VARCHAR(20), TEAM_ID NUMERIC(8));
 CREATE TABLE COACH(ID NUMERIC(8) NOT NULL PRIMARY KEY, NAME VARCHAR(20), TEAM_ID NUMERIC(8));
+CREATE TABLE ANIMAL(ID NUMERIC(8) NOT NULL PRIMARY KEY, NAME VARCHAR(20), AGE NUMERIC(8));
 
 CREATE INDEX IX_EMPLOYEE_1 ON EMPLOYEE (EMPLOYEE_NAME);
 

integration-test-common/src/main/resources/META-INF/org/seasar/doma/it/dao/ScriptDao/create-postgres.script

@@ -36,6 +36,7 @@ CREATE TABLE VERY_LONG_CHARACTERS_NAMED_TABLE(VERY_LONG_CHARACTERS_NAMED_TABLE_I
 CREATE TABLE TEAM(ID INTEGER NOT NULL PRIMARY KEY, NAME VARCHAR(20));
 CREATE TABLE PLAYER(ID INTEGER NOT NULL PRIMARY KEY, NAME VARCHAR(20), TEAM_ID INTEGER);
 CREATE TABLE COACH(ID INTEGER NOT NULL PRIMARY KEY, NAME VARCHAR(20), TEAM_ID INTEGER);
+CREATE TABLE ANIMAL(ID INTEGER NOT NULL PRIMARY KEY, NAME VARCHAR(20), AGE INTEGER);
 
 INSERT INTO DEPARTMENT VALUES(1,10,'ACCOUNTING','NEW YORK',1);
 INSERT INTO DEPARTMENT VALUES(2,20,'RESEARCH','DALLAS',1);

integration-test-common/src/main/resources/META-INF/org/seasar/doma/it/dao/ScriptDao/create-sqlite.script

@@ -29,6 +29,7 @@ CREATE TABLE TABLE_STRATEGY2(ID INTEGER NOT NULL PRIMARY KEY, "VALUE" VARCHAR(10
 CREATE TABLE TEAM(ID INTEGER NOT NULL PRIMARY KEY, NAME VARCHAR(20));
 CREATE TABLE PLAYER(ID INTEGER NOT NULL PRIMARY KEY, NAME VARCHAR(20), TEAM_ID INTEGER);
 CREATE TABLE COACH(ID INTEGER NOT NULL PRIMARY KEY, NAME VARCHAR(20), TEAM_ID INTEGER);
+CREATE TABLE ANIMAL(ID INTEGER NOT NULL PRIMARY KEY, NAME VARCHAR(20), AGE INTEGER);
 
 INSERT INTO DEPARTMENT VALUES(1,10,'ACCOUNTING','NEW YORK',1);
 INSERT INTO DEPARTMENT VALUES(2,20,'RESEARCH','DALLAS',1);

integration-test-common/src/main/resources/META-INF/org/seasar/doma/it/dao/ScriptDao/drop-h2.script

@@ -30,6 +30,7 @@ DROP TABLE TABLE_STRATEGY2;
 DROP TABLE TEAM;
 DROP TABLE PLAYER;
 DROP TABLE COACH;
+DROP TABLE ANIMAL;
 
 DROP SEQUENCE SEQUENCE_STRATEGY_ID;
 DROP SEQUENCE MY_SEQUENCE_STRATEGY_ID;