User guide - RTFTempate integration

RTFTempate integration

Before integrating RTFTemplate, you must understand generation process of RTFtemplate.

Here the two "well practices" to integrate RTFTemplate :

  • XML file of available fields (*.fields.xml) must be used while the merge of the JAVA context with RTF model. When you want integrate RTFtemplate, you must use this file to know informations about each fields (type list or not) and not the JAVA context. Indead with this file, RTFTemplate avoid executing introspection on the context (to know if field is type list or not), but it avoid having trouble when your context have not the whole of the JAVA object.
  • Swith edition RTF to do in your application, generation process can be optimized. The two steps can be avoided by caching transformed RTFDocument.

The 3 steps of generation process of RTFtemplate can be configured ou re-implemented. The 3 steps are represnted by interfaces :

RTFTemplate can be configurated with Spring descriptor.

RTFTemplate can be integrated into an application type of rich client or type of WEB.

RTFTemplate using

Here basic JAVA code to use RTFTemplate : 

  String rtfSource = "usecases/models/jakartavelocityproject/jakarta-velocity-model.rtf";
  String rtfTarget = "jakarta-velocity-model.rtf.rtf";

  // 1. Get default RTFtemplateBuilder
  RTFTemplateBuilder builder = RTFTemplateBuilder.newRTFTemplateBuilder();            
    
  // 2. Get RTFtemplate with default Implementation of template engine (Velocity) 
  RTFTemplate rtfTemplate = builder.newRTFTemplate();    
  
  // 3. Set the RTF model source 
  rtfTemplate.setTemplate(new File(rtfSource));  
  
  // 4. Put the context           
  rtfTemplate.put("project", new Project("Jakarta Velocity project"));
  ...    
  
  // 5. Merge the RTF source model and the context  
  rtfTemplate.merge(rtfTarget);

Here dscription of this code :

  • 1. get RTFTemplateBuilder instance . This instance contains the configuration of RTFTemplate to use, on other words the interface implementation IRTFDocumentParser, IRTFDocumentTransformer, et ITemplateEngine to use.
  • 2. get RTFTemplate instance with instance of RTFTemplateBuilder.
  • 3. set the RTF model source to use.
  • 4. put JAVA object into context.
  • 5. execute the 3 steps of the generation process, parsing, transformation et execution of the template engine.

rtfTarget file is the result of process generation of RTFTemplate(merge RTF source model with JAVA object context).

XML file of fields available using

If you use RTFTemplate into WEB application, click here, otherwise click here.

Process optimization

If you want optimize RTFTemplate into WEB application, click here, otherwise click here.

RTFTemplate modular

RTFTemplate is modular, each steps of the process generation can be implemented with class from RTFTemplate or with your implementation.

Implementation and Interfaces

IRTFDocumentParser interface

IRTFDocumentParser interface must parse a RTF model source to build a RTFDocument. Default implementation of the RTFTemplate is the class net.sourceforge.rtf.handler.RTFDocumentHandler.

IRTFDocumentTransformer interface

IRTFDocumentTransformer interface must transform the RTFDocument object in order to that the template engine use it. Some macro switch selected template engine are added (#foreach for Velocity and #list for Freemarker). RTFTemplate implement two type of transformer :

  • Velocity transformer with class net.sourceforge.rtf.template.velocity.RTFVelocityTransformerImpl.
  • Freemarker transformer with class net.sourceforge.rtf.template.freemarker.RTFFreemarkerTransformerImpl.

RTFTemplate use by default the Velocity implementation.

ITemplateEngine interface

ITemplateEngine interface must merge data comming from the JAVA context with the content of the transformed RTFDocument. Merege is done with the template engine. RTTemplate implements 2 template engine :

  • Velocity with class net.sourceforge.rtf.template.velocity.VelocityTemplateEngineImpl.
  • Freemarker with class net.sourceforge.rtf.template.freemarker.FreemarkerTemplateEngineImpl.

RTFTemplate use by default the Velocity implementation.

RTFTemplate configuration

Each step of the generation process can be selected or re implemented. You can configure RTFTemplate with Spring (IoC mecanism) or with JAVA code.

Spring configuration

RTFTemplate use by default the Spring file rtftemplate-config.xml : To select the Freemarker implementation you must do like this : 

    
  // 2. Get RTFtemplate with default Implementation of template engine (Freemarker) 
  RTFTemplate rtfTemplate = builder.newRTFTemplate(RTFTemplateBuilder.
              DEFAULT_FREEMARKER_RTFTEMPLATE);

Here the Spring configuration (by default) of RTFtemplate : 

<beans>

        <!-- **********************************************************************
           ********************* RTFTEMPLTE IMPLEMENTATION  *********************
           ********************************************************************** --> 
           
        <!-- Defautlt RTFTemplate implementation  with freemarker template engine  --> 
        <bean id="ftlRTFTemplate" 
                        class="net.sourceforge.rtf.RTFTemplate" 
                        singleton="false" >
                <property name="parser" ref="defaultRTFParser" />      
                <property name="transformer" ref="ftlTransformer" />                                                            
                <property name="templateEngine" ref="ftl" />                    
        </bean>

        <!-- Defautlt RTFTemplate implementation with velocity template engine  --> 
        <bean id="vmRTFTemplate" 
                        class="net.sourceforge.rtf.RTFTemplate" 
                        singleton="false" >                     
                <property name="parser" ref="defaultRTFParser" />   
                <property name="transformer" ref="vmTransformer" />                      
                <property name="templateEngine" ref="vm" />                     
        </bean>

  <!-- **********************************************************************
           *********************    RTFDOCUMENT PARSER      *********************
           ********************************************************************** -->   

        <!-- Defautlt RTFDocument Parser  --> 
        <bean id="defaultRTFParser" 
                        class="net.sourceforge.rtf.handler.RTFDocumentHandler" 
                        singleton="true" >                       
        </bean>            
        
        
  <!-- **********************************************************************
           ********************* FREEMARKER TEMPLATE ENGINE *********************
           ********************************************************************** --> 
        
  <!-- Freemarker template engine  --> 
  <bean id="ftl" 
                class="net.sourceforge.rtf.template.freemarker.FreemarkerTemplateEngineImpl"            
                singleton="false" >
         <property name="freemarkerConfiguration" ref="ftlConfiguration" />           
  </bean>

  <!-- Freemarker Configuration  --> 
  <bean id="ftlConfiguration" 
                class="freemarker.template.Configuration" 
                singleton="true" >   
  </bean>

  <!-- Freemarker RTF Document Transformer  --> 
  <bean id="ftlTransformer" 
                class="net.sourceforge.rtf.template.freemarker.RTFFreemarkerTransformerImpl" 
                singleton="true" >   
  </bean>  
    
  <!-- **********************************************************************
           *********************  VELOCITY TEMPLATE ENGINE  *********************
           ********************************************************************** -->   
  
  <bean id="vm" 
                class="net.sourceforge.rtf.template.velocity.VelocityTemplateEngineImpl"
                singleton="false" >
         <property name="velocityEngine" ref="vmEngine" />       
  </bean>
  
  <!-- VelocityEngine Configuration  --> 
  <bean id="vmEngine" 
                class="org.apache.velocity.app.VelocityEngine" 
                singleton="true" >   
  </bean>    
    
  <!-- Velocity RTF Document Transformer  --> 
  <bean id="vmTransformer" 
                class="net.sourceforge.rtf.template.velocity.RTFVelocityTransformerImpl" 
                singleton="true" >   
  </bean>      
  
</beans>

The definition of the bean with id vmRTFTemplate is the configuration for RTFtemplate to use :

  • RTFDocumentHandler class for the parser (bean with id defaultRTFParser).
  • RTFVelocityTransformerImpl class for the transformer (bean id with vmTransformer).
  • VelocityTemplateEngineImpl class for th etemplate engine (bean id with vm).

RTFDocumentBuilder class is a helper which is able to load Spring configuration of RTFtemplate.

It's possible to use your own Spring configuration (to implement interfaces with your own implementations) : 

  // Load rtftemplate-config Spring configuration
  String key = 
      "net/sourceforge/rtf/usecases/config/rtftemplate-config.xml";
  ApplicationContext applicationContext = new ClassPathXmlApplicationContext(key);
  
  // 1. Get RTFtemplateBuilder with spring config
  RTFTemplateBuilder builder = RTFTemplateBuilder.newRTFTemplateBuilder(key, applicationContext);

Spring configuration is cached. To reuse your configuration : 

  String key = 
      "net/sourceforge/rtf/usecases/config/rtftemplate-config.xml";
      
  // 1. Get RTFtemplateBuilder with spring config
  RTFTemplateBuilder builder = RTFTemplateBuilder.newRTFTemplateBuilder(key);
Configuration without Spring

This last configuration can be done without Spring, with JAVA code like this : 

  RTFTemplate rtfTemplate  = new RTFTemplate();        
  // Parser
  RTFDocumentHandler parser = new RTFDocumentHandler();
  rtfTemplate.setParser(parser);
  
  // Transformer
  IRTFDocumentTransformer transformer = new RTFVelocityTransformerImpl();
  rtfTemplate.setTransformer(transformer);
  
  // Template engine 
  VelocityTemplateEngineImpl templateEngine = new VelocityTemplateEngineImpl();
  // Initialize velocity engine
  VelocityEngine velocityEngine = new VelocityEngine();
  templateEngine.setVelocityEngine(velocityEngine);
  rtfTemplate.setTemplateEngine(templateEngine);