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.event.HandlerContext;
044:
045: import java.io.IOException;
046: import java.util.ArrayList;
047: import java.util.EventObject;
048: import java.util.HashMap;
049: import java.util.Iterator;
050: import java.util.List;
051: import java.util.Map;
052:
053: import javax.faces.context.FacesContext;
054: import javax.faces.context.ResponseWriter;
055: import javax.faces.component.UIColumn;
056: import javax.faces.component.UIComponent;
057: import javax.faces.component.UIData;
058: import javax.faces.component.UIViewRoot;
059: import javax.faces.render.Renderer;
060:
061: /**
062: * <P> This interface is declares the methods required to be a
063: * LayoutElement. A LayoutElement is the building block of the tree
064: * structure which defines a layout for a particular component. There are
065: * different implementations of LayoutElement that provide various
066: * different types of functionality and data. Some examples are:</P>
067: *
068: * <UL><LI>Conditional ({@link LayoutIf}), this allows portions of the
069: * layout tree to be conditionally rendered.</LI>
070: * <LI>Iterative ({@link LayoutWhile}), this allows portions of the
071: * layout tree to be iteratively rendered.</LI>
072: * <LI>UIComponent ({@link LayoutComponent}), this allows concrete
073: * UIComponents to be used. If the component doesn't already exist,
074: * it will be created automatically.</LI>
075: * <LI>Facet place holders ({@link LayoutFacet}), this provides a means
076: * to specify where a facet should be rendered. It is not a facet
077: * itself but where a facet should be drawn. However, in addition,
078: * it may specify a default value if no facet was provided.</LI></UL>
079: *
080: * @author Ken Paulsen (ken.paulsen@sun.com)
081: */
082: public interface LayoutElement extends java.io.Serializable {
083:
084: /**
085: * This method is used to add a LayoutElement. LayoutElements should be
086: * added sequentially in the order in which they are to be rendered.
087: */
088: public void addChildLayoutElement(LayoutElement element);
089:
090: /**
091: * This method returns the child LayoutElements as a List.
092: *
093: * @return List of LayoutElements
094: */
095: public List getChildLayoutElements();
096:
097: /**
098: * This method returns the parent LayoutElement.
099: *
100: * @return parent LayoutElement
101: */
102: public LayoutElement getParent();
103:
104: /**
105: * This method returns the LayoutDefinition. If unable to, it will throw
106: * an Exception.
107: *
108: * @return The LayoutDefinition
109: */
110: public LayoutDefinition getLayoutDefinition();
111:
112: /**
113: * <P> This method retrieves the Handlers for the requested type.</P>
114: *
115: * @param type The type of Handlers to retrieve.
116: *
117: * @return A List of Handlers.
118: */
119: public List getHandlers(String type);
120:
121: /**
122: * <P> This method associates 'type' with the given list of Handlers.</P>
123: *
124: * @param type The String type for the List of Handlers
125: * @param handlers The List of Handlers
126: */
127: public void setHandlers(String type, List handlers);
128:
129: /**
130: * Accessor method for id. This should always return a non-null value,
131: * it may return "" if id does not apply.
132: *
133: * @return a non-null id
134: */
135: public String getId(FacesContext context, UIComponent parent);
136:
137: /**
138: * <p> This method generally should not be used. It does not resolve
139: * expressions. Instead use
140: * {@link #getId(FacesContext, UIComponent)}.</p>
141: *
142: * @return The unevaluated id.
143: */
144: public String getUnevaluatedId();
145:
146: /**
147: * This method performs any encode action for this particular
148: * LayoutElement.
149: *
150: * @param context The FacesContext
151: * @param component The UIComponent
152: */
153: public void encode(FacesContext context, UIComponent component)
154: throws IOException;
155:
156: /**
157: *
158: */
159: public Object dispatchHandlers(HandlerContext handlerCtx,
160: List handlers);
161:
162: /**
163: * <P> This method iterates over the handlers and executes each one. A
164: * HandlerContext will be created to pass to each Handler. The
165: * HandlerContext object is reused across all Handlers that are
166: * invoked; the setHandler(Handler) method is invoked with the
167: * correct Handler descriptor before the handler is executed.</P>
168: *
169: * @param context The FacesContext
170: * @param eventType The event type which is being fired
171: * @param event An optional EventObject providing more detail
172: *
173: * @return By default, (null) is returned. However, if any of the
174: * handlers produce a non-null return value, then the value from
175: * the last handler to produces a non-null return value is
176: * returned.
177: */
178: public Object dispatchHandlers(FacesContext context,
179: String eventType, EventObject event);
180: }
|