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 /** The name of the property containing the ReferenceManager implementing class. The value is {@value}. */ 108 String PROP_REF_MANAGER_IMPL = "jspwiki.refManager"; 109 110 /** If this property is set to false, we don't allow the creation of empty pages */ 111 String PROP_ALLOW_CREATION_OF_EMPTY_PAGES = "jspwiki.allowCreationOfEmptyPages"; 112 113 /** 114 * Adapt Engine to a concrete type. 115 * 116 * @param cls class denoting the type to adapt to. 117 * @param <E> type to adapt to. 118 * @return engine instance adapted to the requested type. Might throw an unchecked exception if the instance cannot be adapted to requested type! 119 */ 120 @SuppressWarnings( "unchecked" ) 121 default < E extends Engine > E adapt( final Class< E > cls ) { 122 return ( E )this; 123 } 124 125 /** 126 * Retrieves the object instantiated by the Engine matching the requested type. 127 * 128 * @param manager requested object instantiated by the Engine. 129 * @param <T> type of the requested object. 130 * @return requested object instantiated by the Engine, {@code null} if not available. 131 */ 132 < T > T getManager( Class< T > manager ); 133 134 /** 135 * Retrieves the objects instantiated by the Engine that can be assigned to the requested type. 136 * 137 * @param manager requested objectx instantiated by the Engine. 138 * @param <T> type of the requested object. 139 * @return collection of requested objects instantiated by the Engine, {@code empty} list if none available. 140 */ 141 < T > List< T > getManagers( Class< T > manager ); 142 143 /** 144 * check if the Engine has been configured. 145 * 146 * @return {@code true} if it has, {@code false} otherwise. 147 */ 148 boolean isConfigured(); 149 150 /** 151 * Returns the set of properties that the Engine was initialized with. Note that this method returns a direct reference, so it's 152 * possible to manipulate the properties. However, this is not advised unless you really know what you're doing. 153 * 154 * @return The wiki properties 155 */ 156 Properties getWikiProperties(); 157 158 /** 159 * Returns the JSPWiki working directory set with "jspwiki.workDir". 160 * 161 * @since 2.1.100 162 * @return The working directory. 163 */ 164 String getWorkDir(); 165 166 /** 167 * Returns the current template directory. 168 * 169 * @since 1.9.20 170 * @return The template directory as initialized by the engine. 171 */ 172 String getTemplateDir(); 173 174 /** 175 * Returns plugins' search path. 176 * 177 * @return plugins' search path. 178 */ 179 default String getPluginSearchPath() { 180 return TextUtil.getStringProperty( getWikiProperties(), PROP_SEARCHPATH, null ); 181 } 182 183 /** 184 * Returns the moment when this engine was started. 185 * 186 * @since 2.0.15. 187 * @return The start time of this wiki. 188 */ 189 Date getStartTime(); 190 191 /** 192 * Returns the base URL, telling where this Wiki actually lives. 193 * 194 * @since 1.6.1 195 * @return The Base URL. 196 */ 197 String getBaseURL(); 198 199 /** 200 * Returns the URL of the global RSS file. May be null, if the RSS file generation is not operational. 201 * 202 * @since 1.7.10 203 * @return The global RSS url 204 */ 205 String getGlobalRSSURL(); 206 207 /** 208 * Returns an URL to some other Wiki that we know. 209 * 210 * @param wikiName The name of the other wiki. 211 * @return null, if no such reference was found. 212 */ 213 String getInterWikiURL( String wikiName ); 214 215 /** 216 * Returns an URL if a WikiContext is not available. 217 * 218 * @param context The WikiContext (VIEW, EDIT, etc...) 219 * @param pageName Name of the page, as usual 220 * @param params List of parameters. May be null, if no parameters. 221 * @return An URL (absolute or relative). 222 */ 223 String getURL( String context, String pageName, String params ); 224 225 /** 226 * Returns the default front page, if no page is used. 227 * 228 * @return The front page name. 229 */ 230 String getFrontPage(); 231 232 /** 233 * Returns the ServletContext that this particular Engine was initialized with. <strong>It may return {@code null}</strong>, 234 * if the Engine is not running inside a servlet container! 235 * 236 * @since 1.7.10 237 * @return ServletContext of the Engine, or {@code null}. 238 */ 239 ServletContext getServletContext(); 240 241 /** 242 * Looks up and obtains a configuration file inside the WEB-INF folder of a wiki webapp. 243 * 244 * @param name the file to obtain, <em>e.g.</em>, <code>jspwiki.policy</code> 245 * @return the URL to the file 246 */ 247 default URL findConfigFile( final String name ) { 248 LogManager.getLogger( Engine.class ).info( "looking for " + name + " inside WEB-INF " ); 249 // Try creating an absolute path first 250 File defaultFile = null; 251 if( getRootPath() != null ) { 252 defaultFile = new File( getRootPath() + "/WEB-INF/" + name ); 253 } 254 if ( defaultFile != null && defaultFile.exists() ) { 255 try { 256 return defaultFile.toURI().toURL(); 257 } catch ( final MalformedURLException e ) { 258 // Shouldn't happen, but log it if it does 259 LogManager.getLogger( Engine.class ).warn( "Malformed URL: " + e.getMessage() ); 260 } 261 } 262 263 // Ok, the absolute path didn't work; try other methods 264 URL path = null; 265 266 if( getServletContext() != null ) { 267 final File tmpFile; 268 try { 269 tmpFile = File.createTempFile( "temp." + name, "" ); 270 } catch( final IOException e ) { 271 LogManager.getLogger( Engine.class ).error( "unable to create a temp file to load onto the policy", e ); 272 return null; 273 } 274 tmpFile.deleteOnExit(); 275 LogManager.getLogger( Engine.class ).info( "looking for /" + name + " on classpath" ); 276 // create a tmp file of the policy loaded as an InputStream and return the URL to it 277 try( final InputStream is = Engine.class.getResourceAsStream( "/" + name ); 278 final OutputStream os = Files.newOutputStream( tmpFile.toPath() ) ) { 279 if( is == null ) { 280 throw new FileNotFoundException( name + " not found" ); 281 } 282 final URL url = getServletContext().getResource( "/WEB-INF/" + name ); 283 if( url != null ) { 284 return url; 285 } 286 287 final byte[] buff = new byte[1024]; 288 int bytes; 289 while( ( bytes = is.read( buff ) ) != -1 ) { 290 os.write( buff, 0, bytes ); 291 } 292 293 path = tmpFile.toURI().toURL(); 294 } catch( final MalformedURLException e ) { 295 // This should never happen unless I screw up 296 LogManager.getLogger( Engine.class ).fatal( "Your code is b0rked. You are a bad person.", e ); 297 } catch( final IOException e ) { 298 LogManager.getLogger( Engine.class ).error( "failed to load security policy from file " + name + ",stacktrace follows", e ); 299 } 300 } 301 return path; 302 } 303 304 /** 305 * Returns a collection of all supported InterWiki links. 306 * 307 * @return A Collection of Strings. 308 */ 309 Collection< String > getAllInterWikiLinks(); 310 311 /** 312 * Returns a collection of all image types that get inlined. 313 * 314 * @return A Collection of Strings with a regexp pattern. 315 */ 316 Collection< String > getAllInlinedImagePatterns(); 317 318 /** 319 * <p>If the page is a special page, then returns a direct URL to that page. Otherwise returns <code>null</code>. 320 * This method delegates requests to {@link org.apache.wiki.ui.CommandResolver#getSpecialPageReference(String)}.</p> 321 * <p>Special pages are defined in jspwiki.properties using the jspwiki.specialPage setting. They're typically used to give Wiki page 322 * names to e.g. custom JSP pages.</p> 323 * 324 * @param original The page to check 325 * @return A reference to the page, or null, if there's no special page. 326 */ 327 String getSpecialPageReference( String original ); 328 329 /** 330 * Returns the name of the application. 331 * 332 * @return A string describing the name of this application. 333 */ 334 String getApplicationName(); 335 336 /** 337 * Returns the root path. The root path is where the Engine is located in the file system. 338 * 339 * @since 2.2 340 * @return A path to where the Wiki is installed in the local filesystem. 341 */ 342 String getRootPath(); 343 344 /** 345 * Returns the correct page name, or null, if no such page can be found. Aliases are considered. This method simply delegates to 346 * {@link org.apache.wiki.ui.CommandResolver#getFinalPageName(String)}. 347 * 348 * @since 2.0 349 * @param page Page name. 350 * @return The rewritten page name, or null, if the page does not exist. 351 * @throws ProviderException If something goes wrong in the backend. 352 */ 353 String getFinalPageName( String page ) throws ProviderException; 354 355 /** 356 * Turns a WikiName into something that can be called through using an URL. 357 * 358 * @since 1.4.1 359 * @param pagename A name. Can be actually any string. 360 * @return A properly encoded name. 361 * @see #decodeName(String) 362 */ 363 String encodeName( String pagename ); 364 365 /** 366 * Decodes a URL-encoded request back to regular life. This properly heeds the encoding as defined in the settings file. 367 * 368 * @param pagerequest The URL-encoded string to decode 369 * @return A decoded string. 370 * @see #encodeName(String) 371 */ 372 String decodeName( String pagerequest ); 373 374 /** 375 * Returns the IANA name of the character set encoding we're supposed to be using right now. 376 * 377 * @since 1.5.3 378 * @return The content encoding (either UTF-8 or ISO-8859-1). 379 */ 380 Charset getContentEncoding(); 381 382 /** 383 * Registers a WikiEventListener with this instance. 384 * 385 * @param listener the event listener 386 */ 387 void addWikiEventListener( WikiEventListener listener ); 388 389 /** 390 * Un-registers a WikiEventListener with this instance. 391 * 392 * @param listener the event listener 393 */ 394 void removeWikiEventListener( WikiEventListener listener ); 395 396 /** 397 * Adds an attribute to the engine for the duration of this engine. The value is not persisted. 398 * 399 * @since 2.4.91 400 * @param key the attribute name 401 * @param value the value 402 */ 403 void setAttribute( String key, Object value ); 404 405 /** 406 * Gets an attribute from the engine. 407 * 408 * @param key the attribute name 409 * @return the value 410 */ 411 < T > T getAttribute( String key ); 412 413 /** 414 * Removes an attribute. 415 * 416 * @param key The key of the attribute to remove. 417 * @return The previous attribute, if it existed. 418 */ 419 < T > T removeAttribute( String key ); 420 421 /** 422 * Initializes the {@code Engine}, notifying all the {@link EngineLifecycleExtension}s. 423 * 424 * @param properties Wiki configuration properties. 425 * @throws WikiException if something happens while setting up the {@code Engine}. 426 */ 427 default void start( final Properties properties ) throws WikiException { 428 final ServiceLoader< EngineLifecycleExtension > loader = ServiceLoader.load( EngineLifecycleExtension.class ); 429 for( final EngineLifecycleExtension extension : loader ) { 430 extension.onInit( properties ); 431 } 432 initialize( properties ); 433 for( final EngineLifecycleExtension extension : loader ) { 434 extension.onStart( this, properties ); 435 } 436 } 437 438 /** 439 * Shuts down the {@code Engine}, notifying all the {@link EngineLifecycleExtension}s. 440 */ 441 default void stop() { 442 final ServiceLoader< EngineLifecycleExtension > loader = ServiceLoader.load( EngineLifecycleExtension.class ); 443 for( final EngineLifecycleExtension extension : loader ) { 444 extension.onShutdown( this, getWikiProperties() ); 445 } 446 shutdown(); 447 } 448 449 /** 450 * Sets up the application's running {@code Engine}. 451 * 452 * @param properties Wiki configuration properties. 453 * @throws WikiException if something happens while setting up the {@code Engine}. 454 */ 455 void initialize( Properties properties ) throws WikiException; 456 457 /** 458 * Signals that the {@code Engine} will be shut down by the servlet container. 459 */ 460 void shutdown(); 461 462}