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