Generic base API to describe filters

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). 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
• XWiki 13.8+ byte[]
• java.net.URL

Known types supported for OutputTarget converter:

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

XWiki 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: XWiki 13.4+ an attachment referenced using standard XWiki attachment reference syntax
• string: XWiki 13.4+ a plain string

Both InputSource and OutputTarget:

• file: a local file

XWiki 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.