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 {@link org.apache.tapestry.IEngine}
043     * instance.
044     * 
045     * @author Howard Lewis Ship
046     * @since 4.0
047     */
048    public 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} 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} 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} 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    }