====== 전자정부 표준프레임워크 연동 가이드 ======

이 장에서는 전자정부프레임워크(이하 표준프레임워크) 개발환경 구성에 대한 내용을 설명합니다.\\ 표준프레임워크포털에서 제공하는 표준프레임워크를 다운로드 하여 설치하는 방법과 소프트베이스에서 제공하는 xFrame5_egov 프레임워크를 다운로드 하여 설치하는 방법을 설명합니다. 이미 표준프레임워크개발환경이 구성되어 있다면 다음 장으로 이동합니다.

  *표준프레임워크 설치
  *xFrame5_egov 프레임워크 설치

===== 전자정부프레임워크 설치 =====

xFrame5 와 표준프레임워크를 연동하기 위하여 표준프레임워크 개발환경을 설치 합니다.

전자정부프레임워크의 다운로드는 표준프레임워크포털(http://www.egovframe.go.kr/)에서 다운로드 할 수 있습니다. 개발환경 설치에 대한 내용은 [표준프레임워크 포털 > 개발 가이드 > 개발환경가이드] 메뉴의 내용을 참고합니다.

{{ .:egovframework_guide:00.png?nolink |}}

==== xFrame5_egov 프레임워크 설치 ===

===xFrame5_egov 프레임워크 개요 ===

xFrame5_egov 프레임워크는 표준프레임워크 환경에 xFrame5 를 적용하여 환경을 구성한 통합개발환경입니다. 표준프레임워크 3.6(변동가능), java, tomcat, xFrame5 UI 샘플프로젝트, java 샘플프로젝트를 포함한 압축파일로 제공합니다.

=== xFrame5_egov 프레임워크 다운로드 ===

xFrame5_egov 는 xFrame5 설치 페이지(http://technet.softbase.co.kr/wiki/install/egovframe_install)에서 **xFrame5_egov.zip**  파일을 다운로드 받습니다.

{{ .:egovframework_guide:49.png?nolink |}}

=== xFrame5_egov 프레임워크 설치 ===

C 드라이브에 “AppRoot” 디렉터리를 생성하고 다운받은 압축파일을 압축해제 합니다(권장)

다른 디렉터리에 설치하고자 할 경우 다음의 설정내용을 변경해야 합니다.

  *eclipse\eclipse.ini -> VM 옵션 수정 : java 설치 경로 변경
  *eclipse 기동 시 workspace 경로 변경
  *eclipse 환경설정 > maven 설정 : maven repository 경로 변경
  *eclipse 환경설정 > server > Server Runtime Environments : tomcat 설치 경로 변경

프로젝트 샘플 파일의 버전 변경이 있을 경우 최신버전으로 다운로드 합니다.

=== xFrame5_egov 프레임워크 구조 ===

디렉터리 구성내역은 아래와 같습니다.

{{ .:egovframework_guide:02.png?nolink |}}

|< 100% 200px - >|
^ 디렉터리 구분 ^ 설명 ^
|eclipse | 표준프레임워크 3.6 eclipse |
| java | java 설치 디렉터리 |
| repository | local maven 저장소 |
| was | tomcat 디렉터리 |
| workspace | sample 프로젝트를 포함한 eclipse workspace |
| xFrame5(옵션) | xFrame5 UI 개발 툴 디렉터리 |

===== 개발 환경 구성 =====

이 장에서는 개발 환경의 구성을 위해 샘플프로젝트의 다운로드 및 다운로드 된 프로젝트의 Import, 그 후 프로젝트 실행 등에 관해 기술합니다. xFrame5_egov 프레임워크를 설치한 경우 샘플프로젝트가 이미 생성되어 있기 때문에 프로젝트 실행 단계부터 진행합니다.

  *프로젝트 파일 다운로드
  *프로젝트 파일 Import
  *프로젝트 실행

==== 프로젝트 파일 다운로드 ====

샘플프로젝트는 xFrame5 설치 페이지(http://technet.softbase.co.kr/wiki/install/egovframe_install)에서 **xframe5_egov3.6-1.0.0.zip** 파일을 다운로드 받습니다.

{{ .:egovframework_guide:50.png?nolink |}}

개발환경 프로젝트 파일 : 이클립스에 import 하여 개발 진행용(java 파일)

xframe5_egov3.6-1.0.0.zip 파일의 세부 버전 정보는 다를 수 있습니다.

xframe5_egov3.6(표준프레임워크 버전)-1.0.0(세부 버전).zip

==== 프로젝트 파일 Import ====

이클립스의 상단메뉴에서 File > Import… 을 클릭합니다.

{{ .:egovframework_guide:04.png?nolink |}}

General > Existing Projects into Workspace 를 선택 후 Next 버튼을 클릭합니다.

select archive file 를 선택하고 Browse… 버튼을 클릭하여 다운로드 받은 압축 파일(xframe5_egov3.6-
1.0.0.zip)을 선택합니다.

{{ .:egovframework_guide:05.png?nolink |}}

Finish 버튼을 클릭하여 import 를 완료 합니다.

[프로젝트 import 후 프로젝트]

에러가 있다면 프로젝트 clean 을 수행합니다.

{{ .:egovframework_guide:06.png?nolink |}}

alt + F5 를 눌러 메이븐 업데이트를 실행 합니다.

{{ .:egovframework_guide:07.png?nolink |}}

[메이븐 업데이트 후 프로젝트]

==== 프로젝트 개요 ====

=== DB 환경 정보 ===

샘플화면을 동작시키기 위해서는 조회화면에 사용되는 EMP_INFO 테이블이 필요합니다. xframe5_egov3.6 샘플 프로젝트에서는 메모리 DB 인 HSQL 을 사용하여 해당 테이블이 구성되어있습니다. 데이터 베이스 구성내용은 src/main/resources/db/sampledb.sql 파일을 참조 바랍니다.

Database 변경은 src/main/resources/egovframework/spring/ context-datasource.xml 파일의 “dataSource”를 변경합니다.

=== web.xml 파일 변경사항 ===

샘플 화면의 엑셀 다운로드, 엑셀 업로드 기능을 수행하기 위해 서블릿이 등록되어 있습니다.

<sxh xml>
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:web="http://xmlns.jcp.org/xml/ns/javaee"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
    http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd http://xmlns.jcp.org/xml/ns/javaee
    http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" id="xadmin" version="2.4">

    <servlet>
        <servlet-name>XExcelDownload</servlet-name>
        <servlet-class>xexcel5.servlet.XExcelDownload</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>XExcelDownload</servlet-name>
        <url-pattern>/XExcelDownload</url-pattern>
    </servlet-mapping>
    <servlet>
        <servlet-name>XExcelUpload</servlet-name>
        <servlet-class>xexcel5.servlet.XExcelUpload</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>XExcelUpload</servlet-name>
        <url-pattern>/XExcelUpload</url-pattern>
    </servlet-mapping>

</web-app>
</sxh>

=== was 서버 등록 ===

본 가이드에서는 Tomcat 7.0 버전을 기준으로 설명합니다. Tomcat 7.0 은 아래 경로에서 다운로드 받을 수 있습니다.

https://tomcat.apache.org/download-70.cgi

Tomcat 의 다운로드가 완료 되었다면 아래 내용을 진행합니다.

이클립스 화면에서 Window > Preference 를 선택합니다. Server > Runtime Environments 화면에서 오른쪽 Add 버튼을 클릭합니다.

{{ .:egovframework_guide:09.png?nolink |}}

서버 등록창에서 Apache Tomcat v7.0 를 선택 한 뒤 Next 버튼을 클릭합니다.

{{ .:egovframework_guide:10.png?nolink |}}

Browse 버튼을 클릭해서 Tomcat 서버의 홈 디렉터리를 찾아서 선택합니다. 선택한 뒤에 Finish 버튼을 클릭해서 설정을 완료합니다.

{{ .:egovframework_guide:11.png?nolink |}}

Tomcat 서버를 등록합니다. 서버탭에서 No server are… 부분을 클릭하거나 오른쪽버튼 New > Server 를 선택합니다. 서버탭이 없다면 Window > Show View > Servers 를 클릭하여 서버탭을 추가합니다.

{{ .:egovframework_guide:12.png?nolink |}}

Tomcat v7.0 Server 를 선택하고 Finish 버튼을 클릭하여 서버등록을 완료합니다.

{{ .:egovframework_guide:13.png?nolink |}}

==== 프로젝트 실행 ====

=== was 서버 실행 ===

추가한 tomcat 서버를 우 클릭 한 후 Add and Remove 를 클릭하여 샘플프로젝트를 추가합니다.

{{ .:egovframework_guide:14.png?nolink |}}

서버를 실행하고 브라우저에 다음의 URL 로 접속 합니다.

http://localhost:8080/xframe5_egov3.6/index.jsp 또는 http://localhost:8080/xframe5_egov3.6/xframe5.do

[샘플 화면]

{{ .:egovframework_guide:15.png?nolink |}}

=== xFrame5 개발툴 실행 및 프로젝트 열기 ===

xFrame5 툴을 실행합니다. HTML5 모드가 선택되어 있는지 확인한 후 프로젝트 파일 우측에 “…” 버튼을 클릭하여 프로젝트 경로를 설정합니다.

이클립스 workspace 폴더가 C:\AppRoot\xFrame5_egov 폴더 아래에 위치한다면 프로젝트 파일의 경로는 다음과 같습니다.

C:\AppRoot\xFrame5_egov\workspace\xframe5_egov3.6\src\main\webapp\project\egovSample.xfd

프로젝트 경로가 설정되었다면 열기 버튼을 클릭합니다.

{{ .:egovframework_guide:16.png?nolink |}}

개발툴이 실행되었다면 개발툴에서 미리보기로 화면을 실행시키기 위해 HTML5 기본 URL 를 변경합니다.

도구 > 옵션을 클릭 후 [미리보기]탭을 선택 후 아래와 같이 IP 와 포트 등을 변경합니다.

HTML5 기본 URL : http://127.0.0.1:8080/xframe5_egov3.6/xframe5.do

{{ .:egovframework_guide:17.png?nolink |}}

[기타] 탭을 클릭 후 “Transaction 탭 보기” 및 “Transaction 탭 xTranMap 사용” 에 체크합니다.

{{ .:egovframework_guide:18.png?nolink |}}

[HTML5 프로젝트] 윈도우의 [Screen] 탭에서 xdataset5UpdateSample 화면을 더블 클릭하여 열고, F8 단축키로 화면 미리보기를 실행합니다.

{{ .:egovframework_guide:19.png?nolink |}}

=== 샘플 개발 화면 ===

프로젝트의 샘플개발화면에서는 직원번호, 직원이름, 직원나이를 이용하여 가상의 직원 정보를 조회하고 조회된 데이터를 수정하여 저장하는 기능을 수행합니다.

조회화면을 동작 시켰을 경우 아래와 같이 데이터가 조회 됩니다.

{{ .:egovframework_guide:20.png?nolink |}}

===== 화면 개발 =====

이 장에서는 xFrame5 솔루션의 xDataSet5 기능을 통하여 샘플 어플리케이션의 화면 부분을 개발합니다. 이 장에서 기술하는 내용은 아래와 같습니다.

  *샘플 어플리케이션 개요
  *데이터셋 설정
  *트랜잭션 정의
  *화면 폼 개발
  *UI 폼 이벤트 처리 개발

==== 샘플 어플리케이션 개요 ====
샘플 어플리케이션에서는 조회, 추가, 삭제, 저장 기능이 제공되며 이외에도 엑셀업로드, 엑셀 다운로드 기능이 포함되어 있습니다. 본 가이드에서는 조회기능까지만을 다루며 이외의 기능들은 제공하는 샘플 어플리케이션의 소스를 참고합니다.

참고로 xFrame5 개발에 필요한 가이드 문서들은 xframe5설치폴더의 doc 폴더 안에 있습니다.

==== 데이터셋 설정 ====

샘플 어플리케이션에서 사용되는 데이터 셋은 다음의 표와 같으며, 개발툴에서 “Transaction” 탭의 “xDataSet”탭을 선택하여 정의합니다.

{{ .:egovframework_guide:21.png?nolink |}}

=== DS_REQ 데이터셋 정의 ===

직원 정보를 조회하기 위한 검색조건 데이터를 저장하기 위한 데이터셋으로 다음과 같습니다.

{{ .:egovframework_guide:23.png?nolink |}}

=== DS_RES 데이터셋 정의 ===

직원 정보에 해당하는 DS_RES 의 칼럼 정보는 아래와 같습니다. (DS_RES_MAP, DS_RES_VO 동일)

{{ .:egovframework_guide:24.png?nolink |}}

===DS_CBO_DEMP 데이터셋 정의 ===

코드데이터인 직원의 부서코드정보에 해당하는 DS_CBO_DEPT 의 칼럼 정보는 아래와 같습니다

{{ .:egovframework_guide:25.png?nolink |}}

DS_CBO_DEPT 의 초기 데이터는 아래와 같습니다.

{{ .:egovframework_guide:26.png?nolink |}}

=== DS_CBO_TITLE 데이터셋 정의 ===

코드 데이터인 직원의 직책코드정보에 해당하는 DS_CBO_TITLE 의 칼럼 정보는 아래와 같습니다.

{{ .:egovframework_guide:27.png?nolink |}}

DS_CBO_TITLE 의 초기 데이터는 아래와 같습니다.

{{ .:egovframework_guide:28.png?nolink |}}

==== 트랜잭션 정의 ====

트랜잭션시 사용되는 URL 은 XDATASET_BASEURL 과 트랜잭션 ID 별로 설정한 URL 이 결합되어 설정됩니다.

여기서 XDATASET_BASEURL 은 webapp/index.js 파일에 다음과 같이 상대경로로 정의되어 있습니다.

<sxh javascript>
XDATASET_BASEURL : './', // 데이터셋 통신 기본 경로
</sxh>

화면에서 발생하는 트랜잭션을 정의하는 곳은 “Transaction” 탭의 “xTranMap” 탭에서 정의하며, 정의되는 트랜잭션은 아래와 같습니다.

=== xTranMap Info ===

{{ .:egovframework_guide:30.png?nolink |}}

=== xTranMap I/O 설정 ===

{{ .:egovframework_guide:31.png?nolink |}}

==== 화면 폼 개발 ====

설정한 데이터셋을 개발화면의 오브젝트에 연결 합니다.

{{ .:egovframework_guide:32.png?nolink |}}

화면 폼 및 데이터셋의 연관도에 대한 상세 설명은 아래의 표와 같습니다.

|< 100% 100px - >|
^  구분  ^  바인딩 정보  ^
|  1  | DS_EMP_AGE 의 검색조건 칼럼(EMP_NO, EMP_NAME, EMP_AGE). |
|  2  | DS_EMP_INFO 데이터셋을 그리드에 바인딩 |
|  3  | DS_EMP_INFO 데이터셋에서 각각의 칼럼별로 바인딩 |
|  4  | DS_CBO_DEPT 데이터셋을 이용한 PICKLIST 코드 바인딩 |
|  5  | DS_CBO_TITLE 데이터셋을 이용한 PICKLIST 코드 바인딩 |

=== 버튼 속성 정의 ===

개발화면의 버튼들의 속성을 정의합니다.

{{ .:egovframework_guide:33.png?nolink |}}

화면 폼 및 데이터셋의 연관도에 대한 상세 설명은 아래의 표와 같습니다.

^ 구분 ^ Name ^ 설명 ^
| 조회 | btn_search | 조회기능을 수행합니다. |
| 추가 | btn_insert | 그리드의 새 행을 추가합니다. |
| 삭제 | btn_delete | 그리드의 선택된 행을 삭제합니다. |
| 저장 | btn_updateUtil | 데이터 저장 기능을 수행합니다. |

==== UI 폼 이벤트 처리 개발 ====

=== 버튼 이벤트 처리 ===

조회 버튼을 클릭할 경우, 업무 서버와의 데이터 트랜잭션을 발생시킵니다. 각각의 버튼에 대한 “on_mouseup” 이벤트에 대한 처리 소스는 아래와 같습니다.

<sxh javascript>
/*
* 조회 버튼 이벤트 호출
*/
function btn_search_on_mouseup(objInst)
{
    screen.requestsubmit("TR_SELECT", true);
}

/*
* 추가 버튼 이벤트 호출
* 그리드에 행 추가
*/
function btn_insert_on_mouseup(objInst)
{
    grid.additem();
}

/*
* 삭제 버튼 이벤트 호출
* 그리드에 체크한 행 삭제
*/
function btn_delete_on_mouseup(objInst)
{
    grid.deletecheckedrow();
}

/*
* 저장 버튼 이벤트 호출
*/
function btn_updateUtil_on_mouseup(objInst)
{
    screen.requestsubmit("TR_UPDATE_UTIL", true);
}

/*
* mapid : requestsubmit() 함수를 호출할때, 첫번째 파라미터인 트랜잭션 MAP ID값
* result : 서버와의 데이터 수신에 대한 처리 결과 (Rmeart 참조)
* recv_userheader : 서버에서 setUserHeader 함수를 통해 설정한 데이터
* recv_code : 서버에서 setMessage()또는 setErrorMessage()로 설정한 코드
* recv_msg : 서버에서 setMessage() 또는 setErrorMessage()로 설정한 메세지
*/
function screen_on_submitcomplete(mapid, result, recv_userheader, recv_code, recv_msg)
{
    // 처리결과에 대한 내용을 표시
    fldMapId.settext(mapid);
    fldResult.settext(result);
    fldUserHeader.settext(recv_userheader);
    fldRecvCode.settext(recv_code);
    mulRecvMsg.settext(recv_msg);
}
</sxh>

===== 서버 개발 =====

이 장에서는 xFrame5 솔루션의 xDataSet5 기능을 통하여 샘플 어플리케이션의 서버 부분을 개발합니다. 이 장에서 기술하는 내용은 아래와 같습니다.

  *개발 방법 설명
  *개발 방법 별 컨트롤 파일 위치
  *개발 방법 별 관련 라이브러리
  *Service 파일 설명
  *DAO 파일 설명
  *ServiceImpl 파일 설명
  *SQL 파일 설명

=== 개발 방법 설명 ===

조회 시 서버의 Controller에서 xDataSet5 데이터를 변환하는 방식에 따라 구분 됩니다.

  -simple 방식 : xDataSet5를 직접 생성하고 DB조회 데이터도 setData API를 통해 설정하는 방식
  -view 방식 : xDataSet5를 xdataset5spring.jar의 XFrame5Util클래스를 이용해 생성하고, 응답 데이터 처리를 xdataset5util.jar의 XFrame5View를 사용하는 방식

이상의 내용을 표로 나타내면 아래와 같습니다.

^ 구분 ^ xDataSet5 생성 ^ 데이터 설정 ^ 응답데이터 처리 ^
| 기본(simple)방식 | new 로 직접생성 | setData API 사용 | returnData API 사용 |
| view 방식 | XFrame5util 사용 | XFrame5util 사용 | XFrame5util 사용 |

==== 개발 방법별 컨트롤 파일 위치 ====

방식에 따라 사용하는 Controller는 아래의 표와 같이 나누어져 있습니다.

|< 100% 200px - >|
^  구분  ^  방식명  ^  Controller 명  ^
|  1  |  simple 방식  |  SimpleXDataSet5Contoller  |
|  2  |  view 방식  |  ViewXDataSet5Contoller  |

Controller파일의 위치는 아래와 같습니다.

{{ .:egovframework_guide:34.png?nolink |}}

==== 개발 방법별 관련 라이브러리 ====

개발 방법에 따라 사용하는 라이브러리 파일이 다르게 필요하며, simple 방식을 사용한다면 xdataset5.jar 파일이 필요하고 view 방식을 사용한다면 xdataset5.jar, xdataset5-spring.jar, xdataset5-util.jar 파일이 필요합니다.

개발 방법에 따라 필요한 라이브러리 파일은 아래 표와 같습니다 (jar 파일의 버전정보는 표기하기 않음).

|< 100% 100px - >|
^  구분  ^  방식명  ^  필요한 라이브러리  ^
|  1  |  simple 방식  |  xdataset5.jar  |
|  2  |  view 방식  |  xdataset5.jar, xdataset5-spring.jar, xdataset5-util.jar  |


==== Service 파일 설명 ====

직원 정보 조회 처리 개발 부분에 대한 Service 는 아래와 같습니다.

<sxh javascript; highlight: [1, 3, 5, 7];>
public interface ExampleService {

    List<Map<String, Object>> selectMapListByStr(String strEmpName) throws Exception;

    List<Map<String, Object>> selectMapListByMap(Map<String, Object> empMap) throws Exception;

    List<ExampleVO> selectVOListByVO (ExampleVO exampleVO)throws Exception;
}
</sxh>

위의 소스에 대한 설명은 아래와 같습니다.

^  라인  ^ 설명 ^
|  1  | Service 용 interface 를 선언합니다. |
|  3  | String 을 파라미터로 받는 검색용 메소드를 선언합니다. |
|  5  | Map 을 파라미터로 받는 검색용 메소드를 선언합니다. |
|  7  | VO 를 파라미터와 리턴타입으로 사용하는 검색용 메소드를 선언합니다. |

==== DAO 파일 설명 ====

직원 정보 조회 처리 개발 부분에 대한 DAO 는 아래와 같습니다.

<sxh javascript; highlight: [1, 2, 4-14];>
@Repository("exampleDAO")
public class ExampleDAO extends EgovAbstractMapper {

    public List<Map<String, Object>> selectMapListByStr (String strEmpName) throws Exception {
        return selectList("sampleMapper.selectMapListByStr", strEmpName);
    }

    public List<Map<String,Object>> selectMapListByMap (Map<String, Object> empMap) throws Exception {
        return selectList("sampleMapper. selectMapListByMap", empMap);
    }

    public List<EmpInfoVO> selectVOListByVO(EmpInfoVO empInfoVO) throws Exception {
        return selectList("sampleMapper. selectVOListByVO", empInfoVO);
    }
}
</sxh>

위의 소스에 대한 설명은 아래와 같습니다.

^  라인  ^ 설명 ^
|  1  | 해당 class 를 DAO 용 Repository 로 등록합니다. |
|  2  | 표준프레임워크에서 제공하는 DAO 클래스를 상속받아 DAO 를 선언합니다. |
|  4~14  | SQL 파일에서 지정한 id 를 사용하여 DB 검색용 메소드를 구현합니다. |

==== ServiceImpl 파일 설명 ====

직원 정보 조회 처리 개발 부분에 대한 ServiceImpl 는 아래와 같습니다.

<sxh javascript; highlight: [1, 2-3, 5-6, 8-11, 13-17, 19-22];>
@Service("exampleService")
public class ExampleServiceImpl extends EgovAbstractServiceImpl
    implements ExampleService{

    @Resource(name = "exampleDAO")
    private ExampleDAO exampleDAO;

    @Override
    public List<Map<String, Object>> selectMapListByStr(String strEmpName)throws Exception {
        return exampleDAO.selectMapListByStr(strEmpName);
    }

    @Override
    public List<Map<String, Object>> selectMapListByMap (
        Map<String, Object> empMap)throws Exception {
        return exampleDAO.selectMapListByMap(empMap);
    }

    @Override
    public List<EmpInfoVO> selectVOListByVO(ExampleVO exampleVO)throws Exception {
        return exampleDAO.selectVOListByVO(exampleVO);
    }
}
</sxh>

위의 소스에 대한 설명은 아래와 같습니다.

^  라인  ^ 설명 ^
|  1  | 해당 class 를 Service 로 등록합니다. |
|  2 ~ 3  | Service 의 구현 클래스를 선언합니다. |
|  5 ~ 6  | ServiceImpl 에서 사용하는 DAO 를 설정합니다. |
|  8 ~ 11  | String 을 파라미터로 받는 검색용 메소드를 구현합니다. |
|  13 ~ 17  | Map 을 파라미터로 받는 검색용 메소드를 구현합니다. |
|  19 ~ 22  | VO 를 파라미터와 리턴타입으로 사용하는 검색용 메소드를 구현합니다. |

==== SQL 파일 설명 ====

직원 정보 조회 기능에 대한 SQL 은 아래와 같습니다

<sxh xml; highlight: [1, 3, 4-13, 16, 17-32, 35, 36-50];>
<mapper namespace="sampleMapper">

    <select id="selectMapListByStr" parameterType="String" resultType="Map">
    SELECT
        EMP_NAME, EMP_NO, EMP_AGE, DEPT_CODE, TITLE_CODE, MAIL_ADDR
    FROM
        EMP_INFO
    WHERE 1=1
        <if test="_parameter != null and _parameter != ''">
            AND EMP_AGE >= #{_parameter}
        </if>
    ORDER BY
        EMP_AGE ASC
    </select>

    <select id="selectMapListByMap" parameterType="Map" resultType="Map">
    SELECT
        EMP_NAME, EMP_NO, EMP_AGE, DEPT_CODE, TITLE_CODE, MAIL_ADDR
    FROM
        EMP_INFO
    WHERE 1=1
        <if test=" EMP_NO != null and EMP_NO != ''">
            AND EMP_NO = #{EMP_NO}
        </if>
        <if test=" EMP_NAME != null and EMP_NAME != ''">
            AND EMP_NAME = #{EMP_NAME}
        </if>
        <if test=" EMP_AGE != null and EMP_AGE != ''">
            AND EMP_AGE >= #{EMP_AGE}
        </if>
    ORDER BY
        EMP_AGE ASC
    </select>

    <select id="selectVOList" parameterType="empInfoVO" resultType="empInfoVO">
    SELECT
        EMP_NAME, EMP_NO, EMP_AGE, DEPT_CODE, TITLE_CODE, MAIL_ADDR
    FROM
        EMP_INFO
    WHERE 1=1
        <if test=" EMP_NAME != null and EMP_NAME != ''">
            AND EMP_NAME = #{EMP_NAME}
        </if>
        <if test=" EMP_AGE != null and EMP_AGE != ''">
            AND EMP_AGE >= #{EMP_AGE}
        </if>
        <if test="EMP_AGE != null and EMP_AGE != ''">
            AND EMP_AGE >= #{EMP_AGE}
        </if> ORDER BY
        EMP_AGE ASC
    </select>
</sxh>

위의 소스에 대한 설명은 아래와 같습니다.

^  라인  ^ 설명 ^
|  1  | DAO 에서 사용할 namespace 를 설정합니다. |
|  3  | DAO 에서 사용할 id 를 설정합니다.\\ 파라미터는 String 으로 지정하고 결과 타입은 Map 으로 지정합니다. |
|  4 ~ 13  | SELECT 문 Query 를 작성하고 파라미터는 ‘#{}’으로 감쌉니다.\\ 파라미터가 null 인 경우를 위해 if 태그를 사용합니다. |
|  16  | DAO 에서 사용할 id 를 설정합니다.\\ 파라미터와 결과 타입은 Map 으로 지정합니다. |
|  17 ~ 32  |SELECT 문 Query 를 작성하고 파라미터가 null 인 경우를 위해 if 태그를 사용합니다. |
|  35  | DAO 에서 사용할 id 를 설정합니다.\\ 파라미터와 결과 타입은 empInfoVO 로 지정합니다. |
|  36 ~ 50  | SELECT 문 Query 를 작성하고 파라미터가 null 인 경우를 위해 if 태그를 사용합니다 |

VO 사용시 sql-mapper-config.xml 파일에 alias 를 추가합니다.

<sxh xml; highlight: [8];>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE configuration PUBLIC "-//mybatis.org//DTD Config 3.0//EN" "http://mybatis.org/dtd/mybatis-3-config.dtd">

<configuration>
    <typeAliases>
		<typeAlias alias="egovMap" type="egovframework.rte.psl.dataaccess.util.EgovMap"/>
		<typeAlias alias="searchVO" type="egovframework.example.sample.service.SampleDefaultVO"/>
		<typeAlias alias="sampleVO" type="egovframework.example.sample.service.SampleVO"/>
    </typeAliases>
</configuration>
</sxh>

===== 기본 방식 =====

이 장에서는 xDataSet5 를 기본(simple)방식으로 제어하여 controller 를 개발합니다. 이 장에서 기술하는 내용은 아래와 같습니다.

  *Controller 파일 개략적 설명
==== Controller 파일 개략적 설명 ====

데이터셋 생성

HttpServletRequest, HttpServletResponse를 사용하여 XDataSet5를 직접 생성합니다.

<sxh javascript>
// XDataSet5오브젝트 생성
XDataSet5 xDataSet5 = new XDataSet5(request, response);
</sxh>

데이터 설정

xDataSet5 에 setData API 를 사용하여 조회 데이터를 직접 추가합니다.

<sxh javascript>
				xDataSet5.setData("DS_EMP_INFO", "EMP_NAME", nRow, String.valueOf(element.get("EMP_NAME")));
				xDataSet5.setData("DS_EMP_INFO", "EMP_NO", nRow, String.valueOf(element.get("EMP_NO")));
				xDataSet5.setData("DS_EMP_INFO", "EMP_AGE", nRow, String.valueOf(element.get("EMP_AGE")));
				xDataSet5.setData("DS_EMP_INFO", "DEPT_CODE", nRow, String.valueOf(element.get("DEPT_CODE")));
				xDataSet5.setData("DS_EMP_INFO", "TITLE_CODE", nRow, String.valueOf(element.get("TITLE_CODE")));
				xDataSet5.setData("DS_EMP_INFO", "MAIL_ADDR", nRow,String.valueOf(element.get("MAIL_ADDR")));
</sxh>

Response 방법

returnData API를 사용하여 화면으로 데이터를 response합니다.

<sxh javascript>
xDataSet5.returnData();	// response로 데이터 반환처리
</sxh>

이외의 자세한 소스는 SimpleXDataSet5Contoller.java 파일을 참고합니다.

===== view 방식 =====

이 장에서는 xDataSet5 를 view 방식으로 제어하여 controller 를 개발합니다. 이 장에서 기술하는 내용은 아래와 같습니다.

  *Controller 파일 개략적 설명

==== Controller 파일 개략적 설명 ====

데이터셋 생성
XFrame5Util의 xFrame5Map API를 사용하여 xDataSet5를 생성 후 map타입으로 변환하여 처리합니다.

<sxh javascript>
Map<String, Object> reqMap = XFrame5Util.xFrame5Map(request, response, model);
</sxh>

데이터셋 처리
변환된 Map 데이터를 반환하는 형태에 따라 3가지 API를 제공합니다.
    1. getDataString() : String 형태의 데이터 반환
        String strEmpName = XFrame5Util.getDataString(reqMap, "DS_REQ", 0, "EMP_AGE");
        reqMap 데이터에서 지정된 Row의 Column 데이터를 반환 합니다.
    2. getDataMap() : Map 형태의 데이터 반환
        Map<String,Object> empMap = XFrame5Util.getDataMap(reqMap, "DS_REQ", 0);
        reqMap 데이터에서 지정된 Row의 데이터를 Map 형태로 반환 합니다.
    3. getDataBean() : VO 데이터 반환
        ExampleVO exampleVO = (ExampleVO) XFrame5Util.getDataBean(reqMap, "DS_REQ", 0, ExampleVO.class);
        reqMap 데이터에서 지정된 Row의 데이터를 전달한 VO 형태의 데이터로 반환 합니다.

데이터 설정

XFrame5Util 의 setOutputData API 를 사용하여 ModelMap 에 조회데이터를 추가합니다.

<sxh javascript>
XFrame5Util.setOutputData("DS_RES", empList1, model);
</sxh>

Response 방법

xdataset5spring의 XFrame5View라는 커스텀뷰에서 response처리하게 하기 위해 return을 다음과 같이“xFrame5View”라는 ID값으로 설정합니다.

<sxh javascript>
xDataSet5.returnData();	// response로 데이터 반환처리
</sxh>

이외의 자세한 소스는 ViewXDataSet5Contoller.java 파일을 참고합니다.

==== dispatcher-servlet.xml 파일 설명 ====

=== xframe5view 빈추가 ===

xFrame5View 는 거래 시 사용되는 xDataSet5 를 화면으로 response 하기 위해 사용되는 자바 View 입니다.

XDataSet5 를 xDataSet5Util 라이브러리를 통해 제어할 시 아래의 xframe5View 와 beanNameViewResolver 가 선언되어 있어야 합니다.

<sxh xml>
<!-- dispatcher-servlet.xml 에 추가 -->
<bean id="xFrame5View" class="xdataset5spring.XFrame5View"/>
</sxh>

=== BeanNameViewResolver 빈추가 ===

컨트롤러에서 xFrame5View 빈으로 응답데이터를 전송하기 위해 등록합니다.

<sxh xml>
<!-- dispatcher-servlet.xml 에 추가 -->
<bean class="org.springframework.web.servlet.view.BeanNameViewResolver">
    <property name="order" value="0"/>
</bean>
</sxh>

===== spring-security =====

이 장에서는 샘플 프로젝트에 spring security 를 적용하고 xFrame5 에서 화면 처리 및 데이터 처리 방안에 대한 내용을 기술 합니다. spring security 기술자체에 대한 설명은 생략 합니다.

  *spring security 설정
  *CSRF TOKEN 처리 방법

==== Spring security 설정 ====

spring security 설정 파일 : egovframework/spring/context-security.xml

spring security 가 적용되어있는 표준프레임워크에서 xFrame5로 개발을 하기 위해서는 security 설정파일에 다음의 내용을 설정 합니다.

<sxh xml; highlight: [2-5, 8-11, 15, 18-19, 22-24, 27-35];>
<!—SPRING SECURITY 제외 설정 -->
<http pattern="/resources/**" security="none" />
<http pattern="/XExcelDownload" security="none" />
<http pattern="/XExcelUpload" security="none" />
<http pattern="/XFileDownload" security="none" />

<http auto-config="true" use-expressions="true">
    <form-login
        login-processing-url="/security/login"
        login-page="/security/loginPage.do"
        default-target-url="/xframe5.do"
    />

    <!-- CSRF(Cross-site request forgery) 설정 : 기본값 false -->
    <csrf disabled="false" />

    <!-- url 패턴설정 -->
    <intercept-url pattern="/security/**" access="permitAll" />
    <intercept-url pattern="/**" access="hasAnyRole('ROLE_USER')" />

    <!-- X-FRAME-OPTIONS -->
    <headers>
        <frame-options policy="SAMEORIGIN"/>
    </headers>
</http>

<authentication-manager>
    <authentication-provider>
     <user-service>
         <user name="user" password="user" authorities="ROLE_USER"/>
         <user name="guest" password="guest" authorities="ROLE_GUEST"/>
         <user name="admin" password="admin" authorities="ROLE_ADMIN"/>
     </user-service>
    </authentication-provider>
</authentication-manager>
</sxh>

위의 소스에 대한 설명은 아래와 같습니다.

^  라인  ^ 설명 ^
|  2 ~ 5  | Spring security 에서 인증을 거치지 않고 제외 할 패턴을 설정합니다\\ /resources/ : 리소스 디렉터리.\\ /XExcelDownload : 그리드 엑셀 다운로드 기능을 수행.\\ /XExcelUpload : 그리드 엑셀 업로드 기능을 수행. |
|  8 ~ 11  | security 인증 로그인 화면 설정(옵션)\\ login-processing-url= 로그인 처리 서비스 URL\\ login-page= 로그인 페이지 위치\\ default-target-url= 로그인 수행 후 접속할 URL |
|  15  | CSFR 사용 여부 설정.\\ spring security 에서는 기본값이 사용이며 비 활성화 하기 위해서는 해당 값을 true 로 설정. |
|  18 ~ 19  | URL 패턴의 접근 권한 설정. |
|  22 ~ 24  | X-FRAME-OPTIONS 설정\\ 해당 옵션은 ClickJacking 과 같은 공격을 무력화 하기 위해 사용하며 다음과 같은 옵션이 있다.\\ DENY : 해당 페이지는 frame 내에서 표시할 수 없다.\\SAMEORIGIN : 해당 페이지와 동일한 origin 에 해당하는 frame 내에서 표시를 허용한다.\\ ALLOW-FROM : 해당 페이지는 지정된 origin 에 해당하는 frame 내에서 표시할 수 있다.\\ xFrame5 에서 TAB 오브젝트를 생성하고 다른 화면을 링크 시키기 위해 SAMEORIGIN 옵션을 설정합니다.(미설정시 403 에러 발생)\\ 해당 옵션은 웹서버에 자체에 설정하는 방법도 존재합니다(서버 담당자 문의). |
|  27 ~ 35  | 임시 사용자 권한 롤 생성. |

로그인 페이지 코드( WEB-INF/jsp/securityLoginPage.jsp )

<sxh xml>
    <form name="f" action="./login" method="POST">
    <input name="${_csrf.parameterName}" type="hidden" value="${_csrf.token}"/>
        <table class="content">
            <tbody>
                <tr>
                    <td style="width: 20%; height: 24px;">User:</td>
                    <td style="width: auto;"><input type="text" name="username" value="" class="content"></td>
                </tr>
                <tr>
                    <td>Password:</td>
                    <td><input type="password" name="password" class="content"></td>
                </tr>
                <tr>
                    <td><input name="submit" type="submit" value="Login" class="content"></td>
                    <td>
                        <c:if test="${not empty SPRING_SECURITY_LAST_EXCEPTION}">
                            <font color="red" class="content">
                                    로그인 실패 : ${sessionScope["SPRING_SECURITY_LAST_EXCEPTION"].message}
                                <c:remove var="SPRING_SECURITY_LAST_EXCEPTION" scope="session"/>
                            </font>
                        </c:if>
                    </td>
                </tr>
            </tbody>
        </table>
    </form>
</sxh>

로그인 페이지 실행 화면( http://127.0.0.1:8080/xframe5_egov3.6/xframe5.do )

{{ .:egovframework_guide:42.png?nolink |}}

==== CSRF TOKEN 처리 방법 ====

=== 컨트롤러에서 토큰정보를 포함한 쿠키생성 ===

xFrame5 실행 화면을 호출하는 컨트롤러에서 csrf 토큰을 생성하고 생성한 토큰 정보를 쿠키에 추가해 응답합니다.

<sxh javascript; highlight: [6, 7-14, 20];>
@RequestMapping("/xframe5.do")
public Object xframe5(HttpServletRequest request,HttpServletResponseresponse, ModelMap model) {

    try {
        // Spring-security CSRF 인증 토큰 설정
        CsrfToken csrfToken = (CsrfToken)request.getAttribute(CsrfToken.class.getName());
        if (csrfToken != null) {
            // 쿠키에 설정하여 UI에서 처리
            Cookie csrfTokenCK = new Cookie("_csrf.token",csrfToken.getToken());
            Cookie csrfParameterCK = new Cookie("_csrf.parameterName", csrfToken.getParameterName());
            Cookie csrfTokenHeaderCK = new Cookie("_csrf.headerName", csrfToken.getHeaderName());
            response.addCookie(csrfTokenCK);
            response.addCookie(csrfParameterCK);
            response.addCookie(csrfTokenHeaderCK);
        }
    } catch (Exception e) {
        e.printStackTrace();
    }

    return "index";
}
</sxh>

위의 소스에 대한 설명은 아래와 같습니다.

^  라인  ^ 설명 ^
|  6  | CSRF 토큰을 생성합니다. |
|  7 ~ 14  | 토큰정보가 Null 이 아니면 쿠키를 생성하여 토큰정보를 설정합니다.\\ response 객체에 쿠키를 추가 합니다. |
|  20  | index.jsp 페이지로 이동합니다. |

=== UI 에서 데이터 처리시 TOKEN 정보 설정. ===

xFrame5 에서 데이터 처리 시 토큰정보를 포함하는 방법으로 헤더 정보에 포함 하는 방식과 post 데이터에 포함하는 방식의 API 를 제공합니다.

<조회화면 샘플 코드>

<code>
  * 쿠키에서 CSRF 토큰 정보 추출 : factory.getcookie() API

var token, tokenHeader, tokenParameter;
token = factory.getcookie("_csrf.token"); // 토큰 값
tokenHeader = factory.getcookie("_csrf.headerName"); // 토큰 헤더 네임
okenParameter = factory.getcookie("_csrf.parameterName"); // 토큰 파라미터 네임

    1. request 헤더 정보에 포함하는 방법(헤더 네임과 토큰 값 사용) : factory.setxtranhttpheader() API
    var strRequestHeader = {};
    strRequestHeader[tokenHeader] = token;
    factory.setxtranhttpheader(strRequestHeader);
    2. post 데이타에 포함하는 방법(파라미터네임과 토큰값 사용) : factory.setxtranpostdata() API
    var obj_post_data = {};
    obj_post_data[tokenParameter] = token;
    factory.setxtranpostdata(obj_post_data);

// 조회 처리 : screen.requestsubmit() API
screen.requestsubmit("TR_SELECT", true);
</code>

<request 헤더 정보에 포함 시>

{{ .:egovframework_guide:43.png?nolink |}}

<post 데이터에 포함 시>

{{ .:egovframework_guide:44.png?nolink |}}
===== XDataSet Encoding =====

이 장에서는 xFrame5 에서 XDataSet 으로 데이터 전송시에 데이터 Encoding 하는 방법에 대해 설명합니다.


  *XTRAN_DATAENCODING

==== XTRAN_DATAENCODING 실행 파라미터 설정 ====

xFrame5 실행 파라미터에 XTRAN_DATAENCODING 을 추가합니다.

파라미터에 설정할 수 있는 값은 true, false 두 가지 이며 기본값은 false 입니다.

true 일 경우 xFrame5 엔진에서 데이터 전송시에 XDataSet 데이터 영역은 BASE64 인코딩 하여 전송합니다.

[전송 데이터 예시]
<sxh javascript>
XTRAN_DATAENCODING : false
    XDATASET5:{"header":{"version":"VERSION_20150608","compress":true,"screenid":"SvnRepositoryList","
    screenno":"/EXT/SVN/SvnRepositoryList","trancode":""," ………………………….생략

XTRAN_DATAENCODING : true
    XDATASET5:JTdCJTIyaGVhZGVyJTIyJTNBJTdCJTIydmVyc2lvbiUyMiUzQSUyMlZFUlNJT05fMjAxNTA2MD
    glMjIlMkMlMjJjb21wcmVzcyUyMiUzQXRydWUlMkMlMjJzY3JlZW5pZCUyMiUn……………………..생략
</sxh>

서버에서 xdataset5.jar 파일을 사용하여 데이터 처리시 원본데이터로 Decode 하여 반환 합니다.

===== HtmlTagFilter(XSS Filter) =====

이 장에서는 xFrame5 에서 XSS(크로스사이트스크립팅) 방어방법에 대해 설명합니다.

  *XTRAN_XSSENCODING 실행 파라미터 설정

==== XTRAN_XSSENCODING 실행 파라미터 설정 ====

XTRAN_XSSENCODING 실행 파라미터는 크로스 사이트 스크립팅 공격을 방지하기 위해 xFrame5 에서 전송하는 데이터에 특정 문자열이 포함될 경우 자동 변환하여 전송합니다.

파라미터에 설정할 수 있는 값은 true, false 두 가지 이며 기본값은 false 입니다.

true 설정 시에 다음과 같은 문자열을 변경 처리합니다.

  *'<' : '&lt;'
  *'>' : '&gt;'
  *'&' : '&amp;'
  *'"' : '&quot;'
  *'\' : '&apos;'

XTRAN_XSSENCODING 파라미터가 설정되어 있을 경우 XDataSet 데이터 영역은 자동으로 BASE64 인코딩하여 전송합니다.