[CUBRIDMAN-57] Add manual for linking CUBRID and JBoss

ko/jboss_guide/datasource_setting.rst

@@ -0,0 +1,101 @@
+
+
+.. _datasource_setting:
+
+CUBRID DataSource 설정
+======================
+
+본문에 들어가기에 앞서 DataSource를 설정하기 위해서는 JDBC 드라이버가 설정이 되어있어야 한다.
+
+JDBC 드라이버 설치: :ref:`install_jboss`
+
+DataSource 역시 CUBRID JDBC 드라이버 등록과 마찬가지로 운영체제별로 큰 차이는 존재하지 않는다. 사용자가 편한 방법을 통해 진행하는 것을 추천한다.
+
+이 장에서는 non-XA DataSource를 설치하는 과정을 다루고 있다.
+
+DataSource 설정
+----------------
+
+JBoss-cli를 사용하여 설치
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. jboss-cli.sh(Windows는 jboss-cli.bat)을 실행한다.
+
+#. connect를 입력하여 서버에 접속하고 다음 명령어를 입력한다 ::
+
+    /subsystem=datasources/data-source=cubridDS:add(jndi-name="java:/cubridDS",connection-url="[CUBRID_URL]",driver-name=cubrid,user-name=[USER_NAME],password=[PASSWORD])
+
+#. 아래 명령어를 입력하여 테스트를 실행한다. ::
+
+    /subsystem=datasources/data-source=cubridDS:test-connection-in-pool
+
+    {
+        "outcome" => "success",
+        "result" => [true]
+    }
+
+#. 위처럼 메시지가 출력되면 등록에 성공한 것이다.
+
+웹 콘솔을 이용하여 설치
+^^^^^^^^^^^^^^^^^^^^^^^
+
+#. 브라우저를 통해 http://[SERVER_IP]:9990 로 접속한다.
+
+#. configuration -> SubSystems -> Datasources & Drivers -> DataSource 에서 추가 버튼을 선택한다.
+
+#. Custom을 선택한 뒤 Next를 눌러 진행한다.
+
+#. Attribute에서 아래와 같이 입력한다. ::
+
+    Name: [DATASOURCE_NAME]
+    JNDI Name: java:/[JNDI_NAME]
+
+#. JDBC Driver에서 아래와 같이 입력한다. ::
+
+    Driver Name: cubrid
+    Driver Module Name: com.cubrid
+    Driver Class Name: cubrid.jdbc.driver.CUBRIDDriver
+
+#. Connection에서 아래와 같이 입력한다. ::
+
+    Connection URL: [CONNECTION URL]
+    User Name: [USER_NAME]
+    Password: [PASSWORD]
+    Security Domain: [SECURITY_DOMAIN]
+
+#. Test Connection을 수행하여 결과를 확인한다.
+
+#. 성공하면 등록이 완료된 것이다.
+
+실패한 경우 Back 버튼을 눌러 설정에 문제가 있는지 검토한다.
+
+XML 파일을 직접 수정하여 설치
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. $[JBOSS_HOME]\\standalone\\configuration으로 이동한다.
+
+#. standalone.xml 파일을 편집기로 실행한다.
+
+#. datasources 태그를 찾는다.
+
+#. 다음과 같이 내용을 추가한다. ::
+
+    <datasource jndi-name="java:/cubridDS" pool-name="cubrid">
+        <connection-url>[CONNECTION_URL]</connection-url>
+        <driver-class>cubrid.jdbc.driver.CUBRIDDriver</driver-class>
+        <driver>cubrid</driver>
+        <security>
+            <user-name>[USER_NAME]</user-name>
+            <password>[PASSWORD]</password>
+        </security>
+    </datasource>
+
+#. 변경된 내용을 저장 후 종료한다.
+
+.. note ::
+
+    모든 설정 방법에서 사용되는 attribute는 jboss에 존재하는 attribute 중에 극히 일부만 기재되어있다.
+
+    사용자가 필요한 경우 환경에 맞게 property를 추가하여 사용하면 된다. 더 많은 옵션이 필요하면 이곳을 참고한다.: 
+
+    https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/7.3/html-single/configuration_guide/index#datasource_parameters

ko/jboss_guide/index.rst

@@ -0,0 +1,18 @@
+******************
+JBOSS 연동 가이드
+******************
+
+이 장에서는 CUBRID를 JBOSS와 연동하는 방식에 대하여 설명한다.
+
+CUBRID가 설치되어 있다는 가정하에 진행하므로 CUBRID를 미리 설치하는 것을 권장한다.
+
+CUBRID 설치 방법은 다음 페이지를 참고한다: :ref:`install-execute`\
+
+.. toctree::
+
+    info.rst
+    jdk_setting.rst
+    install_jboss.rst
+    jdbc_setting.rst
+    datasource_setting.rst
+    testing.rst

ko/jboss_guide/info.rst

@@ -0,0 +1,25 @@
+
+.. _jboss_info:
+
+JBOSS 소개
+==========
+
+JBOSS는 Java EE 스펙을 구현한 오픈소스 WAS 미들웨어이다.
+
+90년대 후반부터 프로젝트를 시작하여 2006년에 Red Hat이 인수하였고 커뮤니티가 개발하는 WildFly 버전과 WildFly에 기반하여 Red Hat이 성능과 안정성을 개선하여 제공하는 JBoss EAP 버전이 있다.
+
+두 버전의 대략적인 차이는 다음과 같다
+
+*   WildFly는 JBOSS EAP에 비해 업데이트 속도가 빠르다. 하지만 사용 중에 발생하는 문제에 대해 기술 지원을 받을 수 없어서 사용자가 모든 문제를 해결하여야 한다.
+
+*   JBoss EAP는 WildFly에 비해 업데이트가 느리다. 하지만 Red Hat이 직접 성능과 안정성을 개선하였고 사용중에 발생하는 문제에 대해 사후 지원 기간 동안 유료로 기술 지원을 받을 수 있다.
+
+두 가지 버전 중에 사용자의 개발, 운영 환경에 적합하다고 생각하는 버전을 선택하면 된다.
+
+이 장에서는 WildFly 17 버전으로 연동방법을 안내하고 있지만 WildFly 10 ~ 24 버전과 JBoss EAP 7.0.0 ~ 7.2.0 버전에서도 같은 방법으로 등록이 가능함을 확인하였다.
+
+매뉴얼에서 설명하는 것 외의 기능이나 설정이 궁금하다면 공식 홈페이지를 참고하기 바란다.
+
+*   WildFly 홈페이지: https://www.wildfly.org/
+
+*   JBoss EAP 홈페이지: https://www.redhat.com/ko/technologies/jboss-middleware/application-platform

ko/jboss_guide/install_jboss.rst

@@ -0,0 +1,108 @@
+
+
+.. _install_jboss:
+
+***********
+JBoss 설치
+***********
+
+앞서 설명한 대로 JBoss는 WildFly 17버전을 기준으로 설치를 진행한다.
+
+본문에 들어가기에 앞서 JBoss는 EAP 5 버전 이후부터 두 가지 서버 구동 모드(standalone, domain)가 있다. 
+
+standalone모드는 하나의 서버에 하나의 관리 프로세스가 생성되어 서버를 운영하는 방식이다. 이 방식은 서버가 많아질수록 관리사항이 같이 늘기 때문에 관리가 까다로워지지만, 서버를 각각 따로 설정, 제어가 가능하고 대규모 환경에서의 배포도 편리하다.
+
+domain모드는 관리자가 하나의 관리 프로세스를 통해 여러 서버를 동시에 제어할 수 있다. 하나를 통해 N개의 서버 관리가 가능하기 때문에 관리가 용이하지만, 그만큼 중앙서버 구성의 어려움과 각각의 서버에 대한 설정, 제어가 어려워진다는 단점이 있다.
+
+이 장에서는 standalone모드를 사용하여 서버를 설치, 시작, 종료하는 과정을 설명한다.
+
+JBoss 설치, 구동
+----------------------
+
+Linux
+^^^^^^^
+
+#. WildFly 17버전 파일을 다운받는다. ::
+
+    [wildfly@localhost]$ wget https://download.jboss.org/wildfly/17.0.0.Final/wildfly-17.0.0.Final.zip
+
+#. 다운받은 파일의 압축을 해제한다. ::
+
+    [wildfly@localhost]$ unzip wildfly-17.0.1.Final.zip
+
+#. [UNZIP_FILE_ROOT]/bin 으로 이동하여 add-user.sh를 실행한다
+
+    [wildfly@localhost]$ cd [UNZIP_FILE_ROOT]/bin
+    [wildfly@localhost]$ sh add-user.sh
+
+#. Management User를 선택한다.
+
+#. 등록할 관리자의 이름과 패스워드를 입력한다.
+
+#. 해당 사용자가 속할 그룹을 선택한다. 없다면 공백인 상태로 <Enter>를 눌러 진행한다
+
+#. 등록이 완료되었다면 standalone.sh를 실행하여 서버가 구동되는지 확인한다. ::
+
+    ...
+    [org.jboss.as] (Controller Boot Thread) WFLYSRV0025 WildFly Full 17.0.1.Final (WildFly Core 6.0.2.Final) started in 8727ms - Started 306 of 527 services ...
+
+위와 같은 문구가 마지막 줄에 출력되었다면 서버가 제대로 가동된 것이다. 웹 브라우저에서 http://[server_ip]:8080 로 접속하여 확인한다.
+
+Windows
+^^^^^^^^
+
+#. WildFly 17버전 파일을 다운받는다. ::
+
+    https://www.wildfly.org/downloads/
+
+#. 원하는 경로에 압축을 해제한다.
+
+#. $[JBOSS_HOME]\\bin의 add-user.bat을 실행한다.
+
+#. Management User를 선택한다.
+
+#. 등록할 관리자의 이름과 패스워드를 입력한다.
+
+#. 해당 사용자가 속할 그룹을 선택한다. 없다면 공백인 상태로 <Enter>를 눌러 진행한다.
+
+#. 등록이 완료되었다면 standalone.bat을 실행하여 서버가 구동되는지 확인한다. ::
+
+    ...
+    [org.jboss.as] (Controller Boot Thread) WFLYSRV0025: WildFly Full 17.0.0.Final (WildFly Core 6.0.2.Final) started in 6506ms - Started 306 of 527 services ...
+
+위와 비슷한 메시지가 출력되었다면 http://127.0.0.1:8080 으로 접속하여 서버가 성공적으로 기동 되었는지 확인한다.
+
+Linux와 Windows 공통으로 로컬 환경에서 웹 브라우저를 통해 접속하는 게 아닌 외부에서 브라우저를 통해 접근, 확인해야 하는 환경이라면 다음 절차를 추가로 시행한다.
+
+외부 브라우저에서 접속
+-----------------------
+
+#. $[JBOSS_HOME]/standalone/configuration/의 standalone.xml을 편집기로 실행한다.
+
+#. interface라고 적힌 부분을 찾아 아래와 같이 변경한다. ::
+
+    <interfaces>
+        <interface name="management">
+            <inet-address value="${jboss.bind.address.management:0.0.0.0}"/>
+        </interface>
+        <interface name="public">
+            <any-address/>
+        </interface>
+    </interfaces>
+
+#. 외부에서 브라우저를 통해 http://[server_ip]:8080 으로 접속하여 확인한다.
+
+JBoss 종료
+-----------
+
+종료 방법은 운영체제에 상관없이 비슷하다.
+
+#. 서버 실행 콘솔 화면에서 <Ctrl> + <c> 로 종료한다
+
+#. jboss-cli.sh (Windows의 경우 jboss-cli.bat)을 실행하고 명령어를 다음과 같이 입력한다. ::
+
+    [disconnected /] connect
+    [standalone@localhost:9990] shutdown
+    [disconnected /] exit
+
+

ko/jboss_guide/jdbc_setting.rst

@@ -0,0 +1,113 @@
+
+
+.. _jdbc_setting:
+
+CUBRID JDBC 설치
+================
+
+이 장에서는 JBoss에 큐브리드 JDBC를 설치하는 과정을 설명한다. CUBRID 11.0 버전이 설치되어 있다는 가정하에 진행되므로 CUBRID를 설치하고 본 매뉴얼을 읽는 것을 권장한다.
+
+설치 방법은 다음 문서를 참고한다: :ref:`install-execute`\
+
+JDBC 파일을 다운받는 경로는 다음과 같다: https://ftp.cubrid.org/CUBRID_Drivers/JDBC_Driver/JDBC-11.0-latest-cubrid.jar
+
+JDBC를 설치하는 방법은 운영체제에 영향을 크게 받지 않으므로 구분을 하지 않고 설명한다. 단 등록하는 방법의 차이가 있으므로 자신의 환경에서 편한 방법을 사용하는 것을 추천한다.
+
+JDBC 설치 방법
+---------------
+
+#. $[JBOSS_HOME]\\modules\\system\\layers\\base\\com\\cubrid\\main 로 이동한다.
+
+#. 해당 폴더로 CUBRID JDBC 파일을 이동시킨다.
+
+#. 같은 위치에 module.xml 파일을 생성한다.
+
+#. module.xml 파일의 내용을 다음과 같이 작성한다. ::
+
+    <?xml version="1.0" encoding="UTF-8"?>
+    <module xmlns="urn:jboss:module:1.5" name="com.cubrid">
+        <resources>
+            <resource-root path="JDBC-11.0-latest-cubrid.jar"/>
+        </resources>
+        <dependencies>
+            <module name="javax.api"/>
+            <module name="javax.transaction.api"/>
+        </dependencies>
+    </module>
+
+.. note::
+    base 디렉터리 밑에 사용자가 원하는 이름의 폴더를 생성하여 CUBRID JDBC 드라이버를 위치해도 된다. 단 경로의 끝에는 반드시 main 폴더가 있어야 하며 그 안에 JDBC 드라이버와 module.xml 파일이 있어야 JBoss가 드라이버를 인식한다.
+
+    예를 들어, 만약 사용자가 아래의 경로에 JDBC 드라이버를 위치한다면
+
+    $[JBOSS_HOME] \\ modules \\ system \\ layers \\ base \\ **driver \\ cubridjdbc \\ main**
+
+    module.xml 파일의 name 부분에도 수정된 경로를 반영해야 한다.
+
+    ...
+    <module xmls="urn:jboss:module:1.5" **name="driver.cubridjdbc"**>
+    ...
+
+jboss-cli를 사용하여 설치
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. standalone.sh(Windows의 경우 standalone.bat)을 실행한 뒤 jboss-cli를 실행한다.
+
+#. connect를 입력하여 서버에 연결한다.
+
+#. 아래의 명령어를 입력한다. ::
+
+    /subsystem=datasources/jdbc-driver=cubrid:add(driver-name=cubrid,driver-module-name=com.cubrid,driver-datasource-class-name=cubrid.jdbc.driver.CUBRIDDataSource,driver-xa-datasource-class-name=cubrid.jdbc.driver.CUBRIDXADataSource)
+
+#. 아래의 메시지가 출력되면 설치가 완료된 것이다. ::
+
+    {"outcome" => "success"}
+
+#. exit를 입력하여 jboss-cli를 종료할 수 있다.
+
+만약 에러 메시지가 표시될 경우 위의 JDBC 설치 경로 내용을 참고한다.
+
+웹 콘솔을 이용하여 설치
+^^^^^^^^^^^^^^^^^^^^^^^
+
+#. 브라우저를 통해 http://[SERVER_IP]:9990 로 접속한다.
+
+#. configuration -> SubSystems -> Datasources & Drivers -> JDBC Drivers에서 추가 버튼을 선택한다.
+
+#. 아래와 같이 내용을 입력한 뒤 **Add** 를 선택한다.
+
+    .. image:: ../images/jboss_jdbc_setting.png
+
+#. 등록이 성공적으로 완료되면 다음과 같은 내용을 확인 할 수 있다.
+
+    .. image:: ../images/jboss_jdbc_info.png
+
+
+XML 파일을 직접 수정하여 설치
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. $[JBOSS_HOME]\\standalone\\configuration으로 이동한다.
+
+#. standalone.xml 파일을 편집기로 실행한다.
+
+#. datasources 태그 밑의 drivers 태그를 찾는다.
+
+#. 다음과 같이 내용을 추가한다. ::
+
+    <drivers>
+        <driver name="h2" module="com.h2database.h2">
+            <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
+        </driver>
+        <driver name="cubrid" module="com.cubrid">
+            <driver-class>cubrid.jdbc.driver.CUBRIDDriver</driver-class>
+            <xa-datasource-class>cubrid.jdbc.driver.CUBRIDXADataSource</xa-datasource-class>
+            <datasource-class>cubrid.jdbc.driver.CUBRIDDataSource</datasource-class>
+        </driver>
+    </drivers>
+
+#. 변경된 내용을 저장 후 종료한다.
+
+기타
+^^^^^
+
+설치를 완료하면 즉시 적용이 되지만 혹시 모를 오류를 대비하여 서버를 reboot 하는 것을 추천한다.