Package com.sapportals.wcm.repository.filter

Contains interfaces and classes to define repository filters.

See:
Description

Interface Summary

AbstractFilterManager.CFG	TBD: Description of the class.
AbstractFilterManager.FILTER_PRIO	TBD: Description of the class.
AbstractFilterManager.TYPE	TBD: Description of the class.
IContentFilter	This interface defines a content filter that will modify the content of a resource.
IContentFilterManager	This interface defines a content filter manager.
IFilter	TBD: Description of the interface.
IFilterFactory	This client interface of the filter factory defines methods for registering and unregistering filters at run-time.
IFilterManager	Basic interface for all filter components.
INamespaceFilter	A namespace filter will be applied on namespace operations like getResource(), getChildren().
INamespaceFilterManager	A namespace filter manager implements the behaviour for applying namespace filters.
IPropertyFilter	Property filters are used to manipulate resource properties and their visibility.
IPropertyFilterManager	A property filter manager implements the behaviour for applying property filters.
IReadOnlyContentFilter	A content filter that does not change the content.
IRidFilter	A RID filter object is created by a IRidFilterManager and is responsible for processing a RID.
IRidFilterManager	The RID filter manager must decide whether to apply a filter and create the appropriate filter objects and initialize them with the RID to process and any other parameters it needs.
IUriFilter	Deprecated. As of EP 5.0 SP5, replaced by IRidFilter
IUriFilterManager	Deprecated. As of EP 5.0 SP5, replaced by IRidFilterManager

Class Summary

AbstractContentFilterManager	Abstract base class for content filter managers.
AbstractFilterManager	Abstract base class for all filter managers.
AbstractNamespaceFilterManager	Abstract base class for namespace filter managers.
AbstractPropertyFilter
AbstractPropertyFilterManager	Abstract base class for property filter managers.
AbstractRidFilterManager	Abstract base class for RID filter managers.
AbstractUriFilterManager	Deprecated. as of EP 5.0 SP5, replaced by AbstractRidFilterManager.

Exception Summary

FilterConfigurationException

The application tried to check out a resource that is not versioned.

Package com.sapportals.wcm.repository.filter Description

Contains interfaces and classes to define repository filters.

Package Specification

Purpose
Detailed Concept
Interfaces and Classes
Configuration
Implementation Notes

Purpose

Before a resource is read or saved, it can be processed in various ways by a filter. The Knowledge Management (KM) platform distinguishes between different types of filters that serve different purposes:

• Content filter process the content of resources
• Property filter modify and control the visibility of resource properties
• Namespace filter control the visibility of resources

In addition to these filter types, the KM platform makes a distinction between read and write filter. If a filter is applied before a resource is displayed, then it is a read filter. If the filter is applied before the resource is saved, then it is a write filter. For example, in the KM environment, whenever a resource is fetched with the getContent() method, the method checks whether a read filter has to be applied before returning the content. Similarly, whenever the setProperties() method is executed, the method checks whether a write filter has to be applied before saving the properties.

Filters can be cascaded. This means several filters can be applied to a resource in a predefined sequence, one after the other.

Detailed Concept

This section describes the different filter types in detail.

Property Filters

Property filters are used to manipulate the properties of resources and their visibility. They can modify, delete or add properties to a resource. For example, with the help of a filter, it is possible to change the property that specifies the author of a resource. The personal name of the author can be changed to the company name. Properties of a resource are normally stored in a PropertyMap object. When a filter is applied, the contents of this object are modified.

A special form of a property filter controls the visibility of application properties. Application properties store information related to the resource in the database. However this information is not accessible for other components and cannot be presented to users unless it is converted to a normal property. It is the task of a special type of property filter to fetch the application properties from the database, to process them and then to add them to the PropertyMap of the resource. Once they are stored in the PropertyMap they can be accessed by other applications in the normal manner and displayed for end users.

An example of an application that uses this type of property filter is rating. When a user rates a resource by entering an assessment, this information is stored in the database as an application property. When other applications want to access this rating, a property filter reads the information from the database and adds it to the PropertyMap of the resource. Once this has been done the rating is accessible to other components. Services use application properties instead of standard properties because not all repository types support standard properties.

The property filters that are implemented for the KM platform support the processing of specific KM applications. They are not general-purpose filter that are useful for external applications. For this reason, if an external application needs a filter, it must build the filter it requires from scratch, using the available interfaces. Abstract classes are provided for this purpose:

• AbstractPropertyFilterManager to build a filter manager
• AbstractPropertyFilter to build a filter

Namespace Filters

Namespace operations, like displaying the children of a collection or fetching a resource, involve mapping a RID to a resource. When such operations are performed, a filter can be used to manipulate the mapping of the RID to the resource and control the visibilty of the resource. For example, when the getResource or getChildren methods are called, a filter can be used to hide resources that fulfill predefinde criteria.

In the KM environment namespace filters are implemented for certain applications, for example, for time-based publishing and collaboration services like personal notes, feedback and comments. In these applications, the namespace filters are used to control the visibility of resources. For example, when time-based publishing is active and the methods getChildren(), getResource() or Search()are executed, a namespace filter is applied to ensure that only resources that may be viewed and published are returned.

The KM Platform does not provide any general-purpose namespace filter that are useful for external applications. If an external application needs a filter, it must build a new filter and filter manager. An abstract class and interface are provided for this purpose:

• INamespaceFilterManager to build a filter manager
• INamespaceFilter to build a filter

Content Filters

Content filters can be applied to resources before they are viewed or saved. They can modify the content or the format and layout of a file before presenting it to a client. When they modify content, they add, delete or change text. When they modify layout, they merge the content with metadata and in this way are able to represent the same data in different formats that can be viewed on different devices. For example, with the help of content filters, an XML file that contains a particular text can be transformed into an HTML file for display in a browser or into a WML file for display on a handheld device. Similarly, the text of a file can be presented in different formats to serve different audiences. The same information can be distributed as a news column, a business report or a text file. The advantage of the filter is that it makes it easy to reuse content in different environments. Also, it enables a separation of content and presentation, thus allowing different individuals to be responsible for the tasks of writing the content and designing its presentation.

The KM platform has implemented a number of content filter that can be used by external applications. To use one of these filters, the applications have to configure the filter with the help of the user interface of the KM Configuration Framework. Alternatively, if the filter offered by the platform do not meet requirements, applications can implement new filter using:

• AbstractContentFilterManager to implement the filter manager
• IContentFilter to implement the filter

Filter Manager

Each filter type has a corresponding filter manager. It is the task of the filter manager to instantiate the correct filter at runtime. When the KM framework is asked to retrieve or store a resource, it always checks whether a filter is defined for that resource. If a filter is defined, it calls the corresponding filter manager that instantiates the required filter and after processing returns the filtered resource. For each filter implementation there is a corresponding filter manager, for example, a namespace filter has a corresponding namespace filter manager.
Example for an XSLT Filter Manager
If a user clicks a resource in a folder view for which an XSLT filter has been configured, then the XSLT filter manager is started. It fetches all the filter information that is relevant for the transformation of the file from the configuration. This includes the name of the filter that is to be applied, the URL of the XSLT stylesheet, the URL of the formatter program and the mime type of the output. The Filter Manager then checks whether the filter defined in the configuration is applicable to the file in question. If so, it calls the filter, passing on the resource file and all the relevant information.

Interfaces and Classes

The main interfaces and classes of the package define the methods for different filter types and corresponding filter managers. To implement a new filter, it is necessary to build a filter that defines the filtering logic and a corresponding filter manager. If an abstract class is available, then the abstract class must be implemented. For example, to build a new namespace filter, it is necessary to implement AbstractNamespaceFilterManager and INamespaceFilter. Similarly, to build a new content filter, it is necessary to implement AbstractContentFilterManager and IContentFilter.
Apart from the filter and filter manager abstract classes and interfaces, the only other classes of importance in the package are those that define static member variables. These are: AbstractFilterManager.CFG, AbstractFilterManager.FILTER_PRIO and AbstractFilterManager.TYPE

Note that once a new filter and filter manager have been implemented, they are still not active within the framework. To integrate them in the framework it is necessary to:

• Create of an XML file for the configuration
  
• Deploy the XM file and the new filter and filter manager class

For more information on the procedure for deployment, see the Portal Develoment Kit.

Configuration

An application that wants to use a filter has two choices. It can:

• Use an existing content filter
• Implement a new content, namespace or property filter
  

In both cases, a number of steps are necessary to configure the filter and inform the framework that it must use the filter. If a new filter is involved, an additional preparatory step of creating and deploying an XML file that enables the configuration is required. For details see Creation of an XML file for the Configuration.

Using a Content Filter

The following focuses on the configuration of content filter. The content filter already implemented for the KM platform carry out a transformation process using the publishing pipeline. The transformation is based on stylesheets and formatter programs. To enable the use of such a filter, the following configuration details must be set:

• The location, mime type and file extension of the resources which must be filtered
  
• The name and location of the XSL or HTML stylesheet and formatter program that are to be used. If an HTML filter is involved, no formatter is required.

Depending on the type of filter involved, additoinal settings are required. The settings are entered via the user interface of the KM Configuration Framework.

Once the configuration is complete, KM resources are automatically displayed in the format that is prescribed for them. For example, if a user in a folder view chooses to display an XML file that has been allocated to a filter that transforms a file to an RSS format, the file is automatically displayed in an RSS format.

Implementation Notes

The following section explains which filters have been implemented for the KM platform and how they interact with other framework components.

Content Filter Managers

When a client requests contents of a resource and a filter is configured for that resource then the content is always returned via the filter. The content itself is fetched from the framework, and then passed on to a filter manager for processing. Different filter managers are responsible for different types of file transformations. Currently the following managers are available:

• The Xslt filter manager transforms an XML document into a document with a different format. In the transformation process, an XSLT style sheet is applied to document and then a program called a formatter program creates a version of the document with the desired output format. With the help of the Xslt filter manager an XML file can be transformed and displayed in the formats:
  HTML, XHTML, WML, PLAIN, VRML, RSS and SVG-XML
• The Html filter manager changes the layout of an HTML document. It transforms an HTML document to a document with new formatting by applying a cascading stylesheet. It can provide a base tag and a URI handler.
  
• The Html stylesheet filter manager is an HTML filter without a base tag and URL handler properties.
  

At a technical level the processes controlled by the different filter managers are executed by the publishing pipeline. This is responsible for actually converting a resource from one layout or format to another.

The graphic illustrates the classes involved in a transformation process:

Using Stylesheets and Formatter Programs

XSLT filter that transform the format and layout of a resource can only function with the help of XSLT stylesheets and formatter programs. Standard formatters are available for different XSLT stylesheets. However, a special XSLT stylesheet has to be created for each new type of XML document. The KM platform provides a number of predefined formatter programs and stylesheets as shown in the table.

If you want to write your own XSLT stylesheet, which prepares an XML for processing with a formatter program, you must observe certain rules. For example, if you want to use a vrml formatter, the corresponding XSLT stylesheet must meet requirements for a vrml formatter.

Available Stylesheets and Formatter Programs

Output Format	Default XSLT Stylesheet location	Formatter
RSS News format	//etc/filter/rss/rss-html.xsl	text/html
SVG Scalable vector graphics format	//etc/filter/svg/page-svg.xsl	image/svg-xml
LDAP	//etc/filter/ldap/propsxml-html.xsl	text/html
PDF	//etc/filter/pdf/novel-fo.xsl	text/xslfo
VRML (interactive 3D multimedia format for the Web)	//etc/filter/vrml/hello-vrml.xsl model/vrml	model/vrml

The formatter programs for XHTML, WML or PLAIN formats are available in the KM platform without any corresponding XSLT stylesheets. The following lists the names of the formatter programs available for these formats. Note that in most cases the formatter has the same name as the mime type of the output file.

Output Format	Formatter Programs
XHTML	text/html
PLAIN Text format	text/plain
WML Wireless Markup Language format	text/wml