IEngine


1   // Copyright 2004, 2005 The Apache Software Foundation
2   //
3   // Licensed under the Apache License, Version 2.0 (the "License");
4   // you may not use this file except in compliance with the License.
5   // You may obtain a copy of the License at
6   //
7   //     http://www.apache.org/licenses/LICENSE-2.0
8   //
9   // Unless required by applicable law or agreed to in writing, software
10  // distributed under the License is distributed on an "AS IS" BASIS,
11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  // See the License for the specific language governing permissions and
13  // limitations under the License.
14  
15  package org.apache.tapestry;
16  
17  import java.util.Locale  ;
18  
19  import org.apache.hivemind.ClassResolver;
20  import org.apache.tapestry.engine.IEngineService;
21  import org.apache.tapestry.engine.IPropertySource;
22  import org.apache.tapestry.engine.IScriptSource;
23  import org.apache.tapestry.engine.ISpecificationSource;
24  import org.apache.tapestry.services.Infrastructure;
25  import org.apache.tapestry.services.WebRequestServicer;
26  import org.apache.tapestry.spec.IApplicationSpecification;
27  
28  /**
29   * Defines the core, session-persistant object used to run a Tapestry application for a single
30   * client (each client will have its own instance of the engine).
31   * <p>
32   * The engine exists to provide core services to the pages and components that make up the
33   * application. The engine is a delegate to the {@link ApplicationServlet}via the
34   * {@link #service(RequestContext)}method.
35   * <p>
36   * Starting in release 4.0, the engine is kept around only for compatibility (with release 3.0).
37   * It's functions have been moved over into a collection of HiveMind services (or are in the process
38   * of doing so).
39   * 
40   * @author Howard Lewis Ship
41   */
42  
43  public interface IEngine extends WebRequestServicer
44  {
45      /**
46       * Returns the locale for the engine. This locale is used when selecting templates and assets.
47       */
48  
49      public Locale   getLocale();
50  
51      /**
52       * Changes the engine's locale. Any subsequently loaded pages will be in the new locale (though
53       * pages already loaded stay in the old locale). Generally, you should render a new page after
54       * changing the locale, to show that the locale has changed.
55       */
56  
57      public void setLocale(Locale   value);
58  
59      /**
60       * Gets the named service, or throws an {@link org.apache.tapestry.ApplicationRuntimeException}
61       * if the engine can't provide the named service.
62       * 
63       * @deprecated To be removed in 4.1. Engine services can now be injected.
64       */
65  
66      public IEngineService getService(String   name);
67  
68      /**
69       * Returns the application specification that defines the application and its pages.
70       * 
71       * @deprecated To be removed in 4.1. This value can be injected as "infrastructure:applicationSpecification".
72       */
73  
74      public IApplicationSpecification getSpecification();
75  
76      /**
77       * Returns the source of all component specifications for the application. The source is shared
78       * between sessions.
79       * 
80       * @see org.apache.tapestry.engine.AbstractEngine#createSpecificationSource(RequestContext)
81       * @deprecated To be removed in 4.1. This value can be injected as "infrastructure:specificationSource".
82       */
83  
84      public ISpecificationSource getSpecificationSource();
85  
86      /**
87       * Returns an object that can resolve resources and classes.
88       * 
89       * @deprecated To be removed in 4.1. This value can be injected (into services).
90       */
91  
92      public ClassResolver getClassResolver();
93  
94      /**
95       * Returns the visit object, an object that represents the client's visit to the application.
96       * This is where most server-side state is stored (with the exception of persistent page
97       * properties).
98       * <p>
99       * Returns the visit, if it exists, or null if it has not been created.
100      * 
101      * @deprecated To be removed in 4.1. Application state objects can now be injected.
102      */
103 
104     public Object   getVisit();
105 
106     /**
107      * Returns the visit object, creating it if necessary.
108      * 
109      * @deprecated To be removed in 4.1. Application state objects can now be injected.
110      */
111 
112     public Object   getVisit(IRequestCycle cycle);
113 
114     /**
115      * Allows the visit object to be removed; typically done when "shutting down" a user's session
116      * (by setting the visit to null).
117      * 
118      * @deprecated To be removed in 4.1. Application state objects can now be injected.
119      */
120 
121     public void setVisit(Object   value);
122 
123     /**
124      * Returns the globally shared application object. The global object is stored in the servlet
125      * context and shared by all instances of the engine for the same application (within the same
126      * JVM; the global is <em>not</em> shared between nodes in a cluster).
127      * <p>
128      * Returns the global object, if it exists, or null if not defined.
129      * 
130      * @since 2.3
131      * @deprecated To be removed in 4.1. Application state objects can now be injected.
132      */
133 
134     public Object   getGlobal();
135 
136     /**
137      * Returns a source for parsed {@link org.apache.tapestry.IScript}s. The source is shared
138      * between all sessions.
139      * 
140      * @since 1.0.2
141      * @deprecated To be removed in 4.1. This value can now be injected as "infrastructure:scriptSource".
142      */
143 
144     public IScriptSource getScriptSource();
145 
146     /**
147      * Returns a {@link org.apache.tapestry.engine.IPropertySource}that should be used to obtain
148      * configuration data. The returned source represents a search path that includes (at a
149      * minimum):
150      * <ul>
151      * <li>Properties of the {@link org.apache.tapestry.spec.ApplicationSpecification}
152      * <li>Initial Parameters of servlet (configured in the <code>web.xml</code> deployment
153      * descriptor)
154      * <li>Initial Parameter of the servlet context (also configured in <code>web.xml</code>)
155      * <li>System properties (defined with the <code>-D</code> JVM command line parameter)
156      * <li>Hard-coded "factory defaults" (for some properties)
157      * </ul>
158      * 
159      * @since 2.3
160      * @see org.apache.tapestry.engine.AbstractEngine#createPropertySource(RequestContext)
161      * @deprecated To be removed in 4.1. This value can now be injected as "infrastructure:applicationPropertySource".
162      */
163 
164     public IPropertySource getPropertySource();
165 
166     /**
167      * Returns the encoding to be used to generate the responses and accept the requests.
168      * 
169      * @since 3.0
170      */
171 
172     public String   getOutputEncoding();
173 
174     /**
175      * Returns the {@link org.apache.tapestry.services.Infrastructure}&nbsp;object, a central
176      * registry of key HiveMind services used by Tapestry.
177      * 
178      * @since 4.0
179      */
180 
181     public Infrastructure getInfrastructure();
182 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags