1 /*
2 * $Id: RenderKit.java,v 1.36 2007/04/27 22:00:10 ofung Exp $
3 */
4
5 /*
6 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
7 *
8 * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
9 *
10 * The contents of this file are subject to the terms of either the GNU
11 * General Public License Version 2 only ("GPL") or the Common Development
12 * and Distribution License("CDDL") (collectively, the "License"). You
13 * may not use this file except in compliance with the License. You can obtain
14 * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
15 * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
16 * language governing permissions and limitations under the License.
17 *
18 * When distributing the software, include this License Header Notice in each
19 * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
20 * Sun designates this particular file as subject to the "Classpath" exception
21 * as provided by Sun in the GPL Version 2 section of the License file that
22 * accompanied this code. If applicable, add the following below the License
23 * Header, with the fields enclosed by brackets [] replaced by your own
24 * identifying information: "Portions Copyrighted [year]
25 * [name of copyright owner]"
26 *
27 * Contributor(s):
28 *
29 * If you wish your version of this file to be governed by only the CDDL or
30 * only the GPL Version 2, indicate your decision by adding "[Contributor]
31 * elects to include this software in this distribution under the [CDDL or GPL
32 * Version 2] license." If you don't indicate a single choice of license, a
33 * recipient has the option to distribute your version of this file under
34 * either the CDDL, the GPL Version 2 or to extend the choice of license to
35 * its licensees as provided above. However, if you add GPL Version 2 code
36 * and therefore, elected the GPL Version 2 license, then the option applies
37 * only if the new code is made subject to such option by the copyright
38 * holder.
39 */
40
41 package javax.faces.render;
42
43
44 import javax.faces.component.UIComponent;
45 import javax.faces.context.ResponseWriter;
46 import javax.faces.context.ResponseStream;
47 import java.io.Writer;
48 import java.io.OutputStream;
49
50
51 /**
52 * <p><strong>RenderKit</strong> represents a collection of
53 * {@link Renderer} instances that, together, know how to render
54 * JavaServer Faces {@link UIComponent} instances for a specific
55 * client. Typically, {@link RenderKit}s are specialized for
56 * some combination of client device type, markup language, and/or
57 * user <code>Locale</code>. A {@link RenderKit} also acts as
58 * a Factory for associated {@link Renderer} instances, which perform the
59 * actual rendering process for each component.</p>
60 *
61 * <p>A typical JavaServer Faces implementation will configure one or
62 * more {@link RenderKit} instances at web application startup. They
63 * are made available through calls to the <code>getRenderKit()</code>
64 * methods of {@link RenderKitFactory}. Because {@link RenderKit}
65 * instances are shared, they must be implemented in a thread-safe
66 * manner. Due to limitations in the current specification having
67 * multiple <code>RenderKit</code> instances at play in the same
68 * application requires a custom {@link
69 * javax.faces.application.ViewHandler} instance that is aware of how to
70 * deal with this case. This limitation will be lifted in a future
71 * version of the spec.</p>
72 *
73 * <p>The <code>RenderKit</code> instance must also vend a {@link
74 * ResponseStateManager} instance, which is used in the process of
75 * saving and restoring tree structure and state.</p>
76 */
77 // PENDING(edburns): remove limitation
78 public abstract class RenderKit {
79
80
81 /**
82 * <p>Register the specified {@link Renderer} instance, associated with the
83 * specified component <code>family</code> and <code>rendererType</code>,
84 * to the set of {@link Renderer}s registered with this {@link RenderKit},
85 * replacing any previously registered {@link Renderer} for this
86 * combination of identifiers.</p>
87 *
88 * @param family Component family of the {@link Renderer} to register
89 * @param rendererType Renderer type of the {@link Renderer} to register
90 * @param renderer {@link Renderer} instance we are registering
91 *
92 * @throws NullPointerException if <code>family</code> or
93 * <code>rendererType</code> or <code>renderer</code> is null
94 */
95 public abstract void addRenderer(String family, String rendererType,
96 Renderer renderer);
97
98
99 /**
100 * <p>Return the {@link Renderer} instance most recently registered for
101 * the specified component <code>family</code> and
102 * <code>rendererType</code>, if any; otherwise, return
103 * <code>null</code>.</p>
104 *
105 * @param family Component family of the requested
106 * {@link Renderer} instance
107 * @param rendererType Renderer type of the requested
108 * {@link Renderer} instance
109 *
110 * @throws NullPointerException if <code>family</code> or
111 * <code>rendererType</code> is <code>null</code>
112 */
113 public abstract Renderer getRenderer(String family, String rendererType);
114
115
116 /**
117 * <p>Return an instance of {@link ResponseStateManager} to handle
118 * rendering technology specific state management decisions.</p>
119 */
120 public abstract ResponseStateManager getResponseStateManager();
121
122
123 /**
124 * <p>Use the provided <code>Writer</code> to create a new {@link
125 * ResponseWriter} instance for the specified (optional) content
126 * type, and character encoding.</p>
127 *
128 * <p>Implementors are advised to consult the
129 * <code>getCharacterEncoding()</code> method of class {@link
130 * javax.servlet.ServletResponse} to get the required value for the
131 * characterEncoding for this method. Since the <code>Writer</code>
132 * for this response will already have been obtained (due to it
133 * ultimately being passed to this method), we know that the
134 * character encoding cannot change during the rendering of the
135 * response.</p>
136 *
137 * @param writer the Writer around which this {@link ResponseWriter}
138 * must be built.
139 *
140 * @param contentTypeList an "Accept header style" list of content
141 * types for this response, or <code>null</code> if the RenderKit
142 * should choose the best fit. As of the current version, the
143 * values accepted by the Standard render-kit for this parameter
144 * include any valid "Accept header style" String that includes the
145 * String <code>text/html</code>,
146 * <code>application/xhtml+xml</code>, <code>application/xml</code>
147 * or <code>text/xml</code>. This may change in a future version.
148 * The RenderKit must support a value for this argument that comes
149 * straight from the <code>Accept</code> HTTP header, and therefore
150 * requires parsing according to the specification of the
151 * <code>Accept</code> header. Please see <a
152 * href="http://www.ietf.org/rfc/rfc2616.txt?number=2616">Section
153 * 14.1 of RFC 2616</a> for the specification of the
154 * <code>Accept</code> header.
155 *
156 * @param characterEncoding such as "ISO-8859-1" for this
157 * ResponseWriter, or <code>null</code> if the
158 * <code>RenderKit</code> should choose the best fit. Please see <a
159 * href="http://www.iana.org/assignments/character-sets">the
160 * IANA</a> for a list of character encodings.
161 *
162 * @return a new {@link ResponseWriter}.
163 *
164 * @throws IllegalArgumentException if no matching content type
165 * can be found in <code>contentTypeList</code>, no appropriate
166 * content type can be found with the implementation dependent best
167 * fit algorithm, or no matching character encoding can be found for
168 * the argument <code>characterEncoding</code>.
169 *
170 */
171 public abstract ResponseWriter createResponseWriter(Writer writer,
172 String contentTypeList,
173 String characterEncoding);
174
175
176 /**
177 * <p>Use the provided <code>OutputStream</code> to create a new
178 * {@link ResponseStream} instance.</p>
179 *
180 */
181 public abstract ResponseStream createResponseStream(OutputStream out);
182
183
184 }
Save This Page