구문을 실행하는 메소드

이 메소드들은 SQL 매핑 XML 파일에 정의된 SELECT, INSERT, UPDATE 그리고 DELETE 구문을 실행하기 위해 사용된다. 메소드 이름 자체가 그 역할을 설명하도록 명명되었다. 메소드 각각은 구문의 ID 와 파라미터 객체(원시타입, 자바빈, POJO 또는 Map)을 가진다.

<T> T selectOne(String statement, Object parameter)
<E> List<E> selectList(String statement, Object parameter)
<T> Cursor<T> selectCursor(String statement, Object parameter)
<K,V> Map<K,V> selectMap(String statement, Object parameter, String mapKey)
int insert(String statement, Object parameter)
int update(String statement, Object parameter)
int delete(String statement, Object parameter)

selectOne과 selectList의 차이점은 selectOne메소드는 오직 하나의 객체만을 리턴해야 한다는 것이다. 한개 이상을 리턴하거나 null 이 리턴된다면 예외가 발생할 것이다. 얼마나 많은 객체가 리턴될지 모른다면 selectList를 사용하라. 객체의 존재여부를 체크하고 싶다면 개수를 리턴하는 방법이 더 좋다. selectMap은 결과 목록을 Map으로 변환하기 위해 디자인된 특별한 경우이다. 이 경우 결과 객체의 프로퍼티 중 하나를 키로 사용하게 된다. 모든 구문이 파라미터를 필요로 하지는 않기 때문에 파라미터 객체를 요구하지 않는 형태로 오버로드되었다.

insert, update 그리고 delete 메소드에 의해 리턴되는 값은 실행된 구문에 의해 영향을 받은 레코드수를 표시한다.

<T> T selectOne(String statement)
<E> List<E> selectList(String statement)
<T> Cursor<T> selectCursor(String statement)
<K,V> Map<K,V> selectMap(String statement, String mapKey)
int insert(String statement)
int update(String statement)
int delete(String statement)

Cursor는 List와 동일한 결과를 보여주지만, 데이터를 반복문을 통해 지연로딩을 한다.

try (Cursor<MyEntity> entities = session.selectCursor(statement, param)) {
   for (MyEntity entity:entities) {
      // process one entity
   }
}

마지막으로 리턴되는 데이터의 범위를 제한하거나 결과를 핸들링 하는 로직을 부여할 수 있는 3개의 select 메소드가 있다.

<E> List<E> selectList (String statement, Object parameter, RowBounds rowBounds)
<T> Cursor<T> selectCursor(String statement, Object parameter, RowBounds rowBounds)
<K,V> Map<K,V> selectMap(String statement, Object parameter, String mapKey, RowBounds rowbounds)
void select (String statement, Object parameter, ResultHandler<T> handler)
void select (String statement, Object parameter, RowBounds rowBounds, ResultHandler<T> handler)

RowBounds 파라미터는 마이바티스로 하여금 특정 개수 만큼의 레코드를 건너띄게 한다. RowBounds클래스는 offset과 limit 둘다 가지는 생성자가 있다.

int offset = 100;
int limit = 25;
RowBounds rowBounds = new RowBounds(offset, limit);

가장 좋은 성능을 위해 결과셋의 타입을 SCROLL_SENSITIVE나 SCROLL_INSENSITIVE로 사용하라.

ResultHandler파라미터는 레코드별로 다룰수 있도록 해준다. List에 추가할수도 있고 Map, Set을 만들수도 있으며 각각의 결과를 그냥 던질수도 있다. ResultHandler로 많은 것을 할 수 있고 마이바티스는 결과셋을 다루기 위해 내부적으로 사용한다.

Since 3.4.6, ResultHandler passed to a CALLABLE statement is used on every REFCURSOR output parameter of the stored procedure if there is any.

인터페이스는 매우 간단하다.

package org.apache.ibatis.session;
public interface ResultHandler<T> {
  void handleResult(ResultContext<? extends T> context);
}

ResultContext파라미터는 결과 객체에 접근할 수 있도록 해준다.

ResultHandler를 사용할 때 유의해야 할 제약사항이 2개 있다:

• ResultHandler를 사용하여 호출된 메소드의 데이터는 캐싱 되지 않는다.
• 고급 resualtMap을 사용할 경우, 마이바티스는 객체를 완성하기 위해 여러 줄의 코드를 필요로 할 수 있다. ResultHandler를 사용할 때 받는 객체는 associations나 collections가 완전히 채워지지 않은 상태일 수도 있다.

배치 수정시 flush메소드

어떤 시점에 JDBC드라이버 클래스에 저장된 배치 수정구문을 지울(flushing(executing)) 방법이 있다. 이 방법은 ExecutorType을 ExecutorType.BATCH로 설정한 경우 사용가능하다.

List<BatchResult> flushStatements()

트랙잭션 제어 메소드

트랜잭션을 제어하기 위해 4개의 메소드가 있다. 물론 자동커밋을 선택하였거나 외부 트랜잭션 관리자를 사용하면 영향이 없다. 어쨌든 Connection인스턴스에 의해 관리되고 JDBC 트랜잭션 관리자를 사용하면 이 4개의 메소드를 사용할 수 있다.

void commit()
void commit(boolean force)
void rollback()
void rollback(boolean force)

기본적으로 마이바티스는 insert, update, delete 또는 affectData가 활성화된select 를 호출하여 데이터베이스가 변경된 것으로 감지하지 않는 한 실제로 커밋하지 않는다. 이러한 메소드 호출없이 변경되면 커밋된 것으로 보장하기 위해 commit 와 rollback 메소드에 true 값을 전달한다.

참고 MyBatis-Spring 과 MyBatis-Guice는 선언적인 트랜잭션 관리기법을 제공한다. 그래서 스프링이나 쥬스와 함께 마이바티스를 사용한다면 해당되는 메뉴얼을 꼭 참고하길 바란다.

세션 레벨의 캐시를 지우기

void clearCache()

SqlSession인스턴스는 update, commit, rollback 또는 close 할때마다 지워지는 로컬 캐시이다. 명시적으로 닫기 위해서는 clearCache()메소드를 호출할 수 있다.

SqlSession 을 반드시 닫도록 한다.

void close()

반드시 기억해야 하는 중요한 것은 당신이 열었던 세션을 닫아주는 것이다. 확실히 하기 위해 가장 좋은 방법은 다음과 같은 형태로 개발하는 것이다.

try (SqlSession session = sqlSessionFactory.openSession()) {
    // 다음의 3줄은 "어떤 작업을 하는"을 나타낸다.
    session.insert(...);
    session.update(...);
    session.delete(...);
    session.commit();
}

참고 SqlSessionFactory 처럼 SqlSession이 getConfiguration()메소드를 호출하여 Configuration 인스턴스를 얻을 수 있다.

Configuration getConfiguration()

Mappers 사용하기

<T> T getMapper(Class<T> type)

다양한 insert, update, delete 그리고 select 메소드는 강력하지만 다소 장황하고 타입에 안전하지 않다. 더군다나 IDE나 단위 테스트에 그다지 도움이 되지 않는 형태이다. 우리는 Mapper를 사용하는 예제는 이미 시작하기 섹션에서 봤다.

그러므로 매핑된 구문을 실행하기 위해 좀더 공통적인 방법은 Mapper클래스를 사용하는 것이다. Mapper클래스는 SqlSession 메소드에 일치하는 메소드와 간단히 연동된다. 다음의 예제 클래스는 몇가지 메소드 시그니처와 SqlSession에 매핑하는 방법을 보여준다.

public interface AuthorMapper {
  // (Author) selectOne("selectAuthor",5);
  Author selectAuthor(int id);
  // (List<Author>) selectList(“selectAuthors”)
  List<Author> selectAuthors();

  // (Map<Integer,Author>) selectMap("selectAuthors", "id")
  @MapKey("id")
  List<Author> selectAuthorsAsMap();
  // insert("insertAuthor", author)
  int insertAuthor(Author author);
  // updateAuthor("updateAuthor", author)
  int updateAuthor(Author author);
  // delete("deleteAuthor",5)
  int deleteAuthor(int id);
}

아주 간결하게 각각의 Mapper메소드 시그니처는 SqlSession 의 메소드 시그니처와 일치해야만 한다. String 파라미터 ID가 없지만 대신 메소드명은 매핑된 구문의 ID 와 같아야 한다.

추가로 리턴 타입은 기대하는 결과 타입과 일치해야만 한다. 원시타입과 Map, POJO 그리고 자바빈등 대부분의 타입이 지원된다.

참고 Mapper 인터페이스는 어떠한 인터페이스를 구현할 필요가 없고 어떠한 클래스를 확장할 필요도 없다. 메소드 시그니처는 관련된 매핑된 구문을 유일하게 확인하기 위해 사용될 수 있다.

참고 Mapper 인터페이스는 다른 인터페이스를 확장할 수 있다. 적절한 명명공간의 구문은 Mapper 인터페이스에 XML바인딩을 사용한다. 오직 하나의 제한점은 두개의 인터페이스에 같은 메소드 시그니처를 사용할 수 없다는 것이다.

mapper 메소드에 여러개의 파라미터를 전달 할 수 있다. 여러개의 파라미터를 전달하면 파라미터 목록의 위치에 따라 명명될 것이다. 예를 들면 #{param1}, #{param2} 기타 등등 이런 식이다. 만약 파라미터의 이름을 변경하고자 한다면 파라미터의 @Param(“paramName”)애노테이션을 사용할 수 있다.

쿼리 결과를 제한하기 위해 메소드에 RowBounds인스턴스를 전달 할 수 있다.

Mapper 애노테이션

이 프레임워크가 만들어진 이후로 마이바티스는 XML 기반의 프레임워크이다. 설정은 XML기반이고 매핑된 구문또한 XML 에 정의한다. 마이바티스 3 에서는 새로운 추가 옵션이 생겼다. 마이바티스 3 은 편리하고 강력한 자바 기반의 설정 API 를 제공한다. 설정 API 는 XML 기반의 마이바티스 설정의 기초가 된다. 이는 새로운 애노테이션 기반의 설정에도 그대로 적용된다. 애노테이션은 소개하는데 많은 시간이 할애하지 않아도 될 정도로 매핑된 구문을 구현하는 간단한 방법을 제공한다.

참고 자바 애노테이션은 복잡하고 유연해야 하는 경우에 대해서는 다소 제한적이다. 조사하는데 많은 시간이 소요됨에도 불구하고 가장 강력한 마이바티스 매핑은 애노테이션으로 처리되지는 못한다. C# 속성은 이러한 제한사항이 없어서 MyBatis.NET 버전은 XML 대안으로 자바보다 다소 더 풍부한 기능을 제공한다. 하지만 자바 애노테이션 기반의 설정이 장점이 없지는 않다.

사용가능한 애노테이션은 아래에서 설명한다.

Mapper애노테이션 예제

이 예제는 insert 하기전에 일련번호를 가져오기 위해 @SelectKey 애노테이션을 사용하는 것을 보여준다.

@Insert("insert into table3 (id, name) values(#{nameId}, #{name})")
@SelectKey(statement="call next value for TestSequence", keyProperty="nameId", before=true, resultType=int.class)
int insertTable3(Name name);

이 예제는 insert한 후에 값을 가져오기 위해 @SelectKey애노테이션을 사용하는 것으로 보여준다.

@Insert("insert into table2 (name) values(#{name})")
@SelectKey(statement="call identity()", keyProperty="nameId", before=false, resultType=int.class)
int insertTable2(Name name);

이 예제는 SqlSession#flushStatements()를 호출하기 위해 @Flush애노테이션을 사용했다.

@Flush
List<BatchResult> flush();

다음 예제는 @Results애노테이션의 id속성을 명시해서 결과매핑을 명명하는 방법을 보여준다.

@Results(id = "userResult", value = {
  @Result(property = "id", column = "uid", id = true),
  @Result(property = "firstName", column = "first_name"),
  @Result(property = "lastName", column = "last_name")
})
@Select("select * from users where id = #{id}")
User getUserById(Integer id);

@Results(id = "companyResults")
@ConstructorArgs({
  @Arg(column = "cid", javaType = Integer.class, id = true),
  @Arg(column = "name", javaType = String.class)
})
@Select("select * from company where id = #{id}")
Company getCompanyById(Integer id);

다음 예제는 Sql 프로바이더 애노테이션을 사용해서 파라미터 한개를 처리하는 방법을 보여준다.

@SelectProvider(type = UserSqlBuilder.class, method = "buildGetUsersByName")
List<User> getUsersByName(String name);

class UserSqlBuilder {
  public static String buildGetUsersByName(final String name) {
    return new SQL(){{
      SELECT("*");
      FROM("users");
      if (name != null) {
        WHERE("name like #{value} || '%'");
      }
      ORDER_BY("id");
    }}.toString();
  }
}

다음 예제는 Sql 프로바이더 애노테이션을 사용해서 파라미터 여러개를 처리하는 방법을 보여준다.

@SelectProvider(type = UserSqlBuilder.class, method = "buildGetUsersByName")
List<User> getUsersByName(
    @Param("name") String name, @Param("orderByColumn") String orderByColumn);

class UserSqlBuilder {

  // @Param애노테이션을 사용하지 않으면 매퍼 메소드와 동일한 인자를 정의해야만 한다.
  public static String buildGetUsersByName(
      final String name, final String orderByColumn) {
    return new SQL(){{
      SELECT("*");
      FROM("users");
      WHERE("name like #{name} || '%'");
      ORDER_BY(orderByColumn);
    }}.toString();
  }

  // @Param애노테이션을 사용한다면, 오직 사용할 인자만 정의할 수 있다.
  public static String buildGetUsersByName(@Param("orderByColumn") final String orderByColumn) {
    return new SQL(){{
      SELECT("*");
      FROM("users");
      WHERE("name like #{name} || '%'");
      ORDER_BY(orderByColumn);
    }}.toString();
  }
}

이 예제는 모든 매퍼 메소드에 SQL 프로바이더 클래스를 전역 설정으로 공유하는 방법을 보여준다. (3.5.6 버전부터 사용 가능):

Configuration configuration = new Configuration();
configuration.setDefaultSqlProviderType(TemplateFilePathProvider.class); // 모든 mapper 메소드에 공유할 시, SQL 프로바이더 클래스를 지정한다.
// ...

// sql provider 애노테이션에서 type/value 속성을 생략할 수 있다.
// 생략시, 마이바티스는 defaultSqlProviderType으로 지정된 클래스를 적용한다.
public interface UserMapper {

  @SelectProvider // @SelectProvider(TemplateFilePathProvider.class) 와 동일하다.
  User findUser(int id);

  @InsertProvider // @InsertProvider(TemplateFilePathProvider.class) 와 동일하다.
  void createUser(User user);

  @UpdateProvider // @UpdateProvider(TemplateFilePathProvider.class) 와 동일하다.
  void updateUser(User user);

  @DeleteProvider // @DeleteProvider(TemplateFilePathProvider.class) 와 동일하다.
  void deleteUser(int id);
}

이 예제는 ProviderMethodResolver의 기본 구현 사용법을 보여준다.(MyBatis 3.5.1 버전 이상부터 사용가능):

@SelectProvider(UserSqlProvider.class)
List<User> getUsersByName(String name);

// provider 클래스에서 ProviderMethodResolver 를 구현한다.
class UserSqlProvider implements ProviderMethodResolver {
  // In default implementation, it will resolve a method that method name is matched with mapper method
  // 기본 구현에서, 메소드 이름이 mapper 메소드와 일치하는 경우 해당 메소드를 찾는다.
  public static String getUsersByName(final String name) {
    return new SQL(){{
      SELECT("*");
      FROM("users");
      if (name != null) {
        WHERE("name like #{value} || '%'");
      }
      ORDER_BY("id");
    }}.toString();
  }
}

이 예제는 statement 애노테이션에서 databaseId 속성이 어떻게 활용되는지를 보여준다(3.5.5 버전부터 사용 가능):

@Select(value = "SELECT SYS_GUID() FROM dual", databaseId = "oracle") // DatabaseIdProvider가 "oracle"을 제공하면 이 구문을 사용한다.
@Select(value = "SELECT uuid_generate_v4()", databaseId = "postgres") // DatabaseIdProvider가 "postgres"를 제공하면 이 구문을 사용한다.
@Select("SELECT RANDOM_UUID()") // DatabaseIdProvider가 설정되지 않았거나 일치하는 databaseId가 없는 경우 이 구문을 사용한다.
String generateId();