001 // Copyright 2004, 2005 The Apache Software Foundation
002 //
003 // Licensed under the Apache License, Version 2.0 (the "License");
004 // you may not use this file except in compliance with the License.
005 // You may obtain a copy of the License at
006 //
007 // http://www.apache.org/licenses/LICENSE-2.0
008 //
009 // Unless required by applicable law or agreed to in writing, software
010 // distributed under the License is distributed on an "AS IS" BASIS,
011 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012 // See the License for the specific language governing permissions and
013 // limitations under the License.
014
015 package org.apache.tapestry.services;
016
017 import java.util.Locale;
018
019 import org.apache.hivemind.ClassResolver;
020 import org.apache.hivemind.Resource;
021 import org.apache.tapestry.IRequestCycle;
022 import org.apache.tapestry.asset.AssetFactory;
023 import org.apache.tapestry.coerce.ValueConverter;
024 import org.apache.tapestry.describe.HTMLDescriber;
025 import org.apache.tapestry.engine.IPageSource;
026 import org.apache.tapestry.engine.IPropertySource;
027 import org.apache.tapestry.engine.IScriptSource;
028 import org.apache.tapestry.engine.ISpecificationSource;
029 import org.apache.tapestry.engine.state.ApplicationStateManager;
030 import org.apache.tapestry.error.ExceptionPresenter;
031 import org.apache.tapestry.error.RequestExceptionReporter;
032 import org.apache.tapestry.error.StaleLinkExceptionPresenter;
033 import org.apache.tapestry.error.StaleSessionExceptionPresenter;
034 import org.apache.tapestry.listener.ListenerInvoker;
035 import org.apache.tapestry.listener.ListenerMapSource;
036 import org.apache.tapestry.markup.MarkupWriterSource;
037 import org.apache.tapestry.spec.IApplicationSpecification;
038 import org.apache.tapestry.web.WebRequest;
039 import org.apache.tapestry.web.WebResponse;
040
041 /**
042 * Tapestry infrastructure ... key services required by the
043 * {@link org.apache.tapestry.IEngine} instance.
044 *
045 * @author Howard Lewis Ship
046 * @since 4.0
047 */
048 public interface Infrastructure
049 {
050
051 /**
052 * Initializes the Infrastructure for a particular mode.
053 *
054 * @throws IllegalStateException
055 * if the Infrastructure has already been initialized.
056 */
057
058 void initialize(String mode);
059
060 /**
061 * Returns a named property.
062 *
063 * @throws IllegalStateException
064 * if the Infrastructure has not yet been initialized.
065 * @throws org.apache.hivemind.ApplicationRuntimeException
066 * if no value has been contributed for specified property name.
067 */
068
069 Object getProperty(String propertyName);
070
071 /**
072 * Returns the {@link org.apache.tapestry.spec.IApplicationSpecification} for
073 * the current application.
074 */
075
076 IApplicationSpecification getApplicationSpecification();
077
078 /**
079 * Returns an {@link IPropertySource} configured to search the
080 * application specification, etc. See
081 * <code>tapestry.ApplicationPropertySource</code>.
082 */
083 IPropertySource getApplicationPropertySource();
084
085 /**
086 * Returns an {@link IPropertySource} configured to search the
087 * servlet, servlet context, and factory defaults.
088 */
089
090 IPropertySource getGlobalPropertySource();
091
092 /**
093 * Returns the coordinator to be notified of reset events (which will, in
094 * turn, notify other services that they should discard cached data).
095 */
096
097 ResetEventHub getResetEventHub();
098
099 /**
100 * Returns the source of component message bundles.
101 */
102
103 ComponentMessagesSource getComponentMessagesSource();
104
105 /**
106 * Returns component or page template contents.
107 */
108
109 TemplateSource getTemplateSource();
110
111 /**
112 * Returns the source of all application, page, component and library
113 * specifications.
114 */
115
116 ISpecificationSource getSpecificationSource();
117
118 /**
119 * Returns a generic, shared ObjectPool instance.
120 */
121 ObjectPool getObjectPool();
122
123 /**
124 * Returns the source for pages. The source is a cache of pages, but also
125 * can create new instances when needed.
126 */
127
128 IPageSource getPageSource();
129
130 /**
131 * Returns the ClassResolver used by the Tapestry HiveMind module, which
132 * should be sufficient for use throughout the application.
133 */
134
135 ClassResolver getClassResolver();
136
137 /**
138 * The DataSqueezer, used when constructing and decoding values stored in
139 * URLs (as query parameters or hidden form fields).
140 */
141
142 DataSqueezer getDataSqueezer();
143
144 /**
145 * The source for ready-to-execute versions of Tapestry script templates.
146 */
147
148 IScriptSource getScriptSource();
149
150 /**
151 * The object from which engine services are obtained.
152 */
153
154 ServiceMap getServiceMap();
155
156 /**
157 * Service used to report exceptions to the console.
158 */
159
160 RequestExceptionReporter getRequestExceptionReporter();
161
162 /**
163 * Renders the active page as the response.
164 */
165
166 ResponseRenderer getResponseRenderer();
167
168 /**
169 * Constructs {@link org.apache.tapestry.engine.ILink} instances for
170 * {@link org.apache.tapestry.engine.IEngineService}s.
171 */
172
173 LinkFactory getLinkFactory();
174
175 /**
176 * Used by the {@link org.apache.tapestry.IEngine} to create instances
177 * of {@link org.apache.tapestry.IRequestCycle}.
178 */
179
180 RequestCycleFactory getRequestCycleFactory();
181
182 /**
183 * Accesses application state objects (Visit and Global from Tapestry 3.0,
184 * but now more can be created).
185 */
186
187 ApplicationStateManager getApplicationStateManager();
188
189 /**
190 * Returns the request for the current request cycle.
191 */
192
193 WebRequest getRequest();
194
195 /**
196 * Returns the response for the current request cycle.
197 */
198
199 WebResponse getResponse();
200
201 /**
202 * Returns the context path, which identifies the application within the
203 * application server. Context path should be used as a prefix for any URLs
204 * generated. The context path may be the empty string, and will not end in
205 * a slash (servlet paths should start with a slash).
206 */
207
208 String getContextPath();
209
210 /**
211 * Returns the application's id; a unique name that is incorporated into
212 * various session attribute keys and into certain paths when searching for
213 * resources. For a servlet-based Tapestry application, the id is the name
214 * of the servlet.
215 */
216
217 String getApplicationId();
218
219 /**
220 * Returns the root context resource, which is the starting point when
221 * looking for resources within the application.
222 */
223
224 Resource getContextRoot();
225
226 /**
227 * Returns an object used to access component meta-data properties.
228 */
229
230 ComponentPropertySource getComponentPropertySource();
231
232 /**
233 * Invoked when the locale for the current thread is changed.
234 *
235 * @see org.apache.tapestry.IEngine#setLocale(Locale)
236 */
237
238 void setLocale(Locale value);
239
240 String getOutputEncoding();
241
242 MarkupWriterSource getMarkupWriterSource();
243
244 HTMLDescriber getHTMLDescriber();
245
246 /**
247 * Responsible for presenting an exception error report to the user.
248 */
249
250 ExceptionPresenter getExceptionPresenter();
251
252 /**
253 * The source for {@link org.apache.tapestry.listener.ListenerMap}s, for
254 * components or other objects.
255 */
256
257 ListenerMapSource getListenerMapSource();
258
259 /**
260 * The service responsible for reporting
261 * {@link org.apache.tapestry.StaleSessionException}s.
262 */
263
264 StaleSessionExceptionPresenter getStaleSessionExceptionPresenter();
265
266 /**
267 * The service responsible for reporting
268 * {@link org.apache.tapestry.StaleLinkException}s.
269 */
270
271 StaleLinkExceptionPresenter getStaleLinkExceptionPresenter();
272
273 /**
274 * Service used to convert and coerce types.
275 */
276
277 ValueConverter getValueConverter();
278
279 /**
280 * Service (possibly a pipeline) that will invoke
281 * {@link org.apache.tapestry.IActionListener} objects.
282 */
283
284 ListenerInvoker getListenerInvoker();
285
286 /**
287 * Service that is used to convert {@link org.apache.hivemind.Resource}s
288 * into {@link org.apache.tapestry.IAsset}s.
289 */
290
291 AssetFactory getAssetFactory();
292
293 /**
294 * Service used to access HTTP Cookies. This is only available for Servlet
295 * Tapestry; a placeholder will be provided for Portlet Tapestry.
296 */
297
298 CookieSource getCookieSource();
299
300 /**
301 * Used to search for a class name within a list of packages.
302 */
303
304 ClassFinder getClassFinder();
305
306 /**
307 * Returns the request cycle for the current thread.
308 */
309 IRequestCycle getRequestCycle();
310 }