001/* 002 Licensed to the Apache Software Foundation (ASF) under one 003 or more contributor license agreements. See the NOTICE file 004 distributed with this work for additional information 005 regarding copyright ownership. The ASF licenses this file 006 to you under the Apache License, Version 2.0 (the 007 "License"); you may not use this file except in compliance 008 with the License. You may obtain a copy of the License at 009 010 http://www.apache.org/licenses/LICENSE-2.0 011 012 Unless required by applicable law or agreed to in writing, 013 software distributed under the License is distributed on an 014 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 KIND, either express or implied. See the License for the 016 specific language governing permissions and limitations 017 under the License. 018 */ 019package org.apache.wiki.api.core; 020 021import org.apache.logging.log4j.LogManager; 022import org.apache.wiki.api.engine.EngineLifecycleExtension; 023import org.apache.wiki.api.exceptions.ProviderException; 024import org.apache.wiki.api.exceptions.WikiException; 025import org.apache.wiki.event.WikiEventListener; 026import org.apache.wiki.util.TextUtil; 027 028import javax.servlet.ServletContext; 029import java.io.File; 030import java.io.FileNotFoundException; 031import java.io.IOException; 032import java.io.InputStream; 033import java.io.OutputStream; 034import java.net.MalformedURLException; 035import java.net.URL; 036import java.nio.charset.Charset; 037import java.nio.file.Files; 038import java.util.Collection; 039import java.util.Date; 040import java.util.List; 041import java.util.Properties; 042import java.util.ServiceLoader; 043 044 045/** 046 * Provides Wiki services to the JSP page. 047 * 048 * <P> 049 * This is the main interface through which everything should go. 050 * 051 * <p> 052 * There's basically only a single Engine for each web application, and you should always get it using either the 053 * {@code Context#getEngine()} method or through {@code Wiki.engine().find(..)} DSL methods. 054 */ 055public interface Engine { 056 057 /** The default inlining pattern. Currently "*.png" */ 058 String DEFAULT_INLINEPATTERN = "*.png"; 059 060 /** The name used for the default template. The value is {@value}. */ 061 String DEFAULT_TEMPLATE_NAME = "default"; 062 063 /** Property for application name */ 064 String PROP_APPNAME = "jspwiki.applicationName"; 065 066 /** This property defines the inline image pattern. It's current value is {@value} */ 067 String PROP_INLINEIMAGEPTRN = "jspwiki.translatorReader.inlinePattern"; 068 069 /** Property start for any interwiki reference. */ 070 String PROP_INTERWIKIREF = "jspwiki.interWikiRef."; 071 072 /** The property name defining which packages will be searched for plugin classes. */ 073 String PROP_SEARCHPATH = "jspwiki.plugin.searchPath"; 074 075 /** If true, then the user name will be stored with the page data.*/ 076 String PROP_STOREUSERNAME= "jspwiki.storeUserName"; 077 078 /** Define the used encoding. Currently supported are ISO-8859-1 and UTF-8 */ 079 String PROP_ENCODING = "jspwiki.encoding"; 080 081 /** Do not use encoding in WikiJSPFilter, default is false for most servers. 082 Double negative, cause for most servers you don't need the property */ 083 String PROP_NO_FILTER_ENCODING = "jspwiki.nofilterencoding"; 084 085 /** Property name for where the jspwiki work directory should be. 086 If not specified, reverts to ${java.tmpdir}. */ 087 String PROP_WORKDIR = "jspwiki.workDir"; 088 089 /** The name of the cookie that gets stored to the user browser. */ 090 String PREFS_COOKIE_NAME = "JSPWikiUserProfile"; 091 092 /** Property name for the "match english plurals" -hack. */ 093 String PROP_MATCHPLURALS = "jspwiki.translatorReader.matchEnglishPlurals"; 094 095 /** Property name for the template that is used. */ 096 String PROP_TEMPLATEDIR = "jspwiki.templateDir"; 097 098 /** Property name for the default front page. */ 099 String PROP_FRONTPAGE = "jspwiki.frontPage"; 100 101 /** Property name for setting the url generator instance */ 102 String PROP_URLCONSTRUCTOR = "jspwiki.urlConstructor"; 103 104 /** The name of the property containing the ACLManager implementing class. The value is {@value}. */ 105 String PROP_ACL_MANAGER_IMPL = "jspwiki.aclManager"; 106 107 /** If this property is set to false, we don't allow the creation of empty pages */ 108 String PROP_ALLOW_CREATION_OF_EMPTY_PAGES = "jspwiki.allowCreationOfEmptyPages"; 109 110 /** 111 * Adapt Engine to a concrete type. 112 * 113 * @param cls class denoting the type to adapt to. 114 * @param <E> type to adapt to. 115 * @return engine instance adapted to the requested type. Might throw an unchecked exception if the instance cannot be adapted to requested type! 116 */ 117 @SuppressWarnings( "unchecked" ) 118 default < E extends Engine > E adapt( final Class< E > cls ) { 119 return ( E )this; 120 } 121 122 /** 123 * Retrieves the object instantiated by the Engine matching the requested type. 124 * 125 * @param manager requested object instantiated by the Engine. 126 * @param <T> type of the requested object. 127 * @return requested object instantiated by the Engine, {@code null} if not available. 128 */ 129 < T > T getManager( Class< T > manager ); 130 131 /** 132 * Retrieves the objects instantiated by the Engine that can be assigned to the requested type. 133 * 134 * @param manager requested objectx instantiated by the Engine. 135 * @param <T> type of the requested object. 136 * @return collection of requested objects instantiated by the Engine, {@code empty} list if none available. 137 */ 138 < T > List< T > getManagers( Class< T > manager ); 139 140 /** 141 * check if the Engine has been configured. 142 * 143 * @return {@code true} if it has, {@code false} otherwise. 144 */ 145 boolean isConfigured(); 146 147 /** 148 * Returns the set of properties that the Engine was initialized with. Note that this method returns a direct reference, so it's 149 * possible to manipulate the properties. However, this is not advised unless you really know what you're doing. 150 * 151 * @return The wiki properties 152 */ 153 Properties getWikiProperties(); 154 155 /** 156 * Returns the JSPWiki working directory set with "jspwiki.workDir". 157 * 158 * @since 2.1.100 159 * @return The working directory. 160 */ 161 String getWorkDir(); 162 163 /** 164 * Returns the current template directory. 165 * 166 * @since 1.9.20 167 * @return The template directory as initialized by the engine. 168 */ 169 String getTemplateDir(); 170 171 /** 172 * Returns plugins' search path. 173 * 174 * @return plugins' search path. 175 */ 176 default String getPluginSearchPath() { 177 return TextUtil.getStringProperty( getWikiProperties(), PROP_SEARCHPATH, null ); 178 } 179 180 /** 181 * Returns the moment when this engine was started. 182 * 183 * @since 2.0.15. 184 * @return The start time of this wiki. 185 */ 186 Date getStartTime(); 187 188 /** 189 * Returns the base URL, telling where this Wiki actually lives. 190 * 191 * @since 1.6.1 192 * @return The Base URL. 193 */ 194 String getBaseURL(); 195 196 /** 197 * Returns the URL of the global RSS file. May be null, if the RSS file generation is not operational. 198 * 199 * @since 1.7.10 200 * @return The global RSS url 201 */ 202 String getGlobalRSSURL(); 203 204 /** 205 * Returns an URL to some other Wiki that we know. 206 * 207 * @param wikiName The name of the other wiki. 208 * @return null, if no such reference was found. 209 */ 210 String getInterWikiURL( String wikiName ); 211 212 /** 213 * Returns an URL if a WikiContext is not available. 214 * 215 * @param context The WikiContext (VIEW, EDIT, etc...) 216 * @param pageName Name of the page, as usual 217 * @param params List of parameters. May be null, if no parameters. 218 * @return An URL (absolute or relative). 219 */ 220 String getURL( String context, String pageName, String params ); 221 222 /** 223 * Returns the default front page, if no page is used. 224 * 225 * @return The front page name. 226 */ 227 String getFrontPage(); 228 229 /** 230 * Returns the ServletContext that this particular Engine was initialized with. <strong>It may return {@code null}</strong>, 231 * if the Engine is not running inside a servlet container! 232 * 233 * @since 1.7.10 234 * @return ServletContext of the Engine, or {@code null}. 235 */ 236 ServletContext getServletContext(); 237 238 /** 239 * Looks up and obtains a configuration file inside the WEB-INF folder of a wiki webapp. 240 * 241 * @param name the file to obtain, <em>e.g.</em>, <code>jspwiki.policy</code> 242 * @return the URL to the file 243 */ 244 default URL findConfigFile( final String name ) { 245 LogManager.getLogger( Engine.class ).info( "looking for " + name + " inside WEB-INF " ); 246 // Try creating an absolute path first 247 File defaultFile = null; 248 if( getRootPath() != null ) { 249 defaultFile = new File( getRootPath() + "/WEB-INF/" + name ); 250 } 251 if ( defaultFile != null && defaultFile.exists() ) { 252 try { 253 return defaultFile.toURI().toURL(); 254 } catch ( final MalformedURLException e ) { 255 // Shouldn't happen, but log it if it does 256 LogManager.getLogger( Engine.class ).warn( "Malformed URL: " + e.getMessage() ); 257 } 258 } 259 260 // Ok, the absolute path didn't work; try other methods 261 URL path = null; 262 263 if( getServletContext() != null ) { 264 final File tmpFile; 265 try { 266 tmpFile = File.createTempFile( "temp." + name, "" ); 267 } catch( final IOException e ) { 268 LogManager.getLogger( Engine.class ).error( "unable to create a temp file to load onto the policy", e ); 269 return null; 270 } 271 tmpFile.deleteOnExit(); 272 LogManager.getLogger( Engine.class ).info( "looking for /" + name + " on classpath" ); 273 // create a tmp file of the policy loaded as an InputStream and return the URL to it 274 try( final InputStream is = Engine.class.getResourceAsStream( "/" + name ); 275 final OutputStream os = Files.newOutputStream( tmpFile.toPath() ) ) { 276 if( is == null ) { 277 throw new FileNotFoundException( name + " not found" ); 278 } 279 final URL url = getServletContext().getResource( "/WEB-INF/" + name ); 280 if( url != null ) { 281 return url; 282 } 283 284 final byte[] buff = new byte[1024]; 285 int bytes; 286 while( ( bytes = is.read( buff ) ) != -1 ) { 287 os.write( buff, 0, bytes ); 288 } 289 290 path = tmpFile.toURI().toURL(); 291 } catch( final MalformedURLException e ) { 292 // This should never happen unless I screw up 293 LogManager.getLogger( Engine.class ).fatal( "Your code is b0rked. You are a bad person.", e ); 294 } catch( final IOException e ) { 295 LogManager.getLogger( Engine.class ).error( "failed to load security policy from file " + name + ",stacktrace follows", e ); 296 } 297 } 298 return path; 299 } 300 301 /** 302 * Returns a collection of all supported InterWiki links. 303 * 304 * @return A Collection of Strings. 305 */ 306 Collection< String > getAllInterWikiLinks(); 307 308 /** 309 * Returns a collection of all image types that get inlined. 310 * 311 * @return A Collection of Strings with a regexp pattern. 312 */ 313 Collection< String > getAllInlinedImagePatterns(); 314 315 /** 316 * <p>If the page is a special page, then returns a direct URL to that page. Otherwise returns <code>null</code>. 317 * This method delegates requests to {@link org.apache.wiki.ui.CommandResolver#getSpecialPageReference(String)}.</p> 318 * <p>Special pages are defined in jspwiki.properties using the jspwiki.specialPage setting. They're typically used to give Wiki page 319 * names to e.g. custom JSP pages.</p> 320 * 321 * @param original The page to check 322 * @return A reference to the page, or null, if there's no special page. 323 */ 324 String getSpecialPageReference( String original ); 325 326 /** 327 * Returns the name of the application. 328 * 329 * @return A string describing the name of this application. 330 */ 331 String getApplicationName(); 332 333 /** 334 * Returns the root path. The root path is where the Engine is located in the file system. 335 * 336 * @since 2.2 337 * @return A path to where the Wiki is installed in the local filesystem. 338 */ 339 String getRootPath(); 340 341 /** 342 * Returns the correct page name, or null, if no such page can be found. Aliases are considered. This method simply delegates to 343 * {@link org.apache.wiki.ui.CommandResolver#getFinalPageName(String)}. 344 * 345 * @since 2.0 346 * @param page Page name. 347 * @return The rewritten page name, or null, if the page does not exist. 348 * @throws ProviderException If something goes wrong in the backend. 349 */ 350 String getFinalPageName( String page ) throws ProviderException; 351 352 /** 353 * Turns a WikiName into something that can be called through using an URL. 354 * 355 * @since 1.4.1 356 * @param pagename A name. Can be actually any string. 357 * @return A properly encoded name. 358 * @see #decodeName(String) 359 */ 360 String encodeName( String pagename ); 361 362 /** 363 * Decodes a URL-encoded request back to regular life. This properly heeds the encoding as defined in the settings file. 364 * 365 * @param pagerequest The URL-encoded string to decode 366 * @return A decoded string. 367 * @see #encodeName(String) 368 */ 369 String decodeName( String pagerequest ); 370 371 /** 372 * Returns the IANA name of the character set encoding we're supposed to be using right now. 373 * 374 * @since 1.5.3 375 * @return The content encoding (either UTF-8 or ISO-8859-1). 376 */ 377 Charset getContentEncoding(); 378 379 /** 380 * Registers a WikiEventListener with this instance. 381 * 382 * @param listener the event listener 383 */ 384 void addWikiEventListener( WikiEventListener listener ); 385 386 /** 387 * Un-registers a WikiEventListener with this instance. 388 * 389 * @param listener the event listener 390 */ 391 void removeWikiEventListener( WikiEventListener listener ); 392 393 /** 394 * Adds an attribute to the engine for the duration of this engine. The value is not persisted. 395 * 396 * @since 2.4.91 397 * @param key the attribute name 398 * @param value the value 399 */ 400 void setAttribute( String key, Object value ); 401 402 /** 403 * Gets an attribute from the engine. 404 * 405 * @param key the attribute name 406 * @return the value 407 */ 408 < T > T getAttribute( String key ); 409 410 /** 411 * Removes an attribute. 412 * 413 * @param key The key of the attribute to remove. 414 * @return The previous attribute, if it existed. 415 */ 416 < T > T removeAttribute( String key ); 417 418 /** 419 * Initializes the {@code Engine}, notifying all the {@link EngineLifecycleExtension}s. 420 * 421 * @param properties Wiki configuration properties. 422 * @throws WikiException if something happens while setting up the {@code Engine}. 423 */ 424 default void start( final Properties properties ) throws WikiException { 425 final ServiceLoader< EngineLifecycleExtension > loader = ServiceLoader.load( EngineLifecycleExtension.class ); 426 for( final EngineLifecycleExtension extension : loader ) { 427 extension.onInit( properties ); 428 } 429 initialize( properties ); 430 for( final EngineLifecycleExtension extension : loader ) { 431 extension.onStart( this, properties ); 432 } 433 } 434 435 /** 436 * Shuts down the {@code Engine}, notifying all the {@link EngineLifecycleExtension}s. 437 */ 438 default void stop() { 439 final ServiceLoader< EngineLifecycleExtension > loader = ServiceLoader.load( EngineLifecycleExtension.class ); 440 for( final EngineLifecycleExtension extension : loader ) { 441 extension.onShutdown( this, getWikiProperties() ); 442 } 443 shutdown(); 444 } 445 446 /** 447 * Sets up the application's running {@code Engine}. 448 * 449 * @param properties Wiki configuration properties. 450 * @throws WikiException if something happens while setting up the {@code Engine}. 451 */ 452 void initialize( Properties properties ) throws WikiException; 453 454 /** 455 * Signals that the {@code Engine} will be shut down by the servlet container. 456 */ 457 void shutdown(); 458 459}