1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.myfaces.view.facelets;
20
21 import javax.el.ELException;
22 import javax.faces.FacesException;
23 import javax.faces.view.facelets.FaceletException;
24 import java.io.IOException;
25 import java.net.URL;
26 import java.util.Map;
27 import javax.faces.context.FacesContext;
28 import javax.faces.view.facelets.Facelet;
29 import javax.faces.view.facelets.FaceletContext;
30
31 /**
32 * FaceletFactory for producing Facelets relative to the context of the underlying implementation.
33 *
34 * @author Jacob Hookom
35 * @version $Id$
36 */
37 public abstract class FaceletFactory
38 {
39
40 private static ThreadLocal<FaceletFactory> instance = new ThreadLocal<FaceletFactory>();
41
42 public final static String LAST_RESOURCE_RESOLVED = "oam.facelets.LAST_RESOURCE_RESOLVED";
43
44 /**
45 * Return a Facelet instance as specified by the file at the passed URI.
46 *
47 * @param uri
48 * @return
49 * @throws IOException
50 * @throws FaceletException
51 * @throws FacesException
52 * @throws ELException
53 */
54 public abstract Facelet getFacelet(FacesContext context, String uri) throws IOException;
55
56 /**
57 * Create a Facelet from the passed URL. This method checks if the cached Facelet needs to be refreshed before
58 * returning. If so, uses the passed URL to build a new instance;
59 *
60 * @param url
61 * source url
62 * @return Facelet instance
63 * @throws IOException
64 * @throws FaceletException
65 * @throws FacesException
66 * @throws ELException
67 */
68 public abstract Facelet getFacelet(URL url) throws IOException, FaceletException, FacesException, ELException;
69
70 /**
71 * Create a Facelet from the passed URL, but take into account the context. This method is
72 * useful in cases where the facelet instance must replace the one in the cache based on
73 * the context, instead take the one from the cache, like for example when the EL expression
74 * cache is used.
75 *
76 * @param url
77 * source url
78 * @return Facelet instance
79 * @throws IOException
80 * @throws FaceletException
81 * @throws FacesException
82 * @throws ELException
83 */
84 public abstract Facelet getFacelet(FaceletContext ctx, URL url)
85 throws IOException, FaceletException, FacesException, ELException;
86
87 /**
88 * Return a Facelet instance as specified by the file at the passed URI. The returned facelet is used
89 * to create view metadata in this form:
90 * <p>
91 * UIViewRoot(in facet javax_faces_metadata(one or many UIViewParameter instances))
92 * </p>
93 * <p>
94 * This method should be called from FaceletViewMetadata.createMetadataView(FacesContext context)
95 * </p>
96 *
97 * @since 2.0
98 * @param uri
99 * @return
100 * @throws IOException
101 */
102 public abstract Facelet getViewMetadataFacelet(
103 FacesContext context, String uri) throws IOException;
104
105 /**
106 * Create a Facelet used to create view metadata from the passed URL. This method checks if the
107 * cached Facelet needs to be refreshed before returning. If so, uses the passed URL to build a new instance;
108 *
109 * @since 2.0
110 * @param url source url
111 * @return Facelet instance
112 * @throws IOException
113 * @throws FaceletException
114 * @throws FacesException
115 * @throws ELException
116 */
117 public abstract Facelet getViewMetadataFacelet(URL url)
118 throws IOException, FaceletException, FacesException, ELException;
119
120 /**
121 * Return a Facelet instance as specified by the file at the passed URI. The returned facelet is used
122 * to create composite component metadata.
123 * <p>
124 * This method should be called from vdl.getComponentMetadata(FacesContext context)
125 * </p>
126 *
127 * @since 2.0.1
128 * @param uri
129 * @return
130 * @throws IOException
131 */
132 public abstract Facelet getCompositeComponentMetadataFacelet(FacesContext context, String uri)
133 throws IOException;
134
135 /**
136 * Create a Facelet used to create composite component metadata from the passed URL. This method checks if the
137 * cached Facelet needs to be refreshed before returning. If so, uses the passed URL to build a new instance.
138 *
139 * @since 2.0.1
140 * @param url source url
141 * @return Facelet instance
142 * @throws IOException
143 * @throws FaceletException
144 * @throws FacesException
145 * @throws ELException
146 */
147 public abstract Facelet getCompositeComponentMetadataFacelet(URL url)
148 throws IOException, FaceletException, FacesException, ELException;
149
150 /**
151 * Compile a component tag on the fly.
152 *
153 * @param taglibURI
154 * @param tagName
155 * @param attributes
156 * @return
157 */
158 public abstract Facelet compileComponentFacelet(String taglibURI, String tagName, Map<String,Object> attributes);
159
160 /**
161 * Set the static instance
162 *
163 * @param factory
164 */
165 public static final void setInstance(FaceletFactory factory)
166 {
167 if (factory == null)
168 {
169 instance.remove();
170 }
171 else
172 {
173 instance.set(factory);
174 }
175 }
176
177 /**
178 * Get the static instance
179 *
180 * @return
181 */
182 public static final FaceletFactory getInstance()
183 {
184 return instance.get();
185 }
186 }