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} object, a central 176 * registry of key HiveMind services used by Tapestry. 177 * 178 * @since 4.0 179 */ 180 181 public Infrastructure getInfrastructure(); 182 }