1. SQL Map XML Configuration File

1.1 <settings> element

1.2 <typeAlias> Element

1.3 <transactionManager> Element

1.4 <dataSource> Element

1.4.1 SimpleDateSourceFactory

1.4.2 DbcpDataSourceFactory

1.4.3 JndiDataSourceFactory

1.5 <sqlMap> Element

1.6 SqlMap 파일 예

2. Mapped Statements

<statement id="statementName"
 [parameterClass="some.class.Name"]
 [resultClass="some.class.Name"]
 [parameterMap="nameOfParameterMap"]
 [resultMap="nameOfResultMap"]
 [cacheModel="nameOfCache"]
>
 select * from PRODUCT where PRD_ID = [?|#propertyName#]
 order by [$simpleDynamic$]
</statement>

xml에 정의하는 SQL 문장 중에 XML에서 사용되는 문자(<, > 등)가 포함되는 경우 아래와 같이 CDATA를 사용한다.

<statement id="getPersonsByAge" parameterClass=”int” resultClass="examples.domain.Person">
<![CDATA[
 SELECT *
 FROM PERSON
 WHERE AGE > #value#
 ]]>
 </statement>

2.1 Auto-Generated Keys

Data Mapper는 <insert> 문에 <selectKey>문을 이용하여 auto-generated key를 지원한다. <selectKey>는 pre-generated key(oracle sequence)와 post-generated key(MS-SQL 서버)를 모두 지원한다.

<!-Oracle SEQUENCE Example -->
<insert id="insertProduct-ORACLE" parameterClass="com.domain.Product">
<selectKey resultClass="int" >
 SELECT STOCKIDSEQUENCE.NEXTVAL AS ID FROM DUAL
 </selectKey>
 insert into PRODUCT (PRD_ID,PRD_DESCRIPTION)
 values (#id#,#description#)
</insert>

<!- Microsoft SQL Server IDENTITY Column Example -->
<insert id="insertProduct-MS-SQL" parameterClass="com.domain.Product">
 insert into PRODUCT (PRD_DESCRIPTION)
 values (#description#)
 <selectKey resultClass="int" >
 SELECT @@IDENTITY AS ID
 </selectKey>
 </insert>

2.2 Stored Procedures

<procedure> 문장을 통해 stored procedure를 제공한다. 아래 예는 output 파라미터를 갖는 SP가 어떻게 호출되는지 보여준다.

<parameterMap id="swapParameters" class="map" >
 <parameter property="email1" jdbcType="VARCHAR" javaType="java.lang.String"   mode="INOUT"/>
 <parameter property="email2" jdbcType="VARCHAR" javaType="java.lang.String"   mode="INOUT"/>
 </parameterMap>

 <procedure id="swapEmailAddresses" parameterMap="swapParameters"   >
 {call swap_email_address (?, ?)}
 </procedure>

2.3 parameterClass

<statement id=”statementName” parameterClass=” examples.domain.Product”>
 insert into PRODUCT values (#id#, #description#, #price#)
 </statement>

2.4 parameterMap

주의 !
dynamic mapped statements는 inline parameters만 지원하고 parameterMap과는 함께 사용될 수 없다.

parameterMap 속성의 개념은 JDBC PreparedStatement에 사용될 값들에 대한 ordered list를 정의하는 것이다.

<parameterMap id="insert-product-param" class="com.domain.Product">
 <parameter property="id"/>
 <parameter property="description"/>
 </parameterMap>

<statement id="insertProduct" parameterMap="insert-product-param">
 insert into PRODUCT (PRD_ID, PRD_DESCRIPTION) values (?,?);
 </statement>

2.5 Inline Parameters

<statement id="insertProduct" >
 insert into PRODUCT (PRD_ID, PRD_DESCRIPTION)
 values (#id#, #description#);
 </statement>

위의 예에서 inline parameter는 #id#와 #description#이다. inline parameter는 빈의 프로퍼티를 나타낸다.

2.6 resultClass

<statement id="getPerson" parameterClass=”int” resultClass="examples.domain.Person">
 SELECT
 PER_ID as id,
 PER_FIRST_NAME as firstName,
 PER_LAST_NAME as lastName,
 PER_BIRTH_DATE as birthDate,
 PER_WEIGHT_KG as weightInKilograms,
 PER_HEIGHT_M as heightInMeters
 FROM PERSON
 WHERE PER_ID = #value#
</statement>

위의 예에서 Person 클래스는 id, firstName 등과 같은 프로퍼티를 갖는다.
alias를 통해 컬럼의 값은 빈의 프로퍼티에 채워진다.

2.7 resultMap

<resultMap id="get-product-result" class="com.ibatis.example.Product">
 <result property="id" column="PRD_ID"/>
 <result property="description" column="PRD_DESCRIPTION"/>
 </resultMap>

<statement id="getProduct" resultMap="get-product-result">
 select * from PRODUCT
 </statement>

위의 예에서 SQL 쿼리의 result set은 resultMap 정의를 이용하여 Product 인스턴스로 맵핑된다. resultMap은 id 프로퍼티는 PRD_ID 컬럼의 값으로, description 프로퍼티는 PRD_DESCRIPTION 컬럼의 값으로 채워지도록 한다.
"select *"가 지원됨에 주의해야 한다. 이러한 기능은 result set에 반환된 모든 컬럼에 대한 맵핑을 정의할 필요는 없다는 것을 의미한다.

2.8 cacheModel

<cacheModel id="product-cache" imlementation="LRU">
 <flushInterval hours="24"/>
 <flushOnExecute statement="insertProduct"/>
 <flushOnExecute statement="updateProduct"/>
 <flushOnExecute statement="deleteProduct"/>
 <property name="size" value="1000" />
 </cacheModel>

<statement id="getProductList" parameterClass="int"   cacheModel="product-cache">
 select * from PRODUCT where PRD_CAT_ID = #value#
 </statement>

위의 예에서 product에 대해 정의된 캐쉬는 WEAK reference type을 사용한다. 이 캐쉬는 24 시간 마다 혹은 관련된 update 문장들이 수행될 때 마다 flush된다.

2.9 xmlResultName

<select id="getPerson" parameterClass=”int” resultClass="xml"   xmlResultName=”person”>
 SELECT
 PER_ID as id,
 PER_FIRST_NAME as firstName,
 PER_LAST_NAME as lastName,
 PER_BIRTH_DATE as birthDate,
 PER_WEIGHT_KG as weightInKilograms,
 PER_HEIGHT_M as heightInMeters
 FROM PERSON
 WHERE PER_ID = #value#
 </select>

위의 문장은 아래와 같은 구조를 갖는 XML 객체를 생성한다.

<person>
 <id>1</id>
 <firstName>Clinton</firstName>
 <lastName>Begin</lastName>
 <birthDate>1900-01-01</birthDate>
 <weightInKilograms>89</weightInKilograms>
 <heightInMeters>1.77</heightInMeters>
</person>

3. Parameter Maps and Inline Parameters

<parameterMap id="parameterMapName" [class="com.domain.Product"]>
   <parameter property ="propertyName" [jdbcType="VARCHAR"] [javaType="string"]
       [nullValue="NUMERIC"] [null="-9999999"]/>
   <parameter …… />
   <parameter …… />
</parameterMap>

class 속성은 optional이지만 사용하는 것이 좋다. parameterClass와 유사하게 class 속성은 프레임워크가 incoming parameter를 validate하고 성능을 위해 엔진을 최적화하도록 한다.

property

자바 빈의 프로퍼티

jdbcType

데이터베이스 컬럼 타입을 명시한다.

일반적인 컬럼이 nullable이면 필요 없지만 PreparedStatement.setNull(int parameterIndex, int sqlType) 메소드가 호출될 때는 필요하다. 어떤 데이터 타입에 대한 Null 값을 설정할 것인지 지정해야 하기 때문이다. 또한 명시적으로 데이터 타입을 지정한다는 점에서 유용하다. setNull 외에 Date 타입의 경우에도 유용하다. 자바는 java.util.Date 만을 제공하지만 대부분의 데이터베이스는 3개 정도의 date 관련 데이터 타입을 제공하기 때문에 명시적으로 지정하는 것이 좋다.

특히 오라클에서 컬럼 타입을 명시하지 않고 null을 설정하고자 할 때 "Invalid column type" 오류가 발생한다.

javaType

파라미터에 대한 자바 빈의 프로퍼티 타입을 지정한다.

일반적으로 이 타입은 빈의 프로퍼티 타입에서 reflection을 통해 자동으로 설정된다. 하지만 Map과 같은 타입은 프레임워크에 정확한 타입 정보를 제공할 수 없다. 만일 javaType이 설정되지 않았고 프레임워크가 타입을 결정할 수 없는 경우 타입은 Object로 간주된다.

nullValue

null을 표현할 수 없는 자바 빈의 프로퍼티에 대해 null 값을 정의하기 위해 사용된다.

아래는 parameterMap에 대한 예제이다.

<parameterMap id="insert-product-param" class="com.domain.Product">
   <parameter property="id" jdbcType="NUMERIC" javaType="int" nullValue="-9999999"/>
   <parameter property="description" jdbcType="VARCHAR" nullValue="NO_ENTRY"/>
</parameterMap>

<statement id="insertProduct" parameterMap="insert-product-param">
   insert into PRODUCT (PRD_ID, PRD_DESCRIPTION) values (?,?);
</statement>

3.1 Inline Parameter Maps

<statement id="insertProduct" parameterClass="com.domain.Product">
   insert into PRODUCT (PRD_ID, PRD_DESCRIPTION)
   values (#id#, #description#);
</statement>

<statement id="insertProduct" parameterClass="com.domain.Product">
   insert into PRODUCT (PRD_ID, PRD_DESCRIPTION)
   values (#id:NUMERIC#, #description:VARCHAR#);
</statement>

<statement id="insertProduct" parameterClass="com.domain.Product">
   insert into PRODUCT (PRD_ID, PRD_DESCRIPTION)
   values (#id:NUMERIC:-999999#, #description:VARCHAR:NO_ENTRY#);
</statement>

인라인 파라미터 맵을 사용할 경우에는 type 설정 없이 null value를 설정할 수는 없다.

3.2 Primitive Type Parameters

단지 파라미터로 사용하고자 자바 빈을 만드는 것은 바람직하지 않다. 이러한 경우 primitive type wrapper 객체(String, Integer, Date 등)를 사용한다.

<statement id="insertProduct" parameter="java.lang.Integer">
   select * from PRODUCT where PRD_ID = #value#
</statement>

3.3 Map Type Parameters

Map(HashMap, TreeMap 등)을 파라미터 객체로 사용하는 방법

<statement id="insertProduct" parameterClass="java.util.Map">
   select * from PRODUCT
   where PRD_CAT_ID = #catId#
   and PRD_CODE = #code#
</statement>

위와 같은 경우 Map에는 catId, code를 키로 갖는 값이 존재해야 한다.

4. Result Maps

<resultMap id="resultMapName" class="some.domain.Class" [extends="parent-resultMap"]>
   <result property="propertyName" column="COLUMN_NAME"
       [columnIndex="1"] [javaType="int"] [jdbcType="NUMERIC"]
       [nullValue="-999999"] [select="someOtherStatement"]
       />
   <result ……/>
   <result ……/>
   <result ……/>
</resultMap>

extends 속성은 선택적으로 사용되어 베이스로 삼을 다른 resultMap을 설정하기 위해 사용된다. super resultMap의 속성은 항상 sub resultMap의 속성 보다 먼저 insert 된다. 또 parent resultMap은 항상 child 보다 먼저 정의되어야 한다.

property

column

columnIndex

설정되었을 경우 jdbc 드라이버 구현에 따라 성능 향상을 얻을 수 있다.

jdbcType

javaType

nullValue

<resultMap id="get-product-result" class="com.ibatis.example.Product">
   <result property="id" column="PRD_ID"/>
   <result property="description" column="PRD_DESCRIPTION"/>
   <result property="subCode" column="PRD_SUB_CODE" nullValue="-999"/>
</resultMap>

select

select 속성은 객체와 자동으로 로딩되는 complex(user defined 등) 프로퍼티 타입 간의 관계를 서술하기 위해 사용된다. select 속성의 값은 다른 mapped statement의 이름이여야 한다. select 속성이 정의된 프로퍼티의 데이터베이스 컬럼은 반드시 지원되는 primitive type이여야 한다.