Filter Module

Version 30.1 by Vincent Massol on 2021/03/17 19:56

cogGeneric base API to describe filters
TypeJAR
Category
Developed by

XWiki Development Team

Rating
0 Votes
LicenseGNU 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

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). Since 8.3 it's possible to avoid using it for method parameters as long as javac -parameters parameter is used when building the filter (this parameter is automatically enabled if you use XWiki standard parent pom).

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

Get Connected