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