[Velocity] [번역중.. ] Developer's Guide

소개

Velocity는 Java기반의 템플릿 엔진이고, 개발자가 쉽게 생성하고, 그 형식의 문서를 만들 수 있고, 사용자의 데이터를 보여줄 수 있도록 지원하는 간단하고 강력한 개발 도구입니다. 이 가이드에서는 Velocity를 사용한 개발의 기본 개요에 대해서 설명해 갑니다. 그리고, Velocity의 사용법을 위해 2개의 주요한 사용법에 초점을 맞힙니다. :

Servlet 베이스 WWW 개발

일반적인 애플리케이션에서의 사용

Velocity를 사용해 당신의 Servelt에서 클래스에 기반한 VelocityServlet 클래스를 사용해 매우 쉽게 Servlet을 개발하는 것과

역할에서는 유틸리티 클래스를 사용해 애플리케이션 개발을 하는 것에 관하여, 여러분은 이들 사이에 본질적인 차이는 없다는 것을 알게될 것입니다.

시작에 앞서

 

이 정보는 Velocity 사이트와 문서의 어느 다른 곳에서 찾아내질지도 모릅니다만, 그것은 완전하게 여기에 포함되고 있습니다. Velocity를 여러분의 컴퓨터에서 실행하는 것은, 매우 간단합니다. 모든 디렉토리에서의 참조는 Velocity 배포 트리의 루트 상대 패스됨에 주의해 주십시오.

    1. Velocity 배포를 입수해 주십시오. release와, nightly snapshot와, 직접 CVS code repository 등을 이용하는 것이 가능합니다. 좋게 동작한다고는 생각합니다만, 하지만, 최신의 기능을 위해, nightly snapshot이 아마 최선의 방법이겠지요. 상세 정보는, 여기를 참조해 주십시오.

    2. Java 구축 툴인 Jakarta Ant 을 아직 인스톨 하지 않고 있는 경우에는, 우선 그것을 인스톨 해 주십시오. Velocity를 구축하는데 필요하고, Velocity를 사용하는것에도 필요합니다.

    3. 배포는 build 디렉토리로 이동합니다.

    4. ant <build target> 타입은 <build target> 이하의 내용 중 하나입니다. :

• jar bin 디렉토리에 완전한 Velocity jar를 생성합니다. 이 jar는, 'velocity-X. jar'라고 합니다. 여기에서의 「X」는, 현재의 버전 번호입니다. 이 jar는 Velocity에 대해 필수 종속을 필요로하지 않습니다. 여러분이 이 대상(target)을 사용한다면, 여러분은 반드시Jakarta Commons의 Collections 컴포넌트 jar을 얻어야 하고, 당신의 CLASSPATH (or WEB-INF/lib)를 포함시켜야 합니다. 여러분이 그 내장된 logging이나 템플릿 변환을 사용하는 것을 원한다면, 여러분의 CLASSPATH나 webapp의 WEB-INF/lib에 그 적절한 jar를 포함해야 합니다. 편의상, 여러분은 ORO나 Logkit, Commons Collections에 포함된 jar로 생성하기 위한 대상(target)으로 jar-dep로 사용할 수 있습니다.
• jar-dep Jakarta Avalon Logkit 패키지로부터 logging을 위해 필수 지원을 포함하고, Jakarta Commons으로 세부적인 환경을 지원하고, Jakarta ORO 패키지를 사용해서 웹매크로(WebMacro) 템플릿 변환을 필수지원하여, bin 디렉토리에 완전한 Velocity jar를 생성됩니다.
• jar-core bin 디렉토리에 'velocity-core-X.jar'라는 이름의 작은 사이즈의 Velocity jar를 생성합니다. 이 jar에는 Velocity 기능의 코어가 포함되고 있습니다만, Anakia, Texen 같은 유틸리티와, VelocityServer를 지원하는 기본 클래스는 예지는 포함되고 있지 않습니다. 그것은 정규 jar 와 같은 외부의 종속성 요구사항을 가지고 있습니다.
• jar-util 'velocity-util X.jar'라는 유틸리티 Velocity jar를 bin 디렉토리에 생성합니다. 이 jar는, 유틸리티 코드, 특히 Anakia, Texen과 WebMacro 템플릿 변환 유틸리티를 포함합니다. 그것은 정규 jar 와 같은 외부의 종속성 요구사항을 가지고 있습니다.
• jar-servlet 'velocity-servlet-X.jar'라는 유틸리티 Velocity jar를 bin 디렉토리에 생성합니다. 이 jar는, servlet 프로그래머를 위한 유틸리티 코드를 포함합니다. 그것은 정규 jar 와 같은 외부의 종속성 요구사항을 가지고 있습니다.
• jar-j2ee J2EE 지원을 필요로 하는 모든 컴포넌트를 포함하는 'jar' 대상처럼, 완전한 jar를 생성합니다. 현재, 이것은 org.apache.velocity.runtime.resource.loader.DataSourceResourceLoader만을 포함합니다. 일반적으로, 그것은 'velocity-j2ee-X.jar'라하고, bin 디렉토리에 있습니다. 주의: 만약 이 생성 대상을 사용하고 싶을 경우, 반드시 build/lib 디렉토리에 j2ee. jar를 복사(또는 링크)을 해 두어야 합니다. 우리는, 배포의 일부로써 그것을 제공하고 있지 않습니다. 좋은 소스는 http://java. sun. com/에 있습니다. 그것은 정규 jar 와 같은 외부의 종속성 요구사항을 가지고 있습니다.
• jar-J2EE-dep J2EE 지원하고, Jakarta Avalon Logkit으로 logging지원을 포함하고, 과 Jakarta ORO패키지로 부터 regexp 지원하는 완전한 jar를 생성합니다. 상기의 jar-deps 타겟을 참조해 주십시오.
• examples 은 예제 디렉토리에 있는 예제 프로그램으로 예제 코드를 생성합니다. 이것은 또, forumdemo 예제 프로젝트 생성의 생성 대상이 될 것 입니다.
• forumdemo 는 examples/forumdemo 디렉토리에 예제 웹에플리케이션을 생성합니다.
• docs 은, Velocity의 Anakia XML 변환 툴을 사용해 이들 문서를 docs 디렉토리에 생성합니다. stylesheets를 대신에 Velocity 템플릿를 사용하는 것이 가능합니다.－시도해 보세요! 주: 이 대상은, jakarta-site2 프로젝트가 jakarta-velocity 배포 디렉토리와 같은 디렉토리로에 위치하도록 해야 합니다. 이 대상의 상세한 정보는 build.xml 파일을 보세요.
• jar-src 모든 Velocity 소스코드를 하나의 jar에 정리되고, bin 디레크토리에 위치합니다.
• javadocs docs/api 디렉토리에 Javadoc클래스 문서로 생성됩니다.
• test (after jar) will test Velocity against it's testbed suite of test routines - test (jar 후에)는 테스트 루틴(일련의 작업)의  testbed 세트를 대비하여 Velocity를 테스트를 할 것입니다.
• help 이용 할 수 있는 생성 대상의 일람을 표시합니다.

    5. 반드시 필요하지는 않지만 , 생성을 테스트하는것은 좋은 생각입니다. 위에서 보여진 test 타겟을 사용해 주십시오.

    6. 그렇습니다.! Velocity는 사용될 준비가 되었습니다. 클래스 패스 또는 다른 적절한 장소에 jar를 둡니다(만약 servlet에서 사용하는 것이라면 webapp의 lib 디렉토리 등)

    7. 예를 실행해 보고 싶을 경우는, (처음의 경우에는 특히 권장합니다 ), ant examples를 통해 예제의 build를 사용하세요.

부록

 

Velocity는 collections과 같은 Java 2 API의 요소(elements)를 사용하고, Java 2 Standard Edition SDK (Software Development Kit)에 의해 생성됩니다. Velocity의 실행은 Java 2 Standard Edition RTE (Run Time Environment)(또는 물론 SDK를 사용할 수 있다.)가 사용되어진다.

Velocity는 또한 일반적인 기능성을 위해 몇몇의 패키지들에 의존합니다. 그들은 편의상 build/lib 디렉토리에 포함됩니다. 그러나 기본생성대상(:default build target) (위를 참조하세요.)에 그들은 포함되지 않습니다. 만약 기본생성대상(:default build target)을 사용하길 원한다면, 반드시 classpath에 의존(dependencies)을 추가해야 합니다.

• Jakarta Commons Collections - 필수.
• Jakarta Avalon Logkit - 옵션, 매우 공통적입니다. 만약 Velocity에서 기본 파일기반 logging을 사용한다면 필요합니다.
• Jakarta ORO - 옵션. the org.apache.velocity.convert.WebMacro template변경 유틸리티를 사용할 때 필요합니다.

리소스

대부분의 리소스와 예제를 프로그래머에게 이용할 수 있게하고, 우리는 당신이 우리의 예제를 보고, 문서와 소스코드를 보는 것을 권합니다. 이하는 훌륭한 소스의 일부입니다  :

유저와 개발자 커뮤니티 : mail-lists에 참가하여 주십시오.

Mail-list 보관소 : http://www.mail-archive.com라면 충분합니다. 검색박스에 'velocity' 낱말에 넣고 -user, -dev 보관소 둘다 보아 주십시오

소스 코드 : src/java/... : Velocity 프로젝트의 모든 소스 코드가 있습니다

애플리케이션 예제 1 : examples/app_example1 : 응용 프로그램에서 Velocity를 어떻게 사용하는가 보인 간단한 예제

애플리케이션 예제 2 :examples/app_example2 : Velocity 응용 유틸리티 클래스를 사용한 응용 프로그램에서 Velocity를 사용을 보여주는  간단한 예제

servlet 예제 : examples/servlet_example1 : servlet에서 Velocity를 사용하는 방법을 보인 간단한 예제

logger 예제 : examples/logger_example : 모든 로그 메시지를 수신하기 위해 Velocity를 등록하고, 고객 logging 클래스를 생성하는 방법을 보여주는 간단한 예

XML 예제 : examples/xmlapp_example : Velocity 템플릿을 사용하여 XML 문서 데이타에의 접근과 JDOM의 사용법이 간단한 예제. 문서 트리를 떠돌아 다니는 순환 Velocimacro의 데모를 포함합니다.

event 예제 : examples/event_example : Velocity 1.1의 API로 이벤트 운용을 사용한 예제

Anakia 에플리케이션 : examples/anakia : XML 데이타의 스타일시트 렌더링(stylesheet renderings)을 생성하기 위해 Velocity를 사용한 애플리케이션 예제

Forumdemo web app : examples/forumdemo : servlet 기반의 포럼 애플리케이션의 움직임 본보기 

문서 : docs : Velocity 프로젝트를 위해 html로 생성된 모든 문서

API 문서 : docs/api : Velocity 프로젝트를 위해 생성된 Javadoc 문서

템플릿 : test/templates : testbed 디렉토리에 템플릿의 큰 집합(collection), VTL(Velocity Template Language)의 사용법이 훌륭한 소스가 있습니다.

context example : examples/context_example : two examples showing how the Velocity context can be extended. For advanced users.

context 예제 : examples/context_example : Velocity context을 확장할 수 있는 방법을 보여주는 2개의 예제가 있습니다. 고급자용.

 

위의 모든 디렉토리의 참조는, 배포 루트 디렉토리의 상대 패스입니다.

Velocity 사용 방법

    'The Fundamental Pattern'

 

    응용프로그램과 servlet 에서 Velocity를 사용하는 경우 (또는 정확하게는 기타의 경우도 ), 이하의 것을 실행해야 합니다.

1. Velocity의 초기화. 이것은, Velocity를 위한 쌍방의 패턴을 사용할 때에 적용하고, Singleton과 마찬가로 '실행시 인스턴스 분리' (상세하게 붙어서는 하기 참조 ) 한 번만 실행합니다.
2. Context 오브젝트의 생성 (상세는 나중에..)
3. Context에 당신의 데이타 오브젝트의 추가
4. 템플릿의 선택
5. 출력을 생성하기 위해(때문에) 당신의 데이타와 템플릿의 머지('Merge')

    코드에서, org.apache.velocity.app.Velocity 클래스를 통해 Singleton 패턴을 사용하려면, 이렇게 합니다.

	import java.io.StringWriter; import org.apache.velocity.VelocityContext; import org.apache.velocity.Template; import org.apache.velocity.app.Velocity; import org.apache.velocity.exception.ResourceNotFoundException; import org.apache.velocity.exception.ParseErrorException; import org.apache.velocity.exception.MethodInvocationException; Velocity.init(); VelocityContext context = new VelocityContext(); context.put( "name", new String("Velocity") ); Template template = null; try { template = Velocity.getTemplate("mytemplate.vm"); } catch( ResourceNotFoundException rnfe ) {  // couldn't find the template } catch( ParseErrorException pee ) {  // syntax error : problem parsing the template } catch( MethodInvocationException mie ) {  // something invoked in the template // threw an exception } catch( Exception e ) {} StringWriter sw = new StringWriter(); template.merge( context, sw );

    이것이 기본적인 패턴입니다. 대단히 단순하지 않나요? 이것은, 일반적으로 당신이 템플릿을 렌더링하는데 Velocity를 사용할 때에 실행하는 것입니다. 당신은 아마도 당연히 이런 코드를 쓰고 있지 않을 것입니다.－우리는 servlet과 응용프로그램의 둘다를 위해서, 보다 간단하게 만들기 위해 도움되는 2∼3의 툴을 준비하고 있습니다. 이 가이드의 후반부에, 우리는 두개의 servlet에서 일반적인 애플리케이션 처럼 Velocity를 사용하는 것에 대해서 설명할 것입니다. 그리고, 우리는 쉽게 만들기 위해 제공하는 툴을 검토합니다. 어느쪽의 경우도 상기의 순서가 그 화면 뒤에서, 움직이고 있는 것은 사실입니다.

To Singleton Or Not To Singleton

    Velocity 1. 2 버젼이나 이후 버젼부터, 개발자는 현재 Velocity 엔진을 사용하기 위해, Singleton 모델과 Separte Instance 모델의  2개의 옵션이 있습니다.  어느쪽의 방법도 같은 Velocity 코드의 코어를 사용하고, Velocity에 의해 간단하게 당신의 Java 에플리케이션에 통합되는 것이 가능합니다.

    Singleton Model

 

    이것은 legacy  패턴, JVM(또는 Web 에플리케이션, depending)에서 하나의 Velocity 엔진의 instance가 모두 공유됩니다. 이것은 리소스의 공유와 지역적 설정을 위해 매우 편리한 방법입니다. 예컨대, 이것은 servlet 2. 2이후 버젼과 호환되는 독자적인 Velocity의 instance를 가질 수 있는 각각의 Web 에플리케이션이고,  템플릿, 로그, 기타 처럼 리소스 공유를 Web 에플리케이션의 servlet이 지원하는, web 에플리케이션에서 사용하기 위한 매우 적절한 모델입니다.

싱글 톤은, org.apache.velocity.app.Velocity 클래스에서 접근하는 것이 가능하고, 이하처럼 사용합니다.

	import org.apache.velocity.app.Velocity; import org.apache.velocity.Template; ... /* * Configure the engine - as an example, we are using  * ourselves as the logger - see logging examples  */ Velocity.setProperty( Velocity.RUNTIME_LOG_LOGSYSTEM, this); /* * now initialize the engine */ Velocity.init(); ... Template t = Velocity.getTemplate("foo.vm");

    Singleton 모델은, org.apache.velocity.servlet.VelocityServlet 베이스 클래스에서 사용되고, 유틸리티 클래스는, servlet을 간단하게 작성하기 위해 배포되는 것에 주의해 주십시오. 이 클래스를 확장하는 것은 Velocity를 사용하는 servlets를 쓰는 것이 가장 공통적이고편리한 방법입니다만, 다른 목적을 위해 이 클래스를 사용하지 않는 것은 당신의 자유입니다.

    Separate Instance

 

    새로운 1. 2버젼부터, Separate instance는 같은 JVM(또는 Web 에플리케이션 )에서 Velocity의 인스턴스를 대부분 생성, 설정,사용하는것을 지원합니다.

이것은 같은 에플리케이션에서 템플릿 디렉토리와, 로그, 기타 등의 설정을 분할하고 싶을 때에 도움이 됩니다. Separate instance를 사용하기 위해서는, org.apache.velocity.app.VelocityEngine 클래스를 사용합니다. 상기의 Singleton의 예제와 비슷한 예제가 있습니다.

	import org.apache.velocity.app.VelocityEngine; import org.apache.velocity.Template; ... /* * create a new instance of the engine */ VelocityEngine ve = new VelocityEngine(); /* * configure the engine. In this case, we are using  * ourselves as a logger (see logging examples..)  */ ve.setProperty( VelocityEngine.RUNTIME_LOG_LOGSYSTEM, this); /* * initialize the engine */ ve.init(); ... Template t = ve.getTemplate("foo.vm");

보이는것 처럼, 이것은 매우 심플하고 간단한 것입니다. 단순한 문법의 변경에서의 제외하고, Velocity를 사용하면 Singleton과 Separate instance의 요구때문에 당신의 에플리케이션과 템플릿의 고 레벨의 구조를 변경할 필요는 없습니다.

프로그래머로써, 당신이 사용해야 하는 클래스는 싱글 톤 모델을 사용하는 경우에는 org.apache.velocity.app.Velocity 클래스를, non-Singleton 모델 ('Separate instance')은 org.apache.velocity.app.VelocityEngine을 Velocity 내부에 영향을 미친다.

에플리케이션에서 org.apache.velocity.runtime 패키지의 internal Runtime, RuntimeConstants, RuntimeSingleton or RuntimeInstance 클래스를 결정해 사용하지 말아 주십시오. 이것들은 내부 사용만을 상정하고 있고, 오래지 않아 변경될 것입니다. 위에서 언급했듯이 당신이 사용할 클래스는 org.apache.velocity.app 패키지, 그리고 Velocity와 VelocityEngine 클래스입니다.

 만약 어느것이든지 그들 클래스로가 잘못되었거나 필요하다면, 변경을 제안하는 것에 주저하지 말아 주십시오－이들 클래스는 에플리케이션 개발자를 대상으로 합니다.

The Context

 

    The Basics

    'context'의 개념은, Velocity에 있어서 주요하고, 시스템의 일부의 사이에서 데이타 중심의 콘테이너를 이동시키는 공통의 테크닉입니다. context의 사고방식은 Java layer(혹은, 당신 프로그래머)와 template layer(또는 설계자(designer))사이에서 데이타의 'carrier'라 합니다. 프로그래머로써의 당신은, 다양한 타입(당신의 에플리케이션이 요구하는 것은 무엇이든지)의 오브젝트를 모으게 되고, context에서 그것들을 두게 됩니다. 설계자(designer), 이들 objects와 그들의 methods에, 그리고, properties는 references라는 template elements를 통해 접근 가능하게 되게 됩니다. 일반적으로, 당신은 에플리케이션의 자료를 결정하기 위해 설계자(designer)와 일하게 됩니다. 어떤 의미에서, 이것은 템플릿에서 접근하는 설계자(designer)를 위한 데이터 설정을 생성하는 'API'가 될 것입니다.

따라서, 개발 프로세스의 양상으로의 그것은 약간의 시간과 신중한 분석을 바치는 가치가 있습니다.