Package org.apache.wiki.api.core

# Interface Engine

public interface Engine
Provides Wiki services to the JSP page.

This is the main interface through which everything should go.

There's basically only a single Engine for each web application, and you should always get it using either the `Context#getEngine()` method or through `Wiki.engine().find(..)` DSL methods.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`DEFAULT_INLINEPATTERN`
The default inlining pattern.
`static final String`
`DEFAULT_TEMPLATE_NAME`
The name used for the default template.
`static final String`
`PREFS_COOKIE_NAME`
The name of the cookie that gets stored to the user browser.
`static final String`
`PROP_ACL_MANAGER_IMPL`
The name of the property containing the ACLManager implementing class.
`static final String`
`PROP_ALLOW_CREATION_OF_EMPTY_PAGES`
If this property is set to false, we don't allow the creation of empty pages
`static final String`
`PROP_APPNAME`
Property for application name
`static final String`
`PROP_ENCODING`
Define the used encoding.
`static final String`
`PROP_FRONTPAGE`
Property name for the default front page.
`static final String`
`PROP_INLINEIMAGEPTRN`
This property defines the inline image pattern.
`static final String`
`PROP_INTERWIKIREF`
Property start for any interwiki reference.
`static final String`
`PROP_MATCHPLURALS`
Property name for the "match english plurals" -hack.
`static final String`
`PROP_NO_FILTER_ENCODING`
Do not use encoding in WikiJSPFilter, default is false for most servers.
`static final String`
`PROP_REF_MANAGER_IMPL`
The name of the property containing the ReferenceManager implementing class.
`static final String`
`PROP_SEARCHPATH`
The property name defining which packages will be searched for plugin classes.
`static final String`
`PROP_STOREUSERNAME`
If true, then the user name will be stored with the page data.
`static final String`
`PROP_TEMPLATEDIR`
Property name for the template that is used.
`static final String`
`PROP_URLCONSTRUCTOR`
Property name for setting the url generator instance
`static final String`
`PROP_USE_2_X_ACL_LOGIC`
see JSPWIKI-130
`static final String`
`PROP_WORKDIR`
Property name for where the jspwiki work directory should be.

## Method Summary

Modifier and Type
Method
Description
`default <E extends Engine>
E`
`adapt(Class<E> cls)`
Adapt Engine to a concrete type.
`void`
`addWikiEventListener(org.apache.wiki.event.WikiEventListener listener)`
Registers a WikiEventListener with this instance.
`String`
`decodeName(String pagerequest)`
Decodes a URL-encoded request back to regular life.
`String`
`encodeName(String pagename)`
Turns a WikiName into something that can be called through using an URL.
`default URL`
`findConfigFile(String name)`
Looks up and obtains a configuration file inside the WEB-INF folder of a wiki webapp.
`Collection<String>`
`getAllInlinedImagePatterns()`
Returns a collection of all image types that get inlined.
`Collection<String>`
`getAllInterWikiLinks()`
Returns a collection of all supported InterWiki links.
`String`
`getApplicationName()`
Returns the name of the application.
`<T> T`
`getAttribute(String key)`
Gets an attribute from the engine.
`String`
`getBaseURL()`
Returns the base URL, telling where this Wiki actually lives.
`Charset`
`getContentEncoding()`
Returns the IANA name of the character set encoding we're supposed to be using right now.
`String`
`getFinalPageName(String page)`
Returns the correct page name, or null, if no such page can be found.
`String`
`getFrontPage()`
Returns the default front page, if no page is used.
`String`
`getGlobalRSSURL()`
Returns the URL of the global RSS file.
`String`
`getInterWikiURL(String wikiName)`
Returns an URL to some other Wiki that we know.
`<T> T`
`getManager(Class<T> manager)`
Retrieves the object instantiated by the Engine matching the requested type.
`<T> List<T>`
`getManagers(Class<T> manager)`
Retrieves the objects instantiated by the Engine that can be assigned to the requested type.
`default String`
`getPluginSearchPath()`
Returns plugins' search path.
`String`
`getRootPath()`
Returns the root path.
`jakarta.servlet.ServletContext`
`getServletContext()`
Returns the ServletContext that this particular Engine was initialized with.
`String`
`getSpecialPageReference(String original)`
If the page is a special page, then returns a direct URL to that page.
`Date`
`getStartTime()`
Returns the moment when this engine was started.
`String`
`getTemplateDir()`
Returns the current template directory.
`String`
`getURL(String context, String pageName, String params)`
Returns an URL if a WikiContext is not available.
`Properties`
`getWikiProperties()`
Returns the set of properties that the Engine was initialized with.
`String`
`getWorkDir()`
Returns the JSPWiki working directory set with "jspwiki.workDir".
`void`
`initialize(Properties properties)`
Sets up the application's running `Engine`.
`boolean`
`isConfigured()`
check if the Engine has been configured.
`<T> T`
`removeAttribute(String key)`
Removes an attribute.
`void`
`removeWikiEventListener(org.apache.wiki.event.WikiEventListener listener)`
Un-registers a WikiEventListener with this instance.
`void`
`setAttribute(String key, Object value)`
Adds an attribute to the engine for the duration of this engine.
`void`
`shutdown()`
Signals that the `Engine` will be shut down by the servlet container.
`default void`
`start(Properties properties)`
Initializes the `Engine`, notifying all the `EngineLifecycleExtension`s.
`default void`
`stop()`
Shuts down the `Engine`, notifying all the `EngineLifecycleExtension`s.

## Field Details

### PROP_USE_2_X_ACL_LOGIC

static final String PROP_USE_2_X_ACL_LOGIC
see JSPWIKI-130

Since:
  3.0.0
See Also:
  - Constant Field Values

### DEFAULT_INLINEPATTERN

static final String DEFAULT_INLINEPATTERN
The default inlining pattern. Currently "*.png"

See Also:
  - Constant Field Values

### DEFAULT_TEMPLATE_NAME

static final String DEFAULT_TEMPLATE_NAME
The name used for the default template. The value is "default".

See Also:
  - Constant Field Values

### PROP_APPNAME

static final String PROP_APPNAME
Property for application name

See Also:
  - Constant Field Values

### PROP_INLINEIMAGEPTRN

static final String PROP_INLINEIMAGEPTRN
This property defines the inline image pattern. It's current value is "jspwiki.translatorReader.inlinePattern"

See Also:
  - Constant Field Values

### PROP_INTERWIKIREF

static final String PROP_INTERWIKIREF
Property start for any interwiki reference.

See Also:
  - Constant Field Values

### PROP_SEARCHPATH

static final String PROP_SEARCHPATH
The property name defining which packages will be searched for plugin classes.

See Also:
  - Constant Field Values

### PROP_STOREUSERNAME

static final String PROP_STOREUSERNAME
If true, then the user name will be stored with the page data.

See Also:
  - Constant Field Values

### PROP_ENCODING

static final String PROP_ENCODING
Define the used encoding. Currently supported are ISO-8859-1 and UTF-8

See Also:
  - Constant Field Values

### PROP_NO_FILTER_ENCODING

static final String PROP_NO_FILTER_ENCODING
Do not use encoding in WikiJSPFilter, default is false for most servers. Double negative, cause for most servers you don't need the property

See Also:
  - Constant Field Values

### PROP_WORKDIR

static final String PROP_WORKDIR
Property name for where the jspwiki work directory should be. If not specified, reverts to ${java.tmpdir}.

See Also:
  - Constant Field Values

### PREFS_COOKIE_NAME

static final String PREFS_COOKIE_NAME
The name of the cookie that gets stored to the user browser.

See Also:
  - Constant Field Values

### PROP_MATCHPLURALS

static final String PROP_MATCHPLURALS
Property name for the "match english plurals" -hack.

See Also:
  - Constant Field Values

### PROP_TEMPLATEDIR

static final String PROP_TEMPLATEDIR
Property name for the template that is used.

See Also:
  - Constant Field Values

### PROP_FRONTPAGE

static final String PROP_FRONTPAGE
Property name for the default front page.

See Also:
  - Constant Field Values

### PROP_URLCONSTRUCTOR

static final String PROP_URLCONSTRUCTOR
Property name for setting the url generator instance

See Also:
  - Constant Field Values

### PROP_ACL_MANAGER_IMPL

static final String PROP_ACL_MANAGER_IMPL
The name of the property containing the ACLManager implementing class. The value is "jspwiki.aclManager".

See Also:
  - Constant Field Values

### PROP_REF_MANAGER_IMPL

static final String PROP_REF_MANAGER_IMPL
The name of the property containing the ReferenceManager implementing class. The value is "jspwiki.refManager".

See Also:
  - Constant Field Values

### PROP_ALLOW_CREATION_OF_EMPTY_PAGES

static final String PROP_ALLOW_CREATION_OF_EMPTY_PAGES
If this property is set to false, we don't allow the creation of empty pages

See Also:
  - Constant Field Values

## Method Details

### adapt

default <E extends Engine> E adapt(Class<E> cls)
Adapt Engine to a concrete type.

Type Parameters:
  `E` - type to adapt to.
Parameters:
  `cls` - class denoting the type to adapt to.
Returns:
  engine instance adapted to the requested type. Might throw an unchecked exception if the instance cannot be adapted to requested type!

### getManager

<T> T getManager(Class<T> manager)
Retrieves the object instantiated by the Engine matching the requested type.

Type Parameters:
  `T` - type of the requested object.
Parameters:
  `manager` - requested object instantiated by the Engine.
Returns:
  requested object instantiated by the Engine, `null` if not available.

### getManagers

<T> List<T> getManagers(Class<T> manager)
Retrieves the objects instantiated by the Engine that can be assigned to the requested type.

Type Parameters:
  `T` - type of the requested object.
Parameters:
  `manager` - requested objectx instantiated by the Engine.
Returns:
  collection of requested objects instantiated by the Engine, `empty` list if none available.

### isConfigured

boolean isConfigured()
check if the Engine has been configured.

Returns:
  `true` if it has, `false` otherwise.

### getWikiProperties

Properties getWikiProperties()
Returns the set of properties that the Engine was initialized with. Note that this method returns a direct reference, so it's possible to manipulate the properties. However, this is not advised unless you really know what you're doing.

Returns:
  The wiki properties

### getWorkDir

String getWorkDir()
Returns the JSPWiki working directory set with "jspwiki.workDir".

Returns:
  The working directory.
Since:
  2.1.100

### getTemplateDir

String getTemplateDir()
Returns the current template directory.

Returns:
  The template directory as initialized by the engine.
Since:
  1.9.20

### getPluginSearchPath

default String getPluginSearchPath()
Returns plugins' search path.

Returns:
  plugins' search path.

### getStartTime

Date getStartTime()
Returns the moment when this engine was started.

Returns:
  The start time of this wiki.
Since:
  2.0.15.

### getBaseURL

String getBaseURL()
Returns the base URL, telling where this Wiki actually lives.

Returns:
  The Base URL.
Since:
  1.6.1

### getGlobalRSSURL

String getGlobalRSSURL()
Returns the URL of the global RSS file. May be null, if the RSS file generation is not operational.

Returns:
  The global RSS url
Since:
  1.7.10

### getInterWikiURL

String getInterWikiURL(String wikiName)
Returns an URL to some other Wiki that we know.

Parameters:
  `wikiName` - The name of the other wiki.
Returns:
  null, if no such reference was found.

### getURL

String getURL(String context, String pageName, String params)
Returns an URL if a WikiContext is not available.

Parameters:
  `context` - The WikiContext (VIEW, EDIT, etc...)
  `pageName` - Name of the page, as usual
  `params` - List of parameters. May be null, if no parameters.
Returns:
  An URL (absolute or relative).

### getFrontPage

String getFrontPage()
Returns the default front page, if no page is used.

Returns:
  The front page name.

### getServletContext

jakarta.servlet.ServletContext getServletContext()
Returns the ServletContext that this particular Engine was initialized with. It may return `null`, if the Engine is not running inside a servlet container!

Returns:
  ServletContext of the Engine, or `null`.
Since:
  1.7.10

### findConfigFile

default URL findConfigFile(String name)
Looks up and obtains a configuration file inside the WEB-INF folder of a wiki webapp.

Parameters:
  `name` - the file to obtain, e.g., `jspwiki.policy`
Returns:
  the URL to the file

### getAllInterWikiLinks

Collection<String> getAllInterWikiLinks()
Returns a collection of all supported InterWiki links.

Returns:
  A Collection of Strings.

### getAllInlinedImagePatterns

Collection<String> getAllInlinedImagePatterns()
Returns a collection of all image types that get inlined.

Returns:
  A Collection of Strings with a regexp pattern.

### getSpecialPageReference

String getSpecialPageReference(String original)

If the page is a special page, then returns a direct URL to that page. Otherwise returns `null`. This method delegates requests to `org.apache.wiki.ui.CommandResolver#getSpecialPageReference(String)`.

Special pages are defined in jspwiki.properties using the jspwiki.specialPage setting. They're typically used to give Wiki page names to e.g. custom JSP pages.

Parameters:
  `original` - The page to check
Returns:
  A reference to the page, or null, if there's no special page.

### getApplicationName

String getApplicationName()
Returns the name of the application.

Returns:
  A string describing the name of this application.

### getRootPath

String getRootPath()
Returns the root path. The root path is where the Engine is located in the file system.

Returns:
  A path to where the Wiki is installed in the local filesystem.
Since:
  2.2

### getFinalPageName

String getFinalPageName(String page) throws ProviderException
Returns the correct page name, or null, if no such page can be found. Aliases are considered. This method simply delegates to `org.apache.wiki.ui.CommandResolver#getFinalPageName(String)`.

Parameters:
  `page` - Page name.
Returns:
  The rewritten page name, or null, if the page does not exist.
Throws:
  `ProviderException` - If something goes wrong in the backend.
Since:
  2.0

### encodeName

String encodeName(String pagename)
Turns a WikiName into something that can be called through using an URL.

Parameters:
  `pagename` - A name. Can be actually any string.
Returns:
  A properly encoded name.
Since:
  1.4.1
See Also:
  - `decodeName(String)`

### decodeName

String decodeName(String pagerequest)
Decodes a URL-encoded request back to regular life. This properly heeds the encoding as defined in the settings file.

Parameters:
  `pagerequest` - The URL-encoded string to decode
Returns:
  A decoded string.
See Also:
  - `encodeName(String)`

### getContentEncoding

Charset getContentEncoding()
Returns the IANA name of the character set encoding we're supposed to be using right now.

Returns:
  The content encoding (either UTF-8 or ISO-8859-1).
Since:
  1.5.3

### addWikiEventListener

void addWikiEventListener(org.apache.wiki.event.WikiEventListener listener)
Registers a WikiEventListener with this instance.

Parameters:
  `listener` - the event listener

### removeWikiEventListener

void removeWikiEventListener(org.apache.wiki.event.WikiEventListener listener)
Un-registers a WikiEventListener with this instance.

Parameters:
  `listener` - the event listener

### setAttribute

void setAttribute(String key, Object value)
Adds an attribute to the engine for the duration of this engine. The value is not persisted.

Parameters:
  `key` - the attribute name
  `value` - the value
Since:
  2.4.91

### getAttribute

<T> T getAttribute(String key)
Gets an attribute from the engine.

Parameters:
  `key` - the attribute name
Returns:
  the value

### removeAttribute

<T> T removeAttribute(String key)
Removes an attribute.

Parameters:
  `key` - The key of the attribute to remove.
Returns:
  The previous attribute, if it existed.

### start

default void start(Properties properties) throws WikiException
Initializes the `Engine`, notifying all the `EngineLifecycleExtension`s.

Parameters:
  `properties` - Wiki configuration properties.
Throws:
  `WikiException` - if something happens while setting up the `Engine`.

### stop

default void stop()
Shuts down the `Engine`, notifying all the `EngineLifecycleExtension`s.

### initialize

void initialize(Properties properties) throws WikiException
Sets up the application's running `Engine`.

Parameters:
  `properties` - Wiki configuration properties.
Throws:
  `WikiException` - if something happens while setting up the `Engine`.

### shutdown

void shutdown()
Signals that the `Engine` will be shut down by the servlet container.