001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2007 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041: package com.sun.rave.web.ui.component.util.descriptors;
042:
043: import com.sun.rave.web.ui.component.util.Util;
044: import com.sun.rave.web.ui.component.util.event.AfterEncodeEvent;
045: import com.sun.rave.web.ui.component.util.event.BeforeEncodeEvent;
046: import com.sun.rave.web.ui.component.util.event.EncodeEvent;
047: import com.sun.rave.web.ui.component.util.event.Handler;
048: import com.sun.rave.web.ui.component.util.event.HandlerContext;
049: import com.sun.rave.web.ui.component.util.event.HandlerContextImpl;
050: import com.sun.rave.web.ui.util.RenderingUtilities;
051: import com.sun.rave.web.ui.util.VariableResolver;
052:
053: import java.io.IOException;
054: import java.util.ArrayList;
055: import java.util.EventObject;
056: import java.util.HashMap;
057: import java.util.Iterator;
058: import java.util.List;
059: import java.util.Map;
060:
061: import javax.faces.component.UIComponent;
062: import javax.faces.context.FacesContext;
063: import javax.faces.el.ValueBinding;
064: import javax.faces.webapp.UIComponentTag;
065:
066: /**
067: * <p>This class provides some common functionality between the various types
068: * of LayoutElements. It is the base class of most implementations (perhaps
069: * all).</p>
070: *
071: * @author Ken Paulsen (ken.paulsen@sun.com)
072: */
073: public abstract class LayoutElementBase implements LayoutElement {
074:
075: /**
076: * Constructor
077: *
078: * @param parent The parent LayoutElement
079: * @param id Identifier for this LayoutElement
080: */
081: protected LayoutElementBase(LayoutElement parent, String id) {
082: setParent(parent);
083: _id = id;
084: }
085:
086: /**
087: * This method is used to add a LayoutElement. LayoutElements should be
088: * added sequentially in the order in which they are to be rendered.
089: *
090: * @param element The LayoutElement to add as a child
091: */
092: public void addChildLayoutElement(LayoutElement element) {
093: _layoutElements.add(element);
094: }
095:
096: /**
097: * This method returns the LayoutElements as a List.
098: *
099: * @return List of LayoutElements
100: */
101: public List getChildLayoutElements() {
102: return _layoutElements;
103: }
104:
105: /**
106: * This method walks to the top-most LayoutElement, which should be a
107: * LayoutDefinition. If not, it will throw an Exception.
108: *
109: * @return The LayoutDefinition
110: */
111: public LayoutDefinition getLayoutDefinition() {
112: // Find the top-most LayoutElement
113: LayoutElement cur = this ;
114: while (cur.getParent() != null) {
115: cur = cur.getParent();
116: }
117:
118: // This should be the LayoutDefinition, return it
119: return (LayoutDefinition) cur;
120: }
121:
122: /**
123: * This method returns the parent LayoutElement.
124: *
125: * @return parent LayoutElement
126: */
127: public LayoutElement getParent() {
128: return _parent;
129: }
130:
131: /**
132: * This method sets the parent LayoutElement.
133: *
134: * @param parent Parent LayoutElement
135: */
136: protected void setParent(LayoutElement parent) {
137: _parent = parent;
138: }
139:
140: /**
141: * <p> Accessor method for id. This returns a non-null value, it may
142: * return "" if id is not set or does not apply.</p>
143: *
144: * <p> This method will also NOT resolve EL strings.</p>
145: *
146: * @return a non-null id
147: */
148: private String getId() {
149: if (_id == null) {
150: return "";
151: }
152: return _id;
153: }
154:
155: /**
156: * <p> This method generally should not be used. It does not resolve
157: * expressions. Instead use
158: * {@link #getId(FacesContext, UIComponent)}.</p>
159: *
160: * @return The unevaluated id.
161: */
162: public String getUnevaluatedId() {
163: return _id;
164: }
165:
166: /**
167: * <p> Accessor method for id. This returns a non-null value, it may
168: * return "" if id is not set or does not apply.</p>
169: *
170: * <p> This method will also attempt to resolve EL strings.</p>
171: *
172: * @param context The <code>FacesContext</code>
173: * @param parent The parent <code>UIComponent</code>. This is used
174: * because the current UIComponent is typically
175: * unknown (or not even created yet).
176: *
177: * @return a non-null id
178: */
179: public String getId(FacesContext context, UIComponent parent) {
180: // Evaluate the id...
181: Object value = resolveValue(context, parent, getId());
182:
183: // Return the result
184: return (value == null) ? "" : value.toString();
185: }
186:
187: /**
188: * <p> This method will attempt to resolve EL strings in the given
189: * value.</p>
190: *
191: * @param context The <code>FacesContext</code>
192: * @param parent The parent <code>UIComponent</code>. This is used
193: * because the current UIComponent is typically
194: * unknown (or not even created yet).
195: * @param value The String to resolve
196: *
197: * @return The evaluated value (may be null).
198: */
199: public Object resolveValue(FacesContext context,
200: UIComponent parent, String value) {
201: return Util.resolveValue(context, this , parent, value);
202: }
203:
204: /**
205: * <p> This method allows each LayoutElement to provide it's own encode
206: * functionality. If the <code>LayoutElement</code> should render its
207: * children, this method should return true. Otherwise, this method
208: * should return false.</p>
209: *
210: * @param context The FacesContext
211: * @param component The UIComponent
212: *
213: * @return true if children are to be rendered, false otherwise.
214: */
215: protected abstract boolean encodeThis(FacesContext context,
216: UIComponent component) throws IOException;
217:
218: /**
219: * <p> This is the base implementation for encode. Typically each type of
220: * LayoutElement wants to do something specific then conditionally have
221: * its children rendered. This method invokes the abstract method
222: * "encodeThis" to do specific functionality, it the walks the children
223: * and renders them, if encodeThis returns true. It skips the children
224: * if encodeThis returns false.</p>
225: *
226: * @param context The <code>FacesContext</code>
227: * @param component The <code>UIComponent</code>
228: */
229: public void encode(FacesContext context, UIComponent component)
230: throws IOException {
231: // Invoke "before" handlers
232: // FIXME: Consider true/false for skipping component
233: Object result = dispatchHandlers(context, BEFORE_ENCODE,
234: new BeforeEncodeEvent(component));
235:
236: // Do LayoutElement specific stuff...
237: boolean renderChildren = encodeThis(context, component);
238:
239: // FIXME: Consider buffering HTML and passing to "endDisplay" handlers...
240: // FIXME: Storing in the EventObject may be useful if we go this route.
241: // Perhaps we want our own Response writer to buffer children?
242: //ResponseWriter out = context.getResponseWriter();
243:
244: // Conditionally render children...
245: if (renderChildren) {
246: result = dispatchHandlers(context, ENCODE, new EncodeEvent(
247: component));
248:
249: // Iterate over children
250: LayoutElement childElt = null;
251: Iterator it = getChildLayoutElements().iterator();
252: while (it.hasNext()) {
253: childElt = (LayoutElement) it.next();
254: childElt.encode(context, component);
255: }
256: }
257:
258: // Invoke "after" handlers
259: result = dispatchHandlers(context, AFTER_ENCODE,
260: new AfterEncodeEvent(component));
261: }
262:
263: /**
264: * <p> This method iterates over the handlers and executes each one. A
265: * HandlerContext will be created to pass to each Handler. The
266: * HandlerContext object is reused across all Handlers that are
267: * invoked; the setHandler(Handler) method is invoked with the
268: * correct Handler descriptor before the handler is executed.</p>
269: *
270: * @param context The FacesContext
271: * @param eventType The event type which is being fired
272: * @param event An optional EventObject providing more detail
273: *
274: * @return By default, (null) is returned. However, if any of the
275: * handlers produce a non-null return value, then the value from
276: * the last handler to produces a non-null return value is
277: * returned.
278: */
279: public Object dispatchHandlers(FacesContext context,
280: String eventType, EventObject event) {
281: // Get the handlers for this eventType
282: Object eventObj = event.getSource();
283: if (!(eventObj instanceof UIComponent)) {
284: eventObj = null;
285: }
286: List handlers = getHandlers(eventType, (UIComponent) eventObj);
287:
288: // Make sure we have something to do...
289: if (handlers == null) {
290: return null;
291: }
292:
293: // Create a HandlerContext
294: HandlerContext handlerContext = createHandlerContext(context,
295: event, eventType);
296:
297: // This method is broken down so that recursion is easier
298: return dispatchHandlers(handlerContext, handlers);
299: }
300:
301: /**
302: * <p> As currently implemented, this method is essentially a utility
303: * method. May want to rethink this.</p>
304: */
305: public Object dispatchHandlers(HandlerContext handlerCtx,
306: List handlers) {
307: Object retVal = null;
308: Object result = null;
309: Handler handler = null;
310: Iterator it = handlers.iterator();
311: while (it.hasNext()) {
312: try {
313: // Get the Handler
314: handler = (Handler) it.next();
315: handlerCtx.setHandler(handler);
316:
317: // Delegate to the Handler to perform invocation
318: retVal = handler.invoke(handlerCtx);
319:
320: // Check for return value
321: if (retVal != null) {
322: result = retVal;
323: }
324: } catch (Exception ex) {
325: throw new RuntimeException(ex.getClass().getName()
326: + " while attempting to " + "process a '"
327: + handlerCtx.getEventType() + "' event for '"
328: + getId() + "'.", ex);
329: }
330: }
331:
332: // Return the return value (null by default)
333: return result;
334: }
335:
336: /**
337: * <p> This method is responsible for creating a new HandlerContext. It
338: * does not set the Handler descriptor. This is done right before a
339: * Handler is invoked. This allows the HandlerContext object to be
340: * reused.</p>
341: *
342: * @param context The FacesContext
343: */
344: protected HandlerContext createHandlerContext(FacesContext context,
345: EventObject event, String eventType) {
346: return new HandlerContextImpl(context, this , event, eventType);
347: }
348:
349: /**
350: * <p> This method retrieves the Handlers for the requested type.</p>
351: *
352: * @param type The type of Handlers to retrieve.
353: *
354: * @return A List of Handlers.
355: */
356: public List getHandlers(String type) {
357: return (List) _handlersByType.get(type);
358: }
359:
360: /**
361: * <p> This method provides access to the "handlersByType"
362: * <code>Map</code>.</p>
363: */
364: public Map getHandlersByTypeMap() {
365: return _handlersByType;
366: }
367:
368: /**
369: * <p> This method provides a means to set the "handlersByType" Map.
370: * Normally this is done for each type individually via
371: * {@link #setHandlers(String, List)}. This Map may not be null (null
372: * will be ignored) and should contain entries that map to
373: * <code>List</code>s of {@link Handler}s.
374: */
375: public void setHandlersByTypeMap(Map map) {
376: if (map != null) {
377: _handlersByType = map;
378: }
379: }
380:
381: /**
382: * <p> This method retrieves the Handlers for the requested type. But
383: * also includes any handlers that are associated with the instance
384: * (i.e. the UIComponent).</p>
385: *
386: * @param type The type of <code>Handler</code>s to retrieve.
387: * @param event The associated <code>UIComponent</code> (or null).
388: *
389: * @return A List of Handlers.
390: */
391: public List getHandlers(String type, UIComponent comp) {
392: // 1st get list of handlers for definition of this LayoutElement
393: List handlers = null;
394:
395: // Now check to see if there are any on the UIComponent
396: if (comp != null) {
397: List instHandlers = (List) comp.getAttributes().get(type);
398: if ((instHandlers != null) && (instHandlers.size() > 0)) {
399: // NOTE: Copy b/c this is <i>instance</i> + static
400: // Add the UIComponent instance handlers
401: handlers = new ArrayList(instHandlers);
402:
403: List defHandlers = getHandlers(type);
404: if (defHandlers != null) {
405: // Add the LayoutElement "definition" handlers, if any
406: handlers.addAll(getHandlers(type));
407: }
408: }
409: }
410: if (handlers == null) {
411: handlers = getHandlers(type);
412: }
413:
414: return handlers;
415: }
416:
417: /**
418: * <p> This method associates 'type' with the given list of Handlers.</p>
419: *
420: * @param type The String type for the List of Handlers
421: * @param handlers The List of Handlers
422: */
423: public void setHandlers(String type, List handlers) {
424: _handlersByType.put(type, handlers);
425: }
426:
427: /**
428: * <p> This method is a convenience method for encoding the given
429: * <code>UIComponent</code>. It calls the appropriate encoding
430: * methods on the component and calls itself recursively for all
431: * <code>UIComponent</code> children that do not render their own
432: * children.</p>
433: *
434: * @param context <code>FacesContext</code>
435: * @param component <code>UIComponent</code> to encode
436: */
437: public static void encodeChild(FacesContext context,
438: UIComponent component) throws IOException {
439: RenderingUtilities.renderComponent(component, context);
440: }
441:
442: /**
443: * List of renderable elements (if, facet, UIComponents)
444: */
445: private List _layoutElements = new ArrayList();
446:
447: /**
448: * The parent LayoutElement. This will be null for the LayoutDefinition.
449: */
450: private LayoutElement _parent = null;
451:
452: /**
453: * Map containing Lists of Handlers
454: */
455: private Map _handlersByType = new HashMap();
456:
457: /**
458: * This stores the id for the LayoutElement
459: */
460: private String _id = null;
461:
462: /**
463: * <p> This is the "type" for handlers to be invoked after the encoding
464: * of this element.</p>
465: */
466: public static final String AFTER_ENCODE = "afterEncode";
467:
468: /**
469: * <p> This is the "type" for handlers to be invoked before the encoding
470: * of this element.</p>
471: */
472: public static final String BEFORE_ENCODE = "beforeEncode";
473:
474: /**
475: * <p> This is the "type" for handlers to be invoked during the encoding
476: * of this element. This occurs before any child LayoutElements are
477: * invoked and only if child Elements are to be invoked.</p>
478: */
479: public static final String ENCODE = "encode";
480: }
|