KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > beehive > netui > tags > databinding > datagrid > AbstractCell


1 /*
2  * Copyright 2004 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  *
16  * $Header:$
17  */
18 package org.apache.beehive.netui.tags.databinding.datagrid;
19
20 import org.apache.beehive.netui.util.internal.InternalStringBuilder;
21
22 import java.io.IOException JavaDoc;
23 import javax.servlet.jsp.JspException JavaDoc;
24
25 import org.apache.beehive.netui.databinding.datagrid.api.rendering.DataGridTagModel;
26 import org.apache.beehive.netui.databinding.datagrid.api.rendering.CellModel;
27 import org.apache.beehive.netui.tags.rendering.AbstractRenderAppender;
28 import org.apache.beehive.netui.tags.rendering.StringBuilderRenderAppender;
29 import org.apache.beehive.netui.tags.rendering.AbstractHtmlState;
30 import org.apache.beehive.netui.tags.html.HtmlConstants;
31 import org.apache.beehive.netui.tags.html.FormatTag.Formatter;
32 import org.apache.beehive.netui.util.Bundle;
33 import org.apache.beehive.netui.util.logging.Logger;
34
35 /**
36  * <p>
37  * Abstract base class for JSP tags that render data grid cells. This class provides support to
38  * subclasses in several areas:
39  * <ul>
40  * <li>formatting -- this class accepts instances of {@link Formatter} which can optionally be used
41  * by a subclass to perform formatting on content that is written to a rendered page</li>
42  * <li>applying attributes</li>
43  * <li>applying state attributes to {@link AbstractHtmlState} instances used by subclasses.
44  * </ul>
45  * </p>
46  */
47 public abstract class AbstractCell
48     extends AbstractDataGridHtmlTag {
49
50     private static final Logger LOGGER = Logger.getInstance(AbstractCell.class);
51
52     /* todo: switch onto ConstantRendering.NBSP */
53     private static final String JavaDoc EMPTY_CELL = "&nbsp;";
54
55     /**
56      * Add a {@link Formatter}. Subclasses can optionally use the support formatting; formatters
57      * are added to the {@link CellModel} associated with an instance of the subclass.
58      * @param formatter the formatter to add
59      */
60     public void addFormatter(Formatter formatter) {
61         internalGetCellModel().addFormatter(formatter);
62     }
63
64     /**
65      * Indicate that a formatter has reported an error so the formatter should output it's body text.
66      */
67     public void formatterHasError() {
68         /* todo: error reporting */
69     }
70
71     /**
72      * <p>
73      * This method implements the rendering process for data grid cells. When the data grid's
74      * rendering state is <b>not</b> {@link DataGridTagModel#RENDER_STATE_START}, this tag processes
75      * its body. The tag performs the following steps in order:
76      * <ol>
77      * <li>The tag invokes its {@link #applyAttributes()} method to allow subclasses to apply attributes
78      * to their {@link CellModel} instances at a well known time. Any errors in attribute checking
79      * should be thrown here.</li>
80      * <li>The tag adds the {@link CellModel} associated with the data grid to the
81      * {@link javax.servlet.jsp.JspContext} under the key <code>cellModel</code>.</li>
82      * <li>Rendering is performed by invoking
83      * {@link #renderCell(org.apache.beehive.netui.tags.rendering.AbstractRenderAppender)}. If content is
84      * rendered when the body of the tag is rendered, it is written to the output stream.
85      * </li>
86      * <li>The tag removes the {@link CellModel} instance. If an exception is thrown after the
87      * {@link CellModel} is added to the {@link javax.servlet.jsp.JspContext}, it the cell model
88      * will still be removed from the JspContext.</li>
89      * </ol>
90      * </p>
91      * @throws JspException
92      * @throws IOException
93      */
94     public void doTag()
95         throws JspException JavaDoc, IOException JavaDoc {
96
97         DataGridTagModel dataGridModel = DataGridUtil.getDataGridTagModel(getJspContext());
98
99         int gridRenderState = dataGridModel.getRenderState();
100
101         /* RENDER_STATE_START is a no-op for cells */
102         if(gridRenderState == DataGridTagModel.RENDER_STATE_START) {
103             return;
104         }
105         // otherwise, the CellModel associated with this tag
106 // needs to be fetched from the <cell> tag for the current
107 // iteration
108 else {
109             CellModel model = internalGetCellModel();
110             model.setDataGridTagModel(dataGridModel);
111
112             applyAttributes();
113
114             try {
115                 DataGridUtil.putCellModel(getJspContext(), model);
116
117                 InternalStringBuilder content = new InternalStringBuilder();
118                 AbstractRenderAppender appender = new StringBuilderRenderAppender(content);
119
120                 renderCell(appender);
121
122                 if(content != null && content.length() > 0)
123                     getJspContext().getOut().println(content.toString());
124             }
125             finally {
126                 DataGridUtil.removeCellModel(getJspContext());
127             }
128         }
129
130         return;
131     }
132
133     /**
134      * <p>
135      * Abstract method implemented by subclasses. Implementers should return the {@link CellModel} associated
136      * with the UI that is being rendered by the JSP tag.
137      * </p>
138      * @return the cell's {@link CellModel}
139      */
140     protected abstract CellModel internalGetCellModel();
141
142     /**
143      * <p>
144      * Abstract method implemented by subclasses to perform cell-specific rendering.
145      * </p>
146      * @param appender the {@link AbstractRenderAppender} to which any output should be rendered
147      * @throws IOException
148      * @throws JspException
149      */
150     protected abstract void renderCell(AbstractRenderAppender appender)
151         throws IOException JavaDoc, JspException JavaDoc;
152
153     /**
154      * Utility method usable by subclasses that renders an HTML &amp;nbsp; to represent an empty HTML table cell.
155      * @param appender the {@link AbstractRenderAppender} to which any output should be rendered
156      */
157     protected void renderEmptyCell(AbstractRenderAppender appender) {
158         appender.append(EMPTY_CELL);
159     }
160
161     /**
162      * Utility method invoked during tag rendering. Subclasses should place attribute validation logic
163      * here.
164      * @throws JspException if application of attributes fails
165      */
166     protected void applyAttributes()
167         throws JspException JavaDoc {
168     }
169
170     /**
171      * <p>
172      * Add an HTML state attribute to a {@link AbstractHtmlState} object. This method performs
173      * checks on common attributes and sets their values on the state object or throws an exception.
174      * </p>
175      * <p>
176      * For the HTML tags it is not legal to set the <code>id</code> or <code>name</code> attributes.
177      * In addition, the base tag does
178      * not allow facets to be set. If the attribute is legal it will be added to the
179      * general expression map stored in the <code>AbstractHtmlState</code> of the tag.
180      * </p>
181      *
182      * @param state the state object to which attributes are appliedn
183      * @param name the name of an attribute
184      * @param value the value of the attribute
185      * @throws JspException when an error occurs setting the attribute on the state object
186      */
187     protected final void addStateAttribute(AbstractHtmlState state, String JavaDoc name, String JavaDoc value)
188             throws JspException JavaDoc {
189
190         // validate the name attribute, in the case of an error simply return.
191 if(name == null || name.length() <= 0) {
192             String JavaDoc s = Bundle.getString("Tags_AttributeNameNotSet");
193             throw new JspException JavaDoc(s);
194         }
195
196         // it's not legal to set the id or name attributes this way
197 if(name != null && (name.equals(HtmlConstants.ID) || name.equals(HtmlConstants.NAME))) {
198             String JavaDoc s = Bundle.getString("Tags_AttributeMayNotBeSet", new Object JavaDoc[]{name});
199             throw new JspException JavaDoc(s);
200         }
201
202         // if there is a style or class we will let them override the base
203 if(name.equals(HtmlConstants.CLASS)) {
204             state.styleClass = value;
205             return;
206         }
207         else if(name.equals(HtmlConstants.STYLE)) {
208             state.style = value;
209             return;
210         }
211
212         state.registerAttribute(AbstractHtmlState.ATTR_GENERAL, name, value);
213     }
214 }
215
Popular Tags