Source code: echopoint/ui/jsp/JspComponentPeer.java

   package echopoint.ui.jsp;
   /* 
    * This file is part of the Echo Point Project.  This project is a collection
    * of Components that have extended the Echo Web Application Framework.
    *
    * EchoPoint is free software; you can redistribute it and/or modify
    * it under the terms of the GNU Lesser General Public License as published by
    * the Free Software Foundation; either version 2 of the License, or
    * (at your option) any later version.
   *
   * EchoPoint is distributed in the hope that it will be useful,
   * but WITHOUT ANY WARRANTY; without even the implied warranty of
   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   * GNU Lesser General Public License for more details.
   *
   * You should have received a copy of the GNU Lesser General Public License
   * along with Echo Point; if not, write to the Free Software
   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
   */
  
  import java.io.IOException;
  import java.io.PrintWriter;
  import java.io.StringWriter;
  import java.io.Writer;
  import java.util.HashMap;
  import java.util.Map;
  
  import javax.servlet.Servlet;
  import javax.servlet.ServletException;
  import javax.servlet.http.HttpServletRequest;
  import javax.servlet.http.HttpServletResponse;
  import javax.servlet.http.HttpSession;
  import javax.servlet.jsp.JspFactory;
  import javax.servlet.jsp.JspWriter;
  import javax.servlet.jsp.PageContext;
  
  import nextapp.echo.Component;
  import nextapp.echo.ImageReference;
  import nextapp.echo.event.ImageUpdateListener;
  import nextapp.echoservlet.ComponentPeer;
  import nextapp.echoservlet.ComponentStyle;
  import nextapp.echoservlet.RenderingContext;
  import nextapp.echoservlet.html.Element;
  import nextapp.echoservlet.html.Renderable;
  
  import echopoint.ui.util.EchoPointComponentPeer;
  import echopoint.ui.util.NoNameElement;
  import echopoint.util.throwable.ThrowableKit;
  
  /**
   * <code>JspComponentPeer</code> is an abstract component peer class 
   * that allows JSP page fragments to be used to render a component.
   * <p>
   * This class is useful if you prefer updating JSP/HTML markup rather 
   * than writing Java nextapp.echoservlet.html.Element statements.
   * <p>
   * To use this class you need to implement the method <code>getJspPath()</code>.
   * as this nominates the JSP path to include as peer content.  You might 
   * want to use different JSP pages depending on the state of the 
   * underlying component.  
   * <p>
   * You will very likely want to overide <code>preRender()</code>
   * as well.  This method allows any <code>ComponentStyle</code>'s and 
   * scripts to be added to the Echo HTML document.  You might also
   * want to add beans to the HttpSession or HttpServletRequest
   * objects at this time.
   * <p>  
   * The results of these pre-render methods are then available inside 
   * the JSP page because <code>JspComponentPeer</code> adds itself as 
   * a request scope attribute called "echopoint.ui.jsp.JspComponentPeer" 
   * or in Java terms <code>JspComponentPeer.JSPCOMPONENTPEER</code>.
   * <p>
   * You can then access the peer in the JSP page as follows :
   * <p>
   * <blockquote><pre>
   *      ...
   *      &lt;%@ page language="java" %&gt;
   *      &lt;%@ page import="echopoint.ui.jsp.JspComponentPeer" %&gt;
   *      &lt;%@ page import="com.yourcompany.*" %&gt;
   *      &lt;%
   *      JspComponentPeer peer = (JspComponentPeer) request.getAttribute(JspComponentPeer.JSPCOMPONENTPEER);
   *      YourCustomComponent customC = (YourCustomComponent) peer.getComponent();
   *      Component child = customC.getTopBit();
   *      %&gt;
   *      ...
   *      ...
   *      &lt;span class="&lt;%=peer.getStyle("topLineBit")%&gt;" &gt; Some styled text &lt;/span&gt;
   *      &lt;div class="&lt;%=peer.getStyle("contentBit")%&gt;" &gt;
   *      &lt;%
   *         peer.renderChild(out,child);  
   *      %&gt;
   *      &lt;/div&gt;
   *      &lt;image src="&lt;%=peer.getStyle("contentBit")%&gt;" &gt;
   * </pre></blockquote>
   * <p>
   * You will also have to associated your custom peer with its component
   * via a method such as :
   * <p>
   * <blockquote><pre>
  * public static void register() {
  *       nextapp.echoservlet.EchoServer.loadPeerBindings("mycompany.ui.MyCustomComponent");
  * }
  * </pre></blockquote>
  * <p>
  * This class differs from the other JSP integration class JspTemplatePanel in a number of 
  * ways.  Firstly it only evaluates the JSP once, at the time the Echo servlet is writing 
  * to the servlet stream.  Secondly it does not allow "styles" to be dynamically
  * evaluated like in a <code>JspTemplatePanel</code>.  And finally while it allows
  * child components to be embedded in the output, they are always pre-rendered and are
  * not "named" via the special JSP tags.
  * 
  */
 public abstract class JspComponentPeer extends EchoPointComponentPeer implements Renderable, ImageUpdateListener {
 
   /**
    * This string is used as the request scope attribute name which holds this
    * JspComponentPeer object.
    */
   public static final String JSPCOMPONENTPEER = "echopoint.ui.jsp.JspComponentPeer";
 
   private RenderingContext rc;  
   private PageContext pageContext;
   private JspFactory factory;
   private Servlet servlet;
   private HttpServletRequest request;
   private HttpServletResponse response;
   private HttpSession session;
   
   private Map childElementMap;
   private Map styleMap;
   private String jspPath;
   private boolean isLoudErrorsUsed = true;
   
   /**
    * The render method has been made final.  This method now sets up the
    * objects needed during the actual JSP rendering, such
    * as the JSP page to include, any scripts or component style 
    * names required and will then pre-render any child components.
    * <p>
    * The order is as follows :
    * <ol>
    * <li>getJspPath() is called</li> 
    * <li>preRender() is called</li> 
    * <li>any child peers are pre-rendered</li> 
    * </ol> 
    *  
    * @see nextapp.echoservlet.ComponentPeer#render(nextapp.echoservlet.RenderingContext, nextapp.echoservlet.html.Element)
    */
   public final void render(RenderingContext rc, Element parent) {
     this.rc = rc;
     
     servlet = rc.getConnection().getServer();
     request = rc.getConnection().getRequest();
     response = rc.getConnection().getResponse();
     session = request.getSession();
     
     factory = JspFactory.getDefaultFactory();
     if (factory == null)
       throw new IllegalStateException("The default JSPFactory could not be obtained");
       
     pageContext = factory.getPageContext(servlet, request, response, null, true, JspWriter.NO_BUFFER, true);
     if (pageContext == null)
       throw new IllegalStateException("The JSPFactory could provide a page context for this servlet");
 
     //
     // ask them what JSP page to use given the current state
     jspPath = getJspPath();
     if (jspPath == null || jspPath.length() == 0)
       throw new IllegalStateException("getJspPath must return a non empty JSP path");
     
     //
     // now call the abstract method to setup any styles and
     // scripts etc...    
     preRender(rc);
     
     //
     // if we have any children then render them and save them 
     // into the child map;
     ComponentPeer[] children = getChildren();
     if (children.length > 0) {
       childElementMap = new HashMap();
       for (int i = 0; i < children.length; i++) {
         NoNameElement noNameE = new NoNameElement();
         children[i].render(rc,noNameE);
         childElementMap.put(children[i].getComponent(),noNameE);
       } 
     }
     
     //
     // add ourselves as a Renderable!  This will allow us to be
     // called to output JSp content during the Echo
     // servlet output.
     parent.add(this);
   }
   
   /**
    * This method is called during Echo servlet output and it includes
    * the actual JSP content that has been setup for this 
    * component peer via getJspPath().
    * 
    * @see nextapp.echoservlet.html.Renderable#render(java.io.PrintWriter, int, boolean)
    */
   public final void render(PrintWriter pw, int depth, boolean parentWhitespaceRelevant) {
     
     try {
       //
       // Put ourselves in as a request attribute 
       request.setAttribute(JSPCOMPONENTPEER,this);
       ///////////////////////////////////////////////
       // include the page
       ///////////////////////////////////////////////
       pageContext.include(jspPath);
       factory.releasePageContext(pageContext);
       pageContext = null;
     } catch (ServletException e) {
       reportError(pw,e);
     } catch (IOException e) {
       throw ThrowableKit.makeRuntimeException(e);
     } finally {
       //
       //remove everything just added to request scope 
       //to avoid namespace pollution.
       //
       request.removeAttribute(JSPCOMPONENTPEER);
       // cleanup the factory and page context
       if (factory != null && pageContext != null)
         factory.releasePageContext(pageContext);
       factory = null;  
       servlet = null;
       request = null;
       response = null;
       rc = null;
       childElementMap = null;
       styleMap = null;
       jspPath = null;
     }
   }
   
   /**
    * Report a ServletError, in all likely hood an JSP compile 
    * error, by make it more pretty.
    */
   private void reportError(PrintWriter pw, ServletException e) {
     String temp = e.toString();
     StringBuffer sb = new StringBuffer();
     for (int i = 0; i < temp.length(); i++) {
       char c = temp.charAt(i);
       if (c == '\n')
         sb.append("<br>");
       else
         sb.append(c);  
     }
     String errorMsg = preNewLines(e.toString());
     
     StringWriter swStackTrace = new StringWriter();
     PrintWriter pwStackTrace = new PrintWriter(swStackTrace);
     e.printStackTrace(pwStackTrace);
     String stackTraceMsg = preNewLines(swStackTrace.toString());
     
     
     if (isLoudErrorsUsed) {
       pw.println("<div style=\"background:#acbcdc;color:white;font-size:12;border-width:1; border-style:solid; border-color:black; padding:4; margin:4\" >");
       pw.println("<blink><b>");
       pw.println("<p>JSP Component Peer Exception : '<blockquote><pre>" + errorMsg + "</pre></blockquote>'");
       pw.println("<p>Exception Stack Trace : '<blockquote><pre>" + stackTraceMsg + "</pre></blockquote>'");
       pw.println("</b></blink></div>");
     } else {
       pw.println("<!-- ");
       pw.println("JSP Component Peer Exception : '" + errorMsg + "'");
       pw.println("Exception Stack Trace : '" + stackTraceMsg + "'");
       pw.println(" -->");
     }
   }
     
   private String preNewLines(String s) {
     StringBuffer sb = new StringBuffer(s.length());
     for (int i = 0; i < s.length(); i++) {
       char c = s.charAt(i);
       if (c == '\n') {
         sb.append("<br>");
         while (i < s.length()-1 && s.charAt(i+1) == '\n')
           i++;  
       } else {
         sb.append(c);  
       }
     }
     return sb.toString();
   }
 
   /**
    * This method is an easy way to add completed ComponentStyle
    * objects to the document.  The Echo generated name is returned.
    * <p>
    * These component style names can then be used in class="xxx" 
    * statements inside the JSP markup.
    * <p>
    * A style keyed as "default" is initially primed and is
    * equivalent to <code>ComponentStyle.forComponent(this);</code>
    *  
    * @param styleKey - the key name to be later used with getStyle()
    * @param componentStyle - the completed ComponentStyle object.
    * @return - the Echo generated style name.
    */
   protected String putStyle(String styleKey, ComponentStyle componentStyle) {
     if (styleMap == null)
       styleMap = new HashMap();
     
     String styleName = rc.getDocument().addStyle(componentStyle);
     styleMap.put(styleKey,styleName);
     return styleName;
   }
 
   /**
    * Returns the Echo style name that was previously stored away
    * using the <code>putStyle()<code> method.  This is very useful
    * in HTML class="...." statements inside the JSP.
    * <p>
    * Usage is demonstrated in the following JSP fragment :
    * <p>
    * <blockquote><pre>
    *      ...
    *      &lt;%@ page language="java" %&gt;
    *      &lt;%@ page import="echopoint.ui.jsp.JspComponentPeer" %&gt;
    *      &lt;%
    *      JspComponentPeer peer = (JspComponentPeer) request.getAttribute(JspComponentPeer.JSPCOMPONENTPEER);
    *      %&gt;
    *      ...
    *      ...
    *      &lt;span class="&lt;%=peer.getStyle("topLineBit")" %&gt; Some styled text &lt;/span&gt;
    * </pre></blockquote>
    *  
    * @param styleKey - the styleKey used when storing the style
    * @return the style name
    */
   public String getStyle(String styleKey) {
     return styleMap == null ? null : (String) styleMap.get(styleKey);
   }
   
   /**
    * This is a synonym for the <code>getStyle()</code> method but it
    * adds the text class="xxx" for you.  It allows you to write
    * <p>
    * <blockquote><pre>
    *      &lt;span &lt;%=peer.classEquals("topLineBit")%&gt; &gt; Some styled text &lt;/span&gt;
    * </pre></blockquote>
    * <p>
    * instead of the slightly more terse :
    * <p>
    * <blockquote><pre>
    *      &lt;span class="&lt;%=peer.getStyle("topLineBit")" %&gt; &gt; Some styled text &lt;/span&gt;
    * </pre></blockquote>
    * 
    *  
    * @param styleKey
    * @return
    */
   public String classEquals(String styleKey) {
     StringBuffer sb = new StringBuffer(" class=\"");
     sb.append(getStyle(styleKey));
     sb.append("\" ");
     return sb.toString();
   }
 
   /**
    * This will return the URI for a managed image or null if it
    * can not be found.
    *  
    * @param imageName - the name of a managed image
    * @return the URI for the image or null if it can not be found.
    */
   public String getImageUri(String imageName) {
     return getImageUri(rc,imageName);
   }
 
   /**
    * Synonym for imgEquals(imageName,"");
    * 
    * @see JspComponentPeer#imgEquals(String, String)
    */
   public String imgEquals(String imageName) {
     return imgEquals(imageName,"");
   }
 
   /**
    * This is a synonym for the <code>getImageUri()</code> method but it
    * adds the text &lt;img src="xxx" width="nnn" height="nnn" ...> plus
    * any extra attribuets that have been provided on the call. 
    * <p>
    * It allows you to write
    * <p>
    * <blockquote><pre>
    *      &lt;%=peer.imgEquals("imageName1","vspace=5")%&gt;
    * </pre></blockquote>
    * <p>
    * instead of the slightly more terse :
    * <p>
    * <blockquote><pre>
    *      &lt;img src="&lt;%=peer.getImageUri("imageName1")%&gt;" width="nnn" height="nnn" vspace=5 &gt;
    * </pre></blockquote>
    * 
    * @param styleKey
    * @return
    */
   public String imgEquals(String imageName, String extraAttributes) {
     String imageURI = getImageUri(imageName);
 
     StringBuffer sb = new StringBuffer("<img ");
     sb.append(" src=\"");
     sb.append(imageURI);
     sb.append("\" ");
     if (imageURI != null) {
       ImageReference imageRef = getImage(imageName);
       if (imageRef.getWidth() > 0) {
         sb.append(" width=\"");
         sb.append(imageRef.getWidth());
         sb.append("\" ");   
       }
       if (imageRef.getHeight() > 0) {
         sb.append(" height=\"");
         sb.append(imageRef.getHeight());
         sb.append("\" ");   
       }
     }
     if (extraAttributes != null && extraAttributes.length() > 0) {
       sb.append(extraAttributes);
     }
     sb.append(">");
     return sb.toString();
   }
   
   /**
    * This method is available so that the JSP can render a child 
    * of the main component.  They key to use is the actual 
    * child component itself.  
    * <p>
    * Child components of the peers main component are pre-rendered
    * during the intital setup, before the JSP page is rendered.  You
    * can use this method to access the pre-rendered child components
    * inside the JSP markup itself.
    * <p>
    * Usage is demonstrated in the following JSP fragment :
    * <p>
    * <blockquote><pre>
    *      ...
    *      &lt;%@ page language="java" %&gt;
    *      &lt;%@ page import="echopoint.ui.jsp.JspComponentPeer" %&gt;
    *      &lt;%@ page import="com.yourcompany.*" %&gt;
    *      &lt;%
    *      JspComponentPeer peer = (JspComponentPeer) request.getAttribute(JspComponentPeer.JSPCOMPONENTPEER);
    *      YourCustomComponent customC = (YourCustomComponent) peer.getComponent();
    *      Component child = customC.getTopBit();
    *      %&gt;
    *      ...
    *      ...
    *      &lt;div&gt;
    *      &lt;%
    *         peer.renderChild(out,child);  
    *      %&gt;
    *      &lt;/div&gt;
    * </pre></blockquote>
    *  
    * @param out - the JSP output writer
    * @param childComponent - the component in question
    */
   public void renderChild(Writer out, Component childComponent) {
     // if we have no map we have no child peers
     if (childElementMap == null)
       return;
     Element e = (Element) childElementMap.get(childComponent);
     if (e != null) {
       PrintWriter pw = new PrintWriter(out);
       e.render(pw,0,true);
     }
   }
 
   /** 
    * Returns the current RenderingContext associated with the peer or null if none is available.
    * 
    * @return the current RenderingContext associated with the peer or null if none is available.
    */
   public RenderingContext getRenderingContext() {
     return rc;
   }
 
   /** 
    * Returns the JSPFactory currently in use or null if none is available.
    * @return the JSPFactory currently in use or null if none is available.
    */
   public JspFactory getFactory() {
     return factory;
   }
 
   /** 
    * Returns the PageContext currently in use or null if none is available.
    * @return the PageContext currently in use or null if none is available.
    */
   public PageContext getPageContext() {
     return pageContext;
   }
 
   /** 
    * Returns the HttpServletRequest currently in use or null if none is available.
    * @return the HttpServletRequest currently in use or null if none is available.
    */
   public HttpServletRequest getRequest() {
     return request;
   }
 
   /** 
    * Returns the HttpServletResponse currently in use or null if none is available.
    * @return the HttpServletResponse currently in use or null if none is available.
    */
   public HttpServletResponse getResponse() {
     return response;
   }
 
   /** 
    * Returns the Servlet currently in use or null if none is available.
    * @return the Servlet currently in use or null if none is available.
    */
   public Servlet getServlet() {
     return servlet;
   }
 
   /** 
    * Returns the HttpSession currently in use or null if none is available.
    * @return the HttpSession currently in use or null if none is available.
    */
   public HttpSession getSession() {
     return session;
   }
   
   /** 
    * Returns true if loud error message generation is used.
    * @return true if loud error message generation is used.
    */
   public boolean isLoudErrorsUsed() {
     return isLoudErrorsUsed;
   }
 
   /** 
    * If this is set to true, then a loud, obvious HTML error
    * will be output if some catatrophic error occurs
    * during JSP rendering.  Otherwise a quite HTML
    * comment will be emitted.
    * 
    * @param isLoudErrorsUsed - true if loud errors are to be used
    */
   public void setLoudErrorsUsed(boolean isLoudErrorsUsed) {
     this.isLoudErrorsUsed = isLoudErrorsUsed;
   }
 
 
   
   /** 
    * This abstract method is required to return the path of the JSP page 
    * that will be included as the content of this component peer.  
    * It must be non null and non-empty, otherwise an
    * IllegalStateException is thrown.
    * 
    * @return the path of the JSP to be rendered as this peer.
    * 
    * @throws IllegalStateException if the path is null or empty
    */
   protected abstract String getJspPath();
 
   /**
    * This is called to setup any objects needed before
    * the actual JSP page is invoked.  This could include
    * things such as <code>ComponentStyle</code> objects and any
    * special scripts and services required.
    * <p>
    * You might also want to add beans to the HttpSession or 
    * HttpServletRequest objects at this time.  
    * <p>
    * These scripts etc.. can be added to the head of the HTML document because 
    * this method is called before actual JSP rendering occurs.
    * <p>
    * This implementation of the method adds a ComponentStyle
    * mapped as "default", via is built via 
    * <code>ComponentStyle.forComponent(this);</code>
    *  
    * @param rc - the RenderingContext
    */
   protected void preRender(RenderingContext rc) {
     //
     // we always create a default style
     ComponentStyle style = ComponentStyle.forComponent(this);
     style.addElementType("");
     putStyle("default",style);
 
   }
 
 }