This page (revision-22) was last changed on 02-Dec-2023 15:46 by Juan Pablo 

This page was created on 29-Mar-2020 17:46 by Juan Pablo

Only authorized users are allowed to rename pages.

Only authorized users are allowed to delete pages.

Version Date Modified Size Author Changes ... Change note
22 02-Dec-2023 15:46 13 KB Juan Pablo to previous added Event Listeners section
21 23-Jun-2022 07:08 13 KB Murray Altheim to previous | to last fixed spelling errors
Incoming links Outgoing links
JSPWikiPublicAPI
JSPWikiPublicAPI

Difference between version and

At line 1 changed one line
[{TableOfContents title='JSPWiki Public API}]
[{TableOfContents title='JSPWiki Public API'}]
At line 12 changed one line
It's compromised of the classes and interfaces in the {{org.apache.wiki.api.core}}, {{org.apache.wiki.api.engine}}, {{org.apache.wiki.api.exceptions}} and {{org.apache.wiki.api.spi}} packages, plus the {{org.apache.wiki.api.Release}} class. It models the core abstractions of JSPWiki:
It's composed of the classes and interfaces in the {{org.apache.wiki.api.core}}, {{org.apache.wiki.api.engine}}, {{org.apache.wiki.api.exceptions}} and {{org.apache.wiki.api.spi}} packages, plus the {{org.apache.wiki.api.Release}} class. It models the core abstractions of JSPWiki:
At line 17 changed 3 lines
* {{Context}}, which models the ''current'' action happening in a given moment.
** an action in JSPWiki is modeled with a {{Command}}, and that's why {{Context}} extends {{Command}}
** as the {{Context}} is modelling the ''current'' action, you can access from here the associated HTTP request, {{Session}}, {{Page}}, variables that you set on this scope, the associated user, etc.
* {{Context}}, which models the ''current'' action (view, edit, attach, etc.) happening in a given moment.
** an action in JSPWiki is modeled with a {{Command}}, and that's why {{Context}} extends {{Command}}.
** as the {{Context}} is modelling the ''current'' action, you can access from here the associated HTTP request, {{Session}} and {{Page}}, variables that you set on this scope, the associated user, etc.
At line 22 changed 2 lines
* {{Engine}}, which is responsible of keeping the wiki running. As opposed to {{Context}}, the {{Engine}} focuses more on the "static" side of the application: configuration properties, urls (global, rss, etc.}}, the associated {{ServletContext}}, etc.
** Perhaps the most important method here is {{getManager(Class<?> cls )}} which returns the requested "manager" (or ''engine part'' following the engine metaphor). These managers are __not__ part of the public API, so if a given extension relies on them it may stop working on a [new minor release|VersioningProposal].
* {{Engine}}, which is responsible of keeping the wiki running. As opposed to {{Context}}, the {{Engine}} focuses more on the "static" side of the application: configuration properties, urls (global, rss, etc.), the associated {{ServletContext}}, etc.
** Perhaps the most important method here is {{getManager(Class<?> cls )}} which returns the requested "manager" (or ''engine part'', following the engine metaphor). Most of these managers are __not__ part of the public API, so if a given extension relies on them it may stop working on a [new minor release|VersioningProposal].
At line 37 changed one line
note that these default implementations should __never__ be instantiated/accessed directly or, generally speaking, appear in your code. The concrete implementation of the public API used by JSPWiki is selected through an SPI, so it is not impossible that a JSPWiki installation may end up running with a different implementation.
note that these default implementations should __never__ be instantiated/accessed directly or, generally speaking, appear in an extension code. The concrete implementation of the public API used by JSPWiki is selected through an {{[SPI|https://www.baeldung.com/java-spi]}}, so it is not impossible that a JSPWiki installation may be running with a different implementation.
At line 47 changed one line
It is easy to provide custom implementations for the core API:
As noted before, the concrete implementation of the public API used by JSPWiki is selected through an {{[SPI|https://www.baeldung.com/java-spi]}}, so it is easy to provide custom implementations for the core API:
At line 50 changed 4 lines
* For a custom {{Context}}, provide an implementation of {{o.a.w.api.spi.ContextSPI}}, and set the {{jspwiki.provider.impl.context}} property on the {{jspwiki-[[custom].properties}} file with the fully qualified name of the implementation.
* For a custom {{Session}}, provide an implementation of {{o.a.w.api.spi.SessionSPI}}, and set the {{jspwiki.provider.impl.session}} property on the {{jspwiki-[[custom].properties}} file with the fully qualified name of the implementation.
* For custom {{Page}} or {{Attachment}}, provide an implementation of {{o.a.w.api.spi.ContentsSPI}}, and set the {{jspwiki.provider.impl.contents}} property on the {{jspwiki-[[custom].properties}} file with the fully qualified name of the implementation.
* For custom {{Acl}} or {{AclEntry}}, provide an implementation of {{o.a.w.api.spi.AclsSPI}}, and set the {{jspwiki.provider.impl.acls}} property on the {{jspwiki-[[custom].properties}} file with the fully qualified name of the implementation.
* For a custom {{Context}}, provide an implementation of {{o.a.w.api.spi.ContextSPI}}, and set the {{jspwiki.provider.impl.context}} property on the {{jspwiki-[[custom].properties}} file with the fully qualified class name of the implementation.
* For a custom {{Session}}, provide an implementation of {{o.a.w.api.spi.SessionSPI}}, and set the {{jspwiki.provider.impl.session}} property on the {{jspwiki-[[custom].properties}} file with the fully qualified class name of the implementation.
* For custom {{Page}} or {{Attachment}}, provide an implementation of {{o.a.w.api.spi.ContentsSPI}}, and set the {{jspwiki.provider.impl.contents}} property on the {{jspwiki-[[custom].properties}} file with the fully qualified class name of the implementation.
* For custom {{Acl}} or {{AclEntry}}, provide an implementation of {{o.a.w.api.spi.AclsSPI}}, and set the {{jspwiki.provider.impl.acls}} property on the {{jspwiki-[[custom].properties}} file with the fully qualified class name of the implementation.
At line 55 added 4 lines
%%bg-info
%%label-info info%%
note that for these {{[SPI|https://www.baeldung.com/java-spi]}}s to work, each of these implementations must be accompanied by its corresponding {{META-INF/services/$IMPLEMENTED_INTERFACE}} file whose content must also be the fully qualified class name of the implementation.
%%
At line 58 changed one line
It is possible to register custom "Engine parts" (managers or components or however they are end up being called):
It is possible to register custom "Engine parts" (managers or components or however they end up being called):
At line 62 changed one line
* These custom manager __must__ have a no-arg constructor.
* These custom managers __must__ have a no-arg constructor.
At line 74 changed one line
It's compromised of the classes and interfaces in the {{org.apache.wiki.api.plugins}} package.
It's composed of the classes and interfaces in the {{org.apache.wiki.api.plugins}} package.
At line 81 changed one line
It's compromised of the classes and interfaces in the {{org.apache.wiki.api.filter}} package.
It's composed of the classes and interfaces in the {{org.apache.wiki.api.filter}} package.
At line 88 changed one line
It's compromised of the classes and interfaces in the {{org.apache.wiki.api.providers}} and {{org.apache.wiki.api.search}} package.
It's composed of the classes and interfaces in the {{org.apache.wiki.api.providers}} and {{org.apache.wiki.api.search}} package.
At line 97 added 22 lines
!! Engine lifecycle extensions
Another {{[SPI|https://www.baeldung.com/java-spi]}} to allow custom components be aware of {{Engine}}'s initialization and shutdown, without having to deep dive on {{Engine}}'s internals. The interface to be implemented in this case is {{org.apache.wiki.api.engine.EngineLifecycleExtension}}, which is described in detail in the [How to write an engine lifecycle extension|HowToWriteAnEngineLifecycleExtension] page.
!! Event Listeners
Yet another {{[SPI|https://www.baeldung.com/java-spi]}} to allow easy registering of custom wiki event listeners, without having to care on how to properly register it. The interface to be implemented in this case is {{org.apache.wiki.api.events.CustomWikiEventListener}}, which is described in detail in the [How to write a custom wiki event listener|HowToWriteACustomWikiEventListener] page.
!! Logging
Log4J2 is used to do all the logging inside JSPWiki, with all Log4J (and SLF4J) calls transparently routed to Log4J2. As such, existing 3rd party plugins, filters and providers will continue to log as expected, as Log4J calls will be routed to Log4J2, but the use of Log4J2 should be preferred onwards.
By default, JSPWiki will configure Log4J2 from the {{jspwiki[[-custom].properties}} files, expecting log configuration to be there using [Log4J2 properties syntax|https://logging.apache.org/log4j/2.x/manual/configuration.html#Properties]. {{jspwiki.use.external.logconfig=true}} can be set on {{jspwiki[[-custom].properties}} files to bypass JSPWiki log re-configuration and rely directly on Log4J2 configuration mechanisms.
%%bg-warning
%%label-warning warning%%
if you're using a __[JSPWiki customized .war|StartingPointForCustomExtensions#BuildingACustomized.warFileWithYourExtensions]__, please ensure that neither Log4J nor any SLF4J implementation end up in your customized .war.
%%
At line 95 changed one line
TBD
Most, if not all, of the API you'll be working with will be interfaces, so the appropiate way for unit testing an extension is to mock them with a mocking library, like for example [Mockito|https://site.mockito.org].
At line 123 added one line
Said that, there's a maven artifact, not part of the public API, which holds JSPWiki end-to-end testing support classes. It should be added as a dependency following this configuration:
At line 98 changed one line
!! My extension is not using the public API, what can I do?
%%prettify-nonum
{{{
<dependency>
<groupId>org.apache.jspwiki</groupId>
<artifactId>jspwiki-main</artifactId>
<type>test-jar</type>
<version>LATEST_JSPWIKI</version>
<scope>test</scope>
</dependency>
}}}
%%
At line 137 added 46 lines
The most important class in this artifact is {{org.apache.wiki.TestEngine}} which is an {{Engine}} implementation suitable to be used while testing. It allows to mimic JSPWiki running behaviour and has a number of {{static build(..)}} methods which make really easy to have a {{TestEngine}} up and running:
%%prettify-nonum
{{{
package com.myorg.jspwiki.extensions;
import org.apache.wiki.TestEngine;
import org.apache.wiki.api.providers.PageProvider;
import org.apache.wiki.api.spi.Wiki;
import org.apache.wiki.pages.PageManager;
[...]
import org.junit.jupiter.api.Assertions;
import org.junit.jupiter.api.Test;
[...]
import static org.apache.wiki.TestEngine.with;
public class MyAwesomeTest {
static TestEngine engine = TestEngine.build( with( "jspwiki.usePageCache", "false" ),
with( "jspwiki.pageProvider", "WikiPageAdapterProvider" ),
with( "jspwiki.attachmentProvider", "WikiAttachmentAdapterProvider" ),
with( "jspwiki.pageProvider.adapter.impl", "com.myorg.jspwiki.extensions.AwesomePageProvider" ),
with( "jspwiki.attachmentProvider.adapter.impl", "com.myorg.jspwiki.extensions.AwesomeAttachmentProvider" ) );
@Test
public void testPageProvider() throws Exception {
final PageProvider pageProvider = engine.getManager( PageManager.class ).getProvider();
Assertions.assertEquals( "com.myorg.jspwiki.extensions.AwesomePageProvider", pageProvider.getProviderInfo() );
pageProvider.putPageText( Wiki.contents.page( engine, "page4" ), "some crazy text here" );
Assertions.assertTrue( pageProvider.pageExists( "page4" ) );
}
[...]
}
}}}
%%
%%bg-info
%%label-info info%%
note how {{TestEngine}} is defined with an {{static}} qualifier. This ensures the {{Engine}} is only initialized once throughout all the tests' executions.
%%
!! My/An extension is not using the public API, what do I do?
At line 102 changed one line
If you are using an extension that does not use the public API consider contacting the extension author so he/she considers a new release. In the meantime, JSPWiki includes an specific module, {{org.apache.jspwiki:jspwiki-210-adapters}} which provides backwards compatibility with extensions not using the public API.
If you are using an extension that does not use the public API, consider contacting the extension author so he/she considers a new release. In the meantime, JSPWiki includes an specific module, {{org.apache.jspwiki:jspwiki-210-adapters}} which provides backwards compatibility with extensions not using the public API.
At line 106 changed one line
Page and attachment providers
Page and attachment providers should modify its {{jspwiki-[[custom].properties}}:
At line 108 changed one line
TBD
* Page providers
** {{jspwiki.pageProvider}} should be set to {{WikiPageAdapterProvider}} and then {{jspwiki.pageProvider.adapter.impl}} to the actual page provider.
* Attachment providers
** {{jspwiki.attachmentProvider}} should be set to {{WikiAttachmentAdapterProvider}} and then {{jspwiki.attachmentProvider.adapter.impl}} to the actual attachment provider.
At line 196 added 4 lines
%%bg-warning
%%label-warning warning%%
note this module is subject to disappear at some point in the future, on a [minor release|VersioningProposal], so extension authors should consider migrating to the public API.
%%
At line 201 added 11 lines
%%bg-warning
%%label-warning warning%%
provided compatibility is limited to the execution of extensions not using the public API. If, for whatever reason, an extension uses part of JSPWiki that has disappeared due to ''[minor release versioning|VersioningProposal]'', then the extension will be loaded but it is bound to cause an exception when reaching that piece of code (this of course applies to extensions using the public API anyway).
%%
\\
[Category.Documentation]
[{PageViewPlugin}]
This page (revision-22) was last changed on 02-Dec-2023 15:46 by Juan Pablo  Top