Filter Module

Last modified by Thomas Mortagne on 2021/09/21 11:20

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

InputSource and OutputTarget

In most filters the convention to pass the data to read or the location when to write the produce data is through the following filter properties:

  • source: of type org.xwiki.filter.input.InputSource (or one of the InputSource extending interfaces to reduce the scope of supported data)
  • target: of type org.xwiki.filter.output.OutputTarget (or one of the OutputTarget extending interfaces to reduce the scope of supported locations)

Converter are also provided to help converting a variety of known input and target types into the corresponding InputSource and OutputTarget instances.

Known types supported for both InputSource and OutputTarget converter:

  • java.io.File
  • java.lang.String is mostly understood as a reference with a typed prefix (or actual String content if the prefix is unknown), see String reference parsing

Known types supported for InputSource converter:

  • java.io.InputStream
  • java.io.Reader
  • 13.8+ byte[]
  • java.net.URL

Known types supported for OutputTarget converter:

  • java.io.OutputStream
  • java.io.Writer

13.4+ It's possible to provide custom InputSource and OutputTarget converters by implementing org.xwiki.filter.input.InputSourceConverter or org.xwiki.filter.output.OutputTargetConverter components associated with the converted type using generics.

String reference parsing

The following prefixes are supported for InputSource and OutputTarget parsers:

InputSource only:

  • url: a URL stream
  • resource: a file located in the classloader
  • attach: 13.4+ an attachment referenced using standard XWiki attachment reference syntax
  • string: 13.4+ a plain string

Both InputSource and OutputTarget:

  • file: a local file

13.4+ It's possible to provide custom InputSource and OutputTarget parsers by implementing org.xwiki.filter.input.InputSourceReferenceParser or org.xwiki.filter.output.OutputTargetReferenceParser components.

Tags:
    

Get Connected