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; 016 017import java.util.Locale; 018 019import org.apache.hivemind.ClassResolver; 020import org.apache.tapestry.engine.IEngineService; 021import org.apache.tapestry.engine.IPropertySource; 022import org.apache.tapestry.engine.IScriptSource; 023import org.apache.tapestry.engine.ISpecificationSource; 024import org.apache.tapestry.services.Infrastructure; 025import org.apache.tapestry.services.WebRequestServicer; 026import org.apache.tapestry.spec.IApplicationSpecification; 027 028/** 029 * Defines the core, session-persistant object used to run a Tapestry application for a single 030 * client (each client will have its own instance of the engine). 031 * <p> 032 * The engine exists to provide core services to the pages and components that make up the 033 * application. The engine is a delegate to the {@link ApplicationServlet}via the 034 * {@link #service(RequestContext)}method. 035 * <p> 036 * Starting in release 4.0, the engine is kept around only for compatibility (with release 3.0). 037 * It's functions have been moved over into a collection of HiveMind services (or are in the process 038 * of doing so). 039 * 040 * @author Howard Lewis Ship 041 */ 042 043public interface IEngine extends WebRequestServicer 044{ 045 /** 046 * Returns the locale for the engine. This locale is used when selecting templates and assets. 047 */ 048 049 public Locale getLocale(); 050 051 /** 052 * Changes the engine's locale. Any subsequently loaded pages will be in the new locale (though 053 * pages already loaded stay in the old locale). Generally, you should render a new page after 054 * changing the locale, to show that the locale has changed. 055 */ 056 057 public void setLocale(Locale value); 058 059 /** 060 * Gets the named service, or throws an {@link org.apache.tapestry.ApplicationRuntimeException} 061 * if the engine can't provide the named service. 062 * 063 * @deprecated To be removed in 4.1. Engine services can now be injected. 064 */ 065 066 public IEngineService getService(String name); 067 068 /** 069 * Returns the application specification that defines the application and its pages. 070 * 071 * @deprecated To be removed in 4.1. This value can be injected as "infrastructure:applicationSpecification". 072 */ 073 074 public IApplicationSpecification getSpecification(); 075 076 /** 077 * Returns the source of all component specifications for the application. The source is shared 078 * between sessions. 079 * 080 * @see org.apache.tapestry.engine.AbstractEngine#createSpecificationSource(RequestContext) 081 * @deprecated To be removed in 4.1. This value can be injected as "infrastructure:specificationSource". 082 */ 083 084 public ISpecificationSource getSpecificationSource(); 085 086 /** 087 * Returns an object that can resolve resources and classes. 088 * 089 * @deprecated To be removed in 4.1. This value can be injected (into services). 090 */ 091 092 public ClassResolver getClassResolver(); 093 094 /** 095 * Returns the visit object, an object that represents the client's visit to the application. 096 * This is where most server-side state is stored (with the exception of persistent page 097 * properties). 098 * <p> 099 * 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}