자바기반 Template 엔진 Velocity

Velocity란?

Velocity는 자바기반 Template 엔진이다.
Velocity를 사용함으로써 웹페이지 디자이너가 자바코드로 작성된 메소드를 참조할 수 있다. 또한 MVC모델을 적용시킨 웹사이트를 개발하기 위해 웹 디자이너와 자바 프로그래머가 병렬적으로 작업할 수 있다.
Velocity는 자바코드를 웹 페이지로부터 분리시킴으로써 유지보수가 용이하게 JSP나 PHP의 실용적인 대안을 제시한다.

Velocity의 설치방법

 Struts상에서 Velocity를 동작시키기 위해서는, Velocity의 서브 프로젝트인 Velocity Tools을 이용합니다. 설치수순은 아래와 같습니다.

1. velocity-tools-x.x.jar、velocity-dep-x.x.x.jar를, Web어플리케이션의 루트 디렉토리 아래 있는 WEB-INF\lib 폴더에 넣습니다.(x는 버전번호)
 
2. web.xml에 VelocityViewServlet을  배치하고 , .vm 확장자의 요청관련 설정을 합니다.(Velocity템플릿트의 확장자는, 통상 .vm 로 합니다.)

3. Velocity설정파일 velocity.properties를 준비합니다.

4. Velocity도구함 설정 파일 velocity-toolbox.xml을 준비합니다.

 우선, 이하의 URL에 따라, Velocity Tools의 바이너리(velociy-tools-x.xjar또는 velocity-tools-x.x.tar.gz)를 다운로드 해 주세요.

http://jakarta.apache.org/site/binindex.cgi#velocity-tools

 필요한 jar파일을 클래스패스에 추가

 위에 바이너리의 압축을 풀면 생기는 velocity-tools-x.x 폴더를, 이후 %VELOCITY% 라고 부릅니다. 우선 필요한 jar파일을 클라스패스에 옮깁니다. %VELOCITY%\lib 폴더에 있는 velcity-tools-x.x.jar와velocity-dep-x.x.x.jar를 Web어플리케이션 루트에 WEB-INF\lib 폴더에 복사 해주세요.

 web.xml에 VelocityViewServlet을 배치

 계속해서, Web어플리케이션의 web.xml에 VelocityViewServlet서블릿을 배치합니다. 이 서블릿은 Velocity템플릿트의 요청을 Velocity엔진에서 처리하기 위해서 입니다. web.xml에 아래와 같이 기술합니다.

web.xml
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/
j2ee/web-app_2_4.xsd" version="2.4">
……중략……
<servlet>
<servlet-name>velocity</servlet-name>
<servlet-class>
org.apache.velocity.tools.view.servlet.VelocityViewServlet
</servlet-class>
<init-param>
<param-name>org.apache.velocity.toolbox</param-name>
<param-value>/WEB-INF/velocity-toolbox.xml</param-value>
</init-param>
<init-param>
<param-name>org.apache.velocity.properties</param-name>
<param-value>/WEB-INF/velocity.properties</param-value>
</init-param>
<load-on-startup>10</load-on-startup>
</servlet>
……중략……
<servlet-mapping>
<servlet-name>velocity</servlet-name>
<url-pattern>*.vm</url-pattern>
</servlet-mapping>
……중략……
</web-app>

 초기화 파라미터에 대하여는, org.apache.velocity.toolbox 파라미터에, Velocity도구함의 설정파일의 장소를 지정합니다.  org.apache.velocity.properties 파라미터는, Velocity설정파일의 장소를 지정합니다.

 Velocity설정파일의 준비

 다음에, Velocity설정파일 velocity.properties을 준비합니다. 이것은, Velocity엔진의 동작을 제어하기 위한 설정파일입니다만, 이것이 없어도 Velocity엔진은 디폴트 설정으로 움직입니다. 파일의 설치장소는 위의 web.xml으로 지정한 장소 /WEB-INF/velocity.properties 입니다.

velocity.properties
＃runtime.log=velocity.log
＃runtime.log.logsystem.class=org.apache.velocity.runtime.log.AvalonLogSystem
input.encoding=EUC_KR
output.encoding=EUC_KR

 Velocity에서 설정가능한 프로퍼티는 꽤 여러가지가 있기 때문에, 여기서 모든 것을 소개하지는 못합니다. 또, 설정되어 있지 않은 프로퍼티에 대해서는 디폴트가 사용되어 지기 때문에, 필요한 프로퍼터 설정만 하면 됩니다. 여기서는, 로그의 출력 파일명 (runtime.log프로퍼티), 로그 시스템의 구현 클래스 (runtime.log.logsystem.class프로퍼티), 입력되는 템플릿트의 문장 인코딩(input.encoding프로퍼티), 출력되는 결과의 문자코드(output.encoding 프로퍼티)를 설정해 두었습니다.

 설정가능한 모든 프로퍼티를 알고 싶으시다면 , 공식사이트에 있는 Developer's Guide 의 10. Velocity Configuration Keys and Values를 참조해 주세요.

  Velocity도구함 설정 파일의 준비

 마지막으로 Velocity도구함 설정파일 velocity-toolbox.xml을 준비하고, web.xml에서 설정한 장소 (/WEB-INF/velocity-toolbox.xml) 에 설치합니다. 이 설정파일은 모든 템플릿에서 묵시적으로 사용가능 하고, 프라이머티브 형의 값이나 오브젝트가 들어간 변수를 등록해 두기 위한 파일 입니다. 그래서 이 설정파일을 도구함이라고 부릅니다.

각주 : 공식 사이트에서는, toolbox.xml이라고 하는 파일명을 사용합니다. 그러나 WEB-INF폴더에 넣어 두는 각종 설정파일은 프레임워크나 컨포넨트의 증가에 따라 늘어만 갑니다. 그래서 나중에 가면 어느 파일이 어느 것의 설정파일인가를 잃어버리는 경우가 있으므로 이 팁에서는 velocity-toolbox.xml 로 명명하는 것을 추천합니다.

velocity-toolbox.xml
<?xml version="1.0"?>
<toolbox>
<data type="number">
<key>version</key>
<value>1.1</value>
</data>
<tool>
<key>date</key>
<scope>application</scope>
<class>org.apache.velocity.tools.generic.DateTool</class>
</tool>
</toolbox>

 위의 샘플은, 수치형의 프라이머티브형 버전과 날짜 도구 DateTool의 오브젝트 date로 등록하고 있습니다. 이것들은, 템플릿트중에 $version $date 등으로 쓰는 것으로 접근 가능 합니다.

 velocity-toolbox.xml에서 쓸 수 있는 요소와 그 설명을 아래의 표로 정리했습니다.

요소            부모요소         설명
<toolbox>    -                  문서 루트
<data>        <toolbox>      수치/참거짓값/문자열등의 데이터등록. type속성에 number／boolean／string중 하나를 등록
<tool>        <toolbox>      오브젝트 등록
<key>       <data>、<tool>  템플릿트 참조를 위한 변수명
<value>       <data>           데이터 값
<class>      <tool>           오브젝트 클래스
<scope>       <tool>          오브젝트의 생존기간. application／session／request중에서 지정

이상으로 설정은 끝입니다.

 샘플 실행

 이하의 샘플 템플릿트를 Web어플리케이션 루트 바로 아래에 두고, 브라우져를 열어 봅시다.

sample.vm
<html>
<body>
#set($message = "Hello World!")
$message<br>
Velocity Version: $version<br>
$date
</body>
</html>

아래처럼 표시가 된다면, Velocity는 정상적으로 동작 하고 있습니다.

Hello World!
Velocity Version: 1.1
2008/08/08 20:08:08

Velocity 문법

 변수(Variables)와 #set 지시자(Directive)

Velocity Templating Language(VTL)는 변수들에 대한 단순한 규칙을 가지고 있다. Velocity는 템플릿내의 변수참조를 객체를 대표하는 문자(String)으로 변환한다.

만약 객체가 String이 아닐 경우, Velocity는 출력을 만들 변수로서 toString() 메소드를 호출하게 된다.

이는 기본적인 행위이며, 우리가 원하는 출력을 갖기 위해서 toString() 메소드를 오버라이드(override) 할 수도 있다.
=====================================
변수 명칭은 다른 프로그래밍 언어들과 유사하며, 명칭은 반드시 문자(대문자 또는 소문자)로 시작해야 한다.

그러나 뒤따라 오는 문자들은 문자, 숫자, underscores(_), hyphens(-)으로 구성될 수도 있다.
=====================================
변수에 값을 할당하기 위해서는 Velocity의 지시자를 사용할 필요가 있다. 모든 지시자의 접두어는 #(hash symbol)이다.

몇몇 지시자들은 Velocity 내부에 정의되어져 있고 Velocity Macros라 불리는 매크로(macros)를 이용해서 정의된 것도 있다.

#set 지시자는 Java 변수에 할당하는 것처럼 동일하게 특정 값을 할당한다.
=====================================
Velocity Template 예

----------------------------

#set ($dog = "Jindo")

The dog is named $dog.

----------------------------

Velocity Template의 결과는 The dog is named Jindo. 가 된다.
=====================================
* Quiet Reference Notation

Velocity는 Context 내에 변수가 존재하지 않으면 참조 변수명을 그대로 Display한다. 이는 원 Text 내에 참조를 포함하고 있기 때문이다. 간단한 예를 보자.

Velocity template: $pizza will not do anything special

Result: $pizza will not do anything special

만약 우리가 은밀한 참조 표기(Quiet Reference Notation)를 사용하게 되면 템플릿 엔진은 존재하지 않는 참조를 Display하지 않을 것이다. 이때는 exclamation point(!)를 dollor표시 뒤에 추가하면 된다.

Velocity template: $!pizza will hide itself

Result: will hide itself
=====================================

 문자 연결

Velocity 내의 새로운 문자에 2개 또는 그 이상의 문자들을 쉽게 할당할 수 있다. 특정 변수에 할당하기 위해서는 = 을 이용한다.

Velocity template

#set ($city = "Austin")

#set ($state = "Texas")
=====================================
#set ($address = "$city, $state")

This is the address : $address
=====================================
Result - This is the address : Austin, Texas
=====================================
또한 좀 더 세밀한 문자 표기가 가능하다. 레프런스 변수명을 {}로 둘러싸면 된다.

예를 들어

#set ($city = "Austin")

#set ($state = "Texas")

#set ($myAddress = "${city}isin$state")

This is the weird address: $myAddress

Result - This is the weird address: AustinisinTexas

만약 {}가 없다면 결과는 다음과 같다. This is the weird address: $cityisinTexas

Velocity에서 "+" 연산자는 산술 연산자로만 쓰이며 문자 연결시에는 사용할 수 없다.

문자열 연결을 하고자 할 경우에는 #set ($string3 = "$string1$string2") 형태로 사용해야 한다.

 주석 (Comments)

Velocity에서의 주석은 ##(double hash)가 라인 주석, #*.....*#가 multi-line 주석으로 사용한다.

사용 예는 아래와 같다.

Velocity template:

## line comment

Some text in the template

#* A two-line

block comment *#

Result:

Some text in the template

 Escapting Rules

템플릿 내부의 특수문자 사용을 하기 위해서는 backslash를 이용해서 표현한다.

사용 예.

Velocity template:

#set ($string = "something")

$string

\$string

Result:

something

$string

만약 $string이 변수 참조로 선언되어져 있지 않다면

$string

\$string

Velocity template:

#set ($hash = "#")

$hash$hash

Results:

##
=====================================

 Collections

Velocity는 다른 몇몇 Collection 타입을 다룰수 있다.(Collection, Map, Iterator, Enumeration, Arrays of objects)

Velocity는 내부적으로 #foreach...#end 지시자를 이용해서 Iterator 인스턴스를 사용한다.

collections와 maps, 객체로 부터 직접 Iterator를 가져오기 위해서 Iterator 인스턴스를 사용.

arrays와 enumerations를 위해서 Velocity 내부에 Iterator Interface를 구현한 객체내부에 array 또는 enumeration을 wrapping하고 있다.

#foreach 문 내에 Iterator 또는 Enumeration이 사용되었을 경우 log 파일에 warning 메시지가 표시될 수 있다. 가능한 Collection을 이용할 경우 Collection, Map 또는 array를 가능한 사용하도록 하자.

 Control Flow Directives

Velocity에서는 2가지의 흐름 지시자가 있다. (#if...#else...#elseif....#end 와 #foreach...#end)

이것은 Velocity를 아주 단순한 프로그래밍 언어로 만든다.

#if...#else...#elseif...#end

#if 지시자(directive)는 다른 언어의 if 문과 유사하다. #if 는 #elseif 또는 #else가 뒤따라오게 된다.

#end는 #if문을 종료한다. Velocity에서 지원되는 logical(or Boolean) operator는 AND(&&), OR(||), NOT(!)이 있다.

Velocity에서 #if 또는 #elseif 조건에서 평가는 3가지 규칙을 따른다.

1.Boolean 객체를 위한 값은 반드시 true여야 한다.

2.Context내에 참조변수가 없을 경우 Velocity는 false로 평가한다.변수에 의한 객체 참조가 null이 아닐 경우 조건은 true가 된다. 따라서 Context내의 변수들은 결코 null 이어서는 안됨을 기억해라.

3.문자열의 true, false는 현재 시점에 평가된다. 이것은 Velocity Macros라 불리는 매크로 내부에 arguments로 사용할 경우 유용하다.

사용 예. Velocity template:

#set ($pages = 5)

#if ($pages == 0)

    There are no pages to display.

#elseif ($pages = 1)

    This the only page.

#else

    There are $pages pages that can be shown.

#endif

Result: There are 5 pages that can be shown.
=====================================

사용 예. Velocity template:

#if ($novalue)
  No value - we won't see this
#else
  The novalue variable doesn't exist
#end

#set ($something = "something")
#if ($something)
  $something
#end

#if (true)
  This statement is true.
#else
  This statement is false.
#end

Result:

The novalue variable doesn't exist

something

This statement is true.
=====================================

Context내에 $notavariable변수가 없을 경우

사용 예. Velocity template:

#if (!true)
  This statement is true.
#else
  This statement is false.
#end

#if (true && $notavariable)
  This statement is true.
#else
  This statement is false.
#end

#if (true || $notavariable)
  This statement is true.
#else
  This statement is false.
#end
Result:

This statement is false.
This statement is false.
This statement is true.