User guide - RTFTempate integration - Servlet

RTFTemplate & Servlet

To use RTFTemplate in your WEB application, you can implement servlet net.sourceforge.rtf.web.servlet.AbstractRTFTemplateServlet.

To use this class, you must :

rtftemplate-web-usecases-version distribution give you samples with RTFTemplate and WEB application..

AbstractRTFTemplateServlet implementation

Methods which must be implement are :

  • putContext : put your context in this method with WHOLE JAVA objects which must be used in the RTf model. It's very important to instanciate Collection and complex objects (objects graph). For the collection, you must add at least ONE JAVA object, in order to RTFTemplate generate loop macro (#foreach for Velocity, #list for Freemarker,...), generate correctly XML file (*.fields.xml).
  • getXMLFieldsAvailable : this méthod must return XML stream of available fields for the model to edit. If model is not cached, this method is called on every RTF edition.

    You can redefine following methods :

  • getRTFReader OR getRTFInputStream : those methods must return the content (Reader or InputStream) of the RTF model source. If model is not cached, this method is called on every RTF edition.
  • getFileNameOfContentDisposition : to return name of filename to use (See Content-Disposition of request) when response is finished.
  • getGroupByPerPageBreak : to generate every groupByPerPageBreakème of item of the first list detected by RTFTemplate, a page break.
  • cacheWithKey et unCacheWithKey : manage cache of the instance transformed RTFDocument.
  • getGlobalApplicationContext et getApplicationContext : set the RTFTemplate Spring configuration to use with (global or model RTF)

Here a class sample which implement AbstractRTFTemplateServlet :

  ...
  import net.sourceforge.rtf.web.servlet.RTFTemplateServlet;

  public class SampleRTFTemplateServlet extends AbstractRTFTemplateServlet  {

      public static final long serialVersionUID = 1L;
      private static final String JAKARATA_VELOCITY_MODEL = "jakarta-velocity-model";
      private static final String REQUEST_MODELNAME = "modelName";
      private static final String REQUEST_MUSTBECACHED = "mustBeCached";
      
      private static final String JAKARATA_VELOCITY_MODEL = "jakarta-velocity-model";
      
      protected Reader getRTFReader(HttpServletRequest request) throws Exception {
              // 1. Get Real path of RTF model.
              String rtfModelName = request.getParameter(REQUEST_MODELNAME);
              rtfModelName+= ".rtf";
              String rtfModelPath = "/models/jakartavelocityproject/" + rtfModelName; 
              rtfModelPath = super.getRealPathOfRTFModel(request, rtfModelPath);
              
              // 2. Get Reader of RTF model
              Reader rtfModelReader = new FileReader(new File(rtfModelPath));
              return rtfModelReader;
      }
      
      protected void putContext(HttpServletRequest request, IContext ctx ) throws Exception {
              // Swith RTF Model Name, Context is different
              String rtfModelName = request.getParameter(REQUEST_MODELNAME);
              if (JAKARATA_VELOCITY_MODEL.equals(rtfModelName)) {
                      putContextJAKARATA_VELOCITY_MODEL(request, ctx);
              }
              else {
                      // ...... Other RTF model
              }
      }
      
      protected InputStream getXMLFieldsAvailable(HttpServletRequest request) throws Exception {
              //        Swith RTF Model Name, XML fields available is different or can be null
              String rtfModelName = request.getParameter(REQUEST_MODELNAME);
              if (JAKARATA_VELOCITY_MODEL.equals(rtfModelName)) {
                      String xmlFieldsAvailable = rtfModelName + ".fields.xml";
                      InputStream inputStream = SampleRTFTemplateServlet.class.getResourceAsStream(xmlFieldsAvailable);
                      return inputStream;
              }
              else {
                      // ...... Other RTF model
              }
              return null;
      }
      
      protected void putContextJAKARATA_VELOCITY_MODEL(HttpServletRequest request, IContext ctx ) throws Exception {
              
              String projectName = request.getParameter("projectName");
              
              String projectName = request.getParameter("projectName");
              /*
               * Context of simply POJO
               */
              ctx.put("date", new Date());
              ctx.put("project", new Project(projectName));
      }
      
      /**
       * return name of FileName for Content-Disposition
       */
      protected String getFileNameOfContentDisposition(HttpServletRequest request) {
              String rtfModelName = request.getParameter("modelName");
              if (rtfModelName != null) {
                      return rtfModelName + ".rtf";
              }
              return super.getFileNameOfContentDisposition(request);
      }
        
    protected String cacheWithKey(HttpServletRequest request) {
        // Test if checkbox cache is checked
        if (request.getParameter(REQUEST_MUSTBECACHED) != null) {
            // Cache must be enable for the RTF model
            // return name of the RTF model
            return request.getParameter(REQUEST_MODELNAME);
        }
        return null;
    }
    
    protected String unCacheWithKey(HttpServletRequest request) {
        // Test if checkbox cache is checked
        if (request.getParameter(REQUEST_MUSTBECACHED) == null) {
            // Cache must be disable for the RTF model
            // return name of the RTF model
            return request.getParameter(REQUEST_MODELNAME);            
        }        
        return null;
    }        
}

Servlet declaration

Once you have implemented AbstractRTFTemplateServlet servelt you must declare it in your web.xml file like this :

  <!-- Servlet RTFtemplate -->   
  <servlet>
    <servlet-name>rtf</servlet-name>
    <servlet-class>net.sourceforge.rtf.web.usecases.SampleRTFTemplateServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>

  <servlet-mapping>
    <servlet-name>rtf</servlet-name>
    <url-pattern>/rtfservlet/*</url-pattern>
  </servlet-mapping>  

Call your servlet

To launch RTF edition by using your servlet, you must define HTML form which post to your servlet :

  <form name="sampleRTFTemplate" action="/youWebApplication/rtfservlet" >
  
    <input type="submit" value="Launch RTF Edition" >
    
  </form>
  

where youWebApplication is the name of your WEB application.

XML fields available

It's adwisable to use XML file of available fields (*.fields.xml). To do that you must implement getXMLFieldsAvailable method of the AbstractRTFTemplateServlet class.

  protected InputStream getXMLFieldsAvailable(HttpServletRequest request) throws Exception {  
    ....
    return xmlFieldsInputStream;
  }  
  

Optimisation

To have more information abour optimization, you can read this section

To cache RTF source model, you must implement cacheWithKey method which must return the key of your RTF model to cache it.

Here a sample :

    protected String cacheWithKey(HttpServletRequest request) {
        // Test if checkbox cache is checked
        if (request.getParameter(REQUEST_MUSTBECACHED) != null) {
            // Cache must be enable for the RTF model
            // return name of the RTF model
            return request.getParameter(REQUEST_MODELNAME);
        }
        return null;
    }

To remove model of the cache (when your RTF source model is updated), you must implement unCacheWithKey method, which must return the key of your RTF model to uncache it. Voici un exemple :

  protected String unCacheWithKey(HttpServletRequest request) {
        // Test if checkbox cache is checked
        if (request.getParameter(REQUEST_MUSTBECACHED) == null) {
            // Cache must be disable for the RTF model
            // return name of the RTF model
            return request.getParameter(REQUEST_MODELNAME);            
        }        
        return null;
    }