Filter Module
Generic base API to describe filters |
Type | JAR |
Category | |
Developed by | |
Rating | |
License | GNU Lesser General Public License 2.1 |
Bundled With | XWiki Standard |
Compatibility | First version containing annotations and descriptors related tools introduced in XWiki Commons 5.2 and input/output and handling moved from the old WikiStream Module in 6.2. |
Description
The idea behind this module is to make filters communicate with each other using common "events", much like XWiki Rendering framework (which is going to be rewritten base on this module) but more generic.
General architecture
There is no defined set of events at base API level, each filter can declare a set of supported events by implementing corresponding interfaces. Proxy helpers are provided to make easy for filters that might have different set of supported events to communicate with each other. Some well known events can be found in http://www.github.com/xwiki/xwiki-commons/tree/master/xwiki-commons-core/xwiki-commons-filter/xwiki-commons-filter-events and http://www.github.com/xwiki/xwiki-platform/tree/master/xwiki-platform-core/xwiki-platform-filter/xwiki-platform-filter-events modules.
The main Filter framework extensions points are the two following input and output modules:
- org.xwiki.filter.output.OutputFilterStreamFactory: which is responsible for converting events into the format this module has been written for (a XAR package, database documents, etc.)
- org.xwiki.filter.input.InputFilterStreamFactory which is responsible for parsing/reading an input and generate related events
See General architecture for more details.
UI
Filter framework can be manipulated using Filter application.
Existing modules
- Generic XML input and output (filter+xml)
- XAR package/document input and output (xwiki+xar/1.2)
- XWiki instance input and output (xwiki+instance)
- Confluence input (confluence+xml)
- MediaWiki input (mediawiki+xml)
- DokuWiki input (dokuwiki+text)
- XFF input and output (xwiki+xff/1.0)
- GitHub Importer input (githubimporter+wiki)
Filters
Annotations
Annotations to help write generic serializers/parsers:
- org.xwiki.filter.annotation.Default: the default value of a filter event parameter.
- org.xwiki.filter.annotation.Name: the name of a filter event parameter (mostly introduced because this information is not part of the bytecode in Java). Since 8.3/8.2.2/7.4.4 it also allows overriding the name of the event (which is otherwise extracted from the method name). .
Descriptors
org.xwiki.filter.FilterDescriptorManager component provide various tools to manipulate filters:
- "parse" a filter class to extract filter informations in a easier to manipulate set of Java objects (list of events and there parameters, etc.)
- create filter proxy which take care of calling or ignore right methods on an object implementing a set of filters