echopoint.ui.jsp
Class JspComponentPeer

java.lang.Object
  nextapp.echoservlet.ComponentPeer
      echopoint.ui.util.EchoPointComponentPeer
          echopoint.ui.jsp.JspComponentPeer

All Implemented Interfaces:

nextapp.echo.event.ChangeListener, java.util.EventListener, nextapp.echo.event.ImageUpdateListener, PeerDelegate, java.beans.PropertyChangeListener, nextapp.echoservlet.html.Renderable, java.io.Serializable

public abstract class JspComponentPeer

extends EchoPointComponentPeer

implements nextapp.echoservlet.html.Renderable

JspComponentPeer is an abstract component peer class that allows JSP page fragments to be used to render a component.

This class is useful if you prefer updating JSP/HTML markup rather than writing Java nextapp.echoservlet.html.Element statements.

To use this class you need to implement the method getJspPath(). 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.

You will very likely want to overide preRender() as well. This method allows any ComponentStyle'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.

The results of these pre-render methods are then available inside the JSP page because JspComponentPeer adds itself as a request scope attribute called "echopoint.ui.jsp.JspComponentPeer" or in Java terms JspComponentPeer.JSPCOMPONENTPEER.

You can then access the peer in the JSP page as follows :

      ...
      <%@ page language="java" %>
      <%@ page import="echopoint.ui.jsp.JspComponentPeer" %>
      <%@ page import="com.yourcompany.*" %>
      <%
      JspComponentPeer peer = (JspComponentPeer) request.getAttribute(JspComponentPeer.JSPCOMPONENTPEER);
      YourCustomComponent customC = (YourCustomComponent) peer.getComponent();
      Component child = customC.getTopBit();
      %>
      ...
      ...
      <span class="<%=peer.getStyle("topLineBit")%>" > Some styled text </span>
      <div class="<%=peer.getStyle("contentBit")%>" >
      <%
         peer.renderChild(out,child);  
      %>
      </div>
      <image src="<%=peer.getStyle("contentBit")%>" >
 

You will also have to associated your custom peer with its component via a method such as :

 public static void register() {
       nextapp.echoservlet.EchoServer.loadPeerBindings("mycompany.ui.MyCustomComponent");
 }
 

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 JspTemplatePanel. 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.

See Also:

Serialized Form

Field Summary

static java.lang.String

JSPCOMPONENTPEER This string is used as the request scope attribute name which holds this JspComponentPeer object.

Fields inherited from class echopoint.ui.util.EchoPointComponentPeer

renderedActive

Fields inherited from interface nextapp.echoservlet.html.Renderable

INDENT_STRING

Constructor Summary

JspComponentPeer()

Method Summary

java.lang.String	classEquals(java.lang.String styleKey) This is a synonym for the getStyle() method but it adds the text class="xxx" for you.
javax.servlet.jsp.JspFactory	getFactory() Returns the JSPFactory currently in use or null if none is available.
java.lang.String	getImageUri(java.lang.String imageName) This will return the URI for a managed image or null if it can not be found.
protected abstract java.lang.String	getJspPath() This abstract method is required to return the path of the JSP page that will be included as the content of this component peer.
javax.servlet.jsp.PageContext	getPageContext() Returns the PageContext currently in use or null if none is available.
nextapp.echoservlet.RenderingContext	getRenderingContext() Returns the current RenderingContext associated with the peer or null if none is available.
javax.servlet.http.HttpServletRequest	getRequest() Returns the HttpServletRequest currently in use or null if none is available.
javax.servlet.http.HttpServletResponse	getResponse() Returns the HttpServletResponse currently in use or null if none is available.
javax.servlet.Servlet	getServlet() Returns the Servlet currently in use or null if none is available.
javax.servlet.http.HttpSession	getSession() Returns the HttpSession currently in use or null if none is available.
java.lang.String	getStyle(java.lang.String styleKey) Returns the Echo style name that was previously stored away using the putStyle() method.
java.lang.String	imgEquals(java.lang.String imageName) Synonym for imgEquals(imageName,"");
java.lang.String	imgEquals(java.lang.String imageName, java.lang.String extraAttributes) This is a synonym for the getImageUri() method but it adds the text <img src="xxx" width="nnn" height="nnn" ...> plus any extra attribuets that have been provided on the call.
boolean	isLoudErrorsUsed() Returns true if loud error message generation is used.
protected void	preRender(nextapp.echoservlet.RenderingContext rc) This is called to setup any objects needed before the actual JSP page is invoked.
protected java.lang.String	putStyle(java.lang.String styleKey, nextapp.echoservlet.ComponentStyle componentStyle) This method is an easy way to add completed ComponentStyle objects to the document.
void	render(java.io.PrintWriter pw, int depth, boolean parentWhitespaceRelevant) 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().
void	render(nextapp.echoservlet.RenderingContext rc, nextapp.echoservlet.html.Element parent) The render method has been made final.
void	renderChild(java.io.Writer out, nextapp.echo.Component childComponent) This method is available so that the JSP can render a child of the main component.
void	setLoudErrorsUsed(boolean isLoudErrorsUsed) If this is set to true, then a loud, obvious HTML error will be output if some catatrophic error occurs during JSP rendering.

Methods inherited from class echopoint.ui.util.EchoPointComponentPeer

addOnce, addOnce, addScriptInclude, copyChildrenExcept, copyChildrenExcept, forComponent, forComponent, forComponent, forComponent, getChildren, getImage, getImageManager, getImageUri, getPeer, getPeer, getToolTipHelper, getUri, hasBeenAdded, imageUpdate, propertyChange, registered, removeAllImages, removeAllManagedImages, removeNewLinesAndJSQuote, removeNewLinesAndJSQuote, setImage, stateChanged, trackImage, unregistered

Methods inherited from class nextapp.echoservlet.ComponentPeer

addAncillaryService, generateId, getBackground, getChildCount, getComponent, getFont, getForeground, getId, getInstancePeer, getParent, redraw, removeAncillaryService

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface echopoint.ui.util.PeerDelegate

getId

Field Detail

JSPCOMPONENTPEER

public static final java.lang.String JSPCOMPONENTPEER

This string is used as the request scope attribute name which holds this JspComponentPeer object.

See Also:

Constant Field Values

Constructor Detail

JspComponentPeer

public JspComponentPeer()

Method Detail

render

public final void render(nextapp.echoservlet.RenderingContext rc,
                         nextapp.echoservlet.html.Element parent)

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.

The order is as follows :

1. getJspPath() is called
2. preRender() is called
3. any child peers are pre-rendered

See Also:

ComponentPeer.render(nextapp.echoservlet.RenderingContext, nextapp.echoservlet.html.Element)

render

public final void render(java.io.PrintWriter pw,
                         int depth,
                         boolean parentWhitespaceRelevant)

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().

Specified by:

render in interface nextapp.echoservlet.html.Renderable

See Also:

Renderable.render(java.io.PrintWriter, int, boolean)

putStyle

protected java.lang.String putStyle(java.lang.String styleKey,
                                    nextapp.echoservlet.ComponentStyle componentStyle)

This method is an easy way to add completed ComponentStyle objects to the document. The Echo generated name is returned.

These component style names can then be used in class="xxx" statements inside the JSP markup.

A style keyed as "default" is initially primed and is equivalent to ComponentStyle.forComponent(this);

Parameters:

styleKey - - the key name to be later used with getStyle()

componentStyle - - the completed ComponentStyle object.

Returns:

- the Echo generated style name.

getStyle

public java.lang.String getStyle(java.lang.String styleKey)

Returns the Echo style name that was previously stored away using the putStyle() method. This is very useful in HTML class="...." statements inside the JSP.

Usage is demonstrated in the following JSP fragment :

      ...
      <%@ page language="java" %>
      <%@ page import="echopoint.ui.jsp.JspComponentPeer" %>
      <%
      JspComponentPeer peer = (JspComponentPeer) request.getAttribute(JspComponentPeer.JSPCOMPONENTPEER);
      %>
      ...
      ...
      <span class="<%=peer.getStyle("topLineBit")" %> Some styled text </span>
 

Parameters:

styleKey - - the styleKey used when storing the style

Returns:

the style name

classEquals

public java.lang.String classEquals(java.lang.String styleKey)

This is a synonym for the getStyle() method but it adds the text class="xxx" for you. It allows you to write

      <span <%=peer.classEquals("topLineBit")%> > Some styled text </span>
 

instead of the slightly more terse :

      <span class="<%=peer.getStyle("topLineBit")" %> > Some styled text </span>
 

Parameters:

styleKey -

Returns:

a String value in the form class="xxx"

getImageUri

public java.lang.String getImageUri(java.lang.String imageName)

This will return the URI for a managed image or null if it can not be found.

Parameters:

imageName - - the name of a managed image

Returns:

the URI for the image or null if it can not be found.

imgEquals

public java.lang.String imgEquals(java.lang.String imageName)

Synonym for imgEquals(imageName,"");

See Also:

imgEquals(String, String)

imgEquals

public java.lang.String imgEquals(java.lang.String imageName,
                                  java.lang.String extraAttributes)

This is a synonym for the getImageUri() method but it adds the text <img src="xxx" width="nnn" height="nnn" ...> plus any extra attribuets that have been provided on the call.

It allows you to write

      <%=peer.imgEquals("imageName1","vspace=5")%>
 

instead of the slightly more terse :

      <img src="<%=peer.getImageUri("imageName1")%>" width="nnn" height="nnn" vspace=5 >
 

Parameters:

imageName - - the name of the image

extraAttributes - - any extra attributes

Returns:

an img tag for the image

renderChild

public void renderChild(java.io.Writer out,
                        nextapp.echo.Component childComponent)

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.

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.

Usage is demonstrated in the following JSP fragment :

      ...
      <%@ page language="java" %>
      <%@ page import="echopoint.ui.jsp.JspComponentPeer" %>
      <%@ page import="com.yourcompany.*" %>
      <%
      JspComponentPeer peer = (JspComponentPeer) request.getAttribute(JspComponentPeer.JSPCOMPONENTPEER);
      YourCustomComponent customC = (YourCustomComponent) peer.getComponent();
      Component child = customC.getTopBit();
      %>
      ...
      ...
      <div>
      <%
         peer.renderChild(out,child);  
      %>
      </div>
 

Parameters:

out - - the JSP output writer

childComponent - - the component in question

getRenderingContext

public nextapp.echoservlet.RenderingContext getRenderingContext()

Returns the current RenderingContext associated with the peer or null if none is available.

Returns:

the current RenderingContext associated with the peer or null if none is available.

getFactory

public javax.servlet.jsp.JspFactory getFactory()

Returns the JSPFactory currently in use or null if none is available.

Returns:

the JSPFactory currently in use or null if none is available.

getPageContext

public javax.servlet.jsp.PageContext getPageContext()

Returns the PageContext currently in use or null if none is available.

Returns:

the PageContext currently in use or null if none is available.

getRequest

public javax.servlet.http.HttpServletRequest getRequest()

Returns the HttpServletRequest currently in use or null if none is available.

Returns:

the HttpServletRequest currently in use or null if none is available.

getResponse

public javax.servlet.http.HttpServletResponse getResponse()

Returns the HttpServletResponse currently in use or null if none is available.

Returns:

the HttpServletResponse currently in use or null if none is available.

getServlet

public javax.servlet.Servlet getServlet()

Returns the Servlet currently in use or null if none is available.

Returns:

the Servlet currently in use or null if none is available.

getSession

public javax.servlet.http.HttpSession getSession()

Returns the HttpSession currently in use or null if none is available.

Returns:

the HttpSession currently in use or null if none is available.

isLoudErrorsUsed

public boolean isLoudErrorsUsed()

Returns true if loud error message generation is used.

Returns:

true if loud error message generation is used.

setLoudErrorsUsed

public void setLoudErrorsUsed(boolean 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.

Parameters:

isLoudErrorsUsed - - true if loud errors are to be used

getJspPath

protected abstract java.lang.String getJspPath()

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.

Returns:

the path of the JSP to be rendered as this peer.

Throws:

java.lang.IllegalStateException - if the path is null or empty

preRender

protected void preRender(nextapp.echoservlet.RenderingContext rc)

This is called to setup any objects needed before the actual JSP page is invoked. This could include things such as ComponentStyle objects and any special scripts and services required.

You might also want to add beans to the HttpSession or HttpServletRequest objects at this time.

These scripts etc.. can be added to the head of the HTML document because this method is called before actual JSP rendering occurs.

This implementation of the method adds a ComponentStyle mapped as "default", via is built via ComponentStyle.forComponent(this);

Parameters:

rc - - the RenderingContext