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

### Method Summary

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

### Field Detail

#### DEFAULT_INLINEPATTERN

    static final java.lang.String DEFAULT_INLINEPATTERN

The default inlining pattern. Currently "*.png"

See Also:
  Constant Field Values

#### DEFAULT_TEMPLATE_NAME

    static final java.lang.String DEFAULT_TEMPLATE_NAME

The name used for the default template. The value is "default".

See Also:
  Constant Field Values

#### PROP_APPNAME

    static final java.lang.String PROP_APPNAME

Property for application name

See Also:
  Constant Field Values

#### PROP_INLINEIMAGEPTRN

    static final java.lang.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 java.lang.String PROP_INTERWIKIREF

Property start for any interwiki reference.

See Also:
  Constant Field Values

#### PROP_SEARCHPATH

    static final java.lang.String PROP_SEARCHPATH

The property name defining which packages will be searched for plugin classes.

See Also:
  Constant Field Values

#### PROP_STOREUSERNAME

    static final java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.String PROP_MATCHPLURALS

Property name for the "match english plurals" -hack.

See Also:
  Constant Field Values

#### PROP_TEMPLATEDIR

    static final java.lang.String PROP_TEMPLATEDIR

Property name for the template that is used.

See Also:
  Constant Field Values

#### PROP_FRONTPAGE

    static final java.lang.String PROP_FRONTPAGE

Property name for the default front page.

See Also:
  Constant Field Values

#### PROP_URLCONSTRUCTOR

    static final java.lang.String PROP_URLCONSTRUCTOR

Property name for setting the url generator instance

See Also:
  Constant Field Values

#### PROP_ACL_MANAGER_IMPL

    static final java.lang.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 java.lang.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 java.lang.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 Detail

#### adapt

    default <E extends Engine> E adapt​(java.lang.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​(java.lang.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> java.util.List<T> getManagers​(java.lang.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

    java.util.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

    java.lang.String getWorkDir()

Returns the JSPWiki working directory set with "jspwiki.workDir".

Returns:
  The working directory.
Since:
  2.1.100

#### getTemplateDir

    java.lang.String getTemplateDir()

Returns the current template directory.

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

#### getPluginSearchPath

    default java.lang.String getPluginSearchPath()

Returns plugins' search path.

Returns:
  plugins' search path.

#### getStartTime

    java.util.Date getStartTime()

Returns the moment when this engine was started.

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

#### getBaseURL

    java.lang.String getBaseURL()

Returns the base URL, telling where this Wiki actually lives.

Returns:
  The Base URL.
Since:
  1.6.1

#### getGlobalRSSURL

    java.lang.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

    java.lang.String getInterWikiURL​(java.lang.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

    java.lang.String getURL​(java.lang.String context,
                            java.lang.String pageName,
                            java.lang.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

    java.lang.String getFrontPage()

Returns the default front page, if no page is used.

Returns:
  The front page name.

#### getServletContext

    javax.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 java.net.URL findConfigFile​(java.lang.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

    java.util.Collection<java.lang.String> getAllInterWikiLinks()

Returns a collection of all supported InterWiki links.

Returns:
  A Collection of Strings.

#### getAllInlinedImagePatterns

    java.util.Collection<java.lang.String> getAllInlinedImagePatterns()

Returns a collection of all image types that get inlined.

Returns:
  A Collection of Strings with a regexp pattern.

#### getSpecialPageReference

    java.lang.String getSpecialPageReference​(java.lang.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

    java.lang.String getApplicationName()

Returns the name of the application.

Returns:
  A string describing the name of this application.

#### getRootPath

    java.lang.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

    java.lang.String getFinalPageName​(java.lang.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

    java.lang.String encodeName​(java.lang.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

    java.lang.String decodeName​(java.lang.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

    java.nio.charset.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​(WikiEventListener listener)

Registers a WikiEventListener with this instance.

Parameters:
  `listener` - the event listener

#### removeWikiEventListener

    void removeWikiEventListener​(WikiEventListener listener)

Un-registers a WikiEventListener with this instance.

Parameters:
  `listener` - the event listener

#### setAttribute

    void setAttribute​(java.lang.String key,
                      java.lang.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​(java.lang.String key)

Gets an attribute from the engine.

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

#### removeAttribute

    <T> T removeAttribute​(java.lang.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​(java.util.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​(java.util.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.