Package com.sapportals.wcm.service.pipeline

Contains interfaces for transforming the layout and format of resources.

See: Description

Interface Summary

Interface	Description
IConst	Constant definitions for the WCM Pipeline package.
IPipelineService	Interface for the WCM pipeline service.
IXsltPipelineService	The XSLT-Pipeline is a specialized version of the pipeline.

Class Summary

Class	Description
PipelineServiceFactory	Service factory for the service of this package.
RequestData	Wrapper class contains DOM (of type document ) or InputStream .
XsltPipelineServiceFactory	Service factory for the service of this package.

Package com.sapportals.wcm.service.pipeline Description

Contains interfaces for transforming the layout and format of resources.

Package Specification

Purpose
Detailed_Concept
Interfaces
Code_Samples
Implementation Notes

Purpose

The publishing pipeline is the technical infrastructure that enables the transformation of resources from one format to another or from one layout to another. When a filter has been defined for a particular file extension, mime type or folder, it is the pipeline that actually executes the transformation process specified by the filter.

The pipeline package and other related packages offer interfaces that can be addressed by an application that wants to use the pipeline. Before introducing these interfaces, the following section gives you an overview of the architecture of the pipeline and explains how the pipeline works at a technical level. This background information makes it easier to understand the purpose of the interfaces in this package and the other related packages.

Detailed Concept

The pipeline is composed of three main components: the producer, the processor and the formatter. Each of these is responsible for executing a different part of the process that transforms a file from one form to another. The components are bound together by a supervisory instance, the pipeline controller, which coordinates and controls the work of the other components.

The graphic illustrates the main pipeline components:

The producer is the first instance that is called, when there is a request to process a resource with the publishing pipeline. It fetches the content of the resource, prepares it for further processing and passes it on to the processor. The processor then carries out the actual transformation process and changes the layout or format of the resource. Finally, the formatter prepares the output. It processes the resource with a formatter program to generate output with a particular format or it simply prepares an output stream and passes it on to another instance. Depending on whether the resource that is processed is an XML or non-XML file, the individual steps within the process differ. The next sections explains the individual processing steps of the publishing pipeline in detail, taking into account the different approaches that are necessary for XML and non-XML resources.

Pipeline Controller

The pipeline controller is an internal component that is responsible for ensuring that the processing steps executed by the pipeline are performed by the right component in the right sequence. To do this, the controller needs instructions encoded in XML. If the resource that is processed by the pipeline is already an XML, the instructions can be included directly in this file. If the resource has a different format, an additional empty XML is required to store them. The manner in which the controller is supplied with instructions can differ. Sometimes the instructions are already included directly in the resource that is passed on to the pipeline, sometimes they are provided by parameters of method calls and occasionally they have to be fetched from other sources and subsequently written into the XML file. The pipeline offers a mechanism called the default processor that acquires the processing information for the Controller and writes it into the available XML file. Whenever the controller registers that no instructions are available, it starts the default processor and in this way is always able to obtain the relevant processing information.

Typically, the instructions for the controller specify the type of pipeline processor that is required, the URL of the stylesheet that is to be applied to the document and the formatter program that generates the output. The example here shows instructions that inform the controller to start an XSLT processor, to use the stylesheet page.xsl and to run the formatter program that generates HTML.

<?wcm-process type="xslt"?>
<?xml-stylesheet href="page.xsl" type="text/xsl?">
<?wcm-format type="text/html"?>

Interfaces

The main interfaces of the publishing pipeline and their relationships are shown in the following graphic:

The interfaces shown in the diagram are included in different pipeline packages. For more information on individual interfaces, refer to the corresponding package which is specified in the table. For information on the KM implementation of these interfaces see the Implementation Notes.

Interfaces	Package
IPipelineService XsltPipelineService	com.sapportals.wcm.service.pipeline
IProcessor	com.sapportals.wcm.service.pipeline.processor
IFormatter	com.sapportals.wcm.service.pipeline.formatter
IProducer	com.sapportals.wcm.service.pipeline.producer
IXmlParser IXslTransformer	com.sapportals.wcm.service.pipeline.tools

Package service.pipeline

The com.sapportals.wcm.service.pipeline package offers the following central interfaces for accessing the functionality of the publishing pipeline:

• IPipelineService
  This offers methods to perform any type of transformation process
• IXsltPipelineService
  This offers methods to perform a transformation with the XSLT processor

The sections that follow explain the purpose of the above interfaces, introduce their most important methods and summarize the steps that are necessary to use them in a program.
Most transformations performed with the pipeline use the XSLT processor to convert an XML file with an XSL stylesheet. For these transformations, it is easiest to use the IXsltPipelineService interface because it is specialized for this process and automates some of the steps. It handles the default processor and the creation of processing instructions automatically. TheIPipelineService interface must be used for other transformations like the formatting of an HTML with a cascading stylesheet or for the implementation of a new pipeline service.

IPipelineService

You can use the IPipelineService interface to program any type of transformation process, regardless of the type of processor or formatter involved. However, it requires that each step in the process is executed explicitly. In contrast, the IXsltPipelineService, which can only be used for XSLT transformations, performs most of the processing steps automatically. For this reason, you always use the IXsltPipelineService for XSLT transformations and the IPipelineService interface for other transformations that do not involve XML files. For example, if you want to change the layout of an html with a CSS, then you use the IPipelineService. In the transformation process the producer converts the non-XML file (eg. html) to a stream and passes it on to the stream processor. This transforms the layout and passes the changed stream on to a stream formatter.

When you use the IPipelineService interface, you must instantiate a producer and supply XML instructions for the pipeline controller. To do this, you instantiate a producer and a default processor. The producer API provides classes that can be used to instantiate different types of producers, the processor API provides a class for a default processor.

The following types of producers are available in the package com.sapportals.wcm.service.pipeline:

• ProducerFromResourceprocesses a resource
• ProducerFromStream processes a stream
• ProducerFromUrl processes the target of a URL
• ProducerFromString processes a string

A class for a default processor is available in the package com.sapportals.wcm.service.pipeline. The default processor is only required when no XML processing instructions are available for the transformation process. It offers methods to add processing instructions to an XML file that is provided by the pipeline.

To use the IPipelineService interface for a transformation, proceed as follows:

1. Ensure that an XML file, XSLT stylesheet and formatter program for the transformation process are available in the KM system. If the formatter is not availalbe, it must be deployed according to the standard deployment procedures in the portal.
2. Instantiate the appropriate producer. Depending on whether the content is available as a resource, URL, stream or string, instantiate a different producer type.
3. Ensure that instructions in XML format are available for the pipeline controller:

• If the content that is to be transformed is an XML, you can enter the instructions directly in the XML or with the help of a default processor. The instructions must specify the processor, stylesheet and the formatter program for the transformation process.

• If the content that is to be transformed is non-XML, you must instantiate a default processor and use the methods it offers to add processing instructions to an XML file. Again, you need to specify the processor, stylesheet and optionally the formatter program that is to be used for the transformation process.

4. Use one of the handle methods of the IPipelineService to execute the pipeline processing. The pipeline returns the content with the new format or layout.

If a formatter program to complete the transformation process is not explicitly specified, then the handle method automatically calls a default formatter. A different formatter is called, depending on the format of the content:

• For XML content, the formatter text/html is called
• For non-XML content, the stream formatter is called. This does not transform the content in any special way, but simply merges it with the xslt and returns it as a stream.

IXsltPipelineService

The IXsltPipelineService interface represents a specialized version of the pipeline. It applies an XSL stylesheet to an XML to change the layout of content. As this is the most frequent type of transformation process, the interface is also the most commonly used. When you use the interface, it necessary to instantiate a producer, but you do not need to explicitly call a default processor. The task of providing the processing instructions for the controller is performed internally. You do however need to provide the content as an XML, an XSL stylesheet and possibly a formatter program.
To use the IXsltPipelineService in a program, proceed as follows:

• Ensure that an XML file, XSLT stylesheet and formatter program for the transformation process are available in the KM system.
  
• Instantiate the producer
  
• Use one of the handle methods of the IXsltPipelineService interface to perform the transformation. The method automatically calls the processor required for the transformation process. When you call the method, you can optionally specify the formatter program you want to use to generate the output.

The formatter program for the specified mime type must be available and entered in the KM configuration framework. If the formatter is not available it must be deployed according to the standard deployment procedures in the portal.

Code Samples

The following code samples show you how to:

• Use the IXsltPipelineService to transform an XML resource with an XSL stylesheet
• Use the IPipelineService interface to change a HTML text with a CSS
  

Using the IXsltPipelineService Interface

The code sample shows how to use the IXsltPipelineService interface to transform an XML resource with an XSL stylesheet.

import com.sapportals.wcm.util.uri.RID;
import com.sapportals.wcm.util.content.IContent;
import com.sapportals.wcm.repository.ResourceFactory;
import com.sapportals.wcm.repository.IResource;
import com.sapportals.wcm.service.pipeline.IXsltPipelineService;

// Get xsl stylesheet
IResource xsl = ResourceFactory.getInstance().getResource(
RID.getRID("/etc/filter/testTransform.xsl"),
ResourceFactory.getInstance().getServiceContext());
// Get xml data
IResource xml = ResourceFactory.getInstance().getResource(
RID.getRID("/documents/folder/test.xml"),
ResourceFactory.getInstance().getServiceContext());
// Get XsltPipeline
IXsltPipelineService xslpipe =
(IXsltPipelineService)ResourceFactory.getInstance().getServiceFactory().
getService("xsltpipeline");

// Build producer for xml and xsl
ProcuderFromResource xml = new ProcuderFromResource(xml);
ProcuderFromResource xsl = new ProcuderFromResource(xsl);

// Use XsltPipeline:
// Transform xml data with xsl stylesheet and format the result
// with the 'text/html' formatter
IContent content = xslpipe.handle(xml, xsl, null, "text/html");

Using the IPipelineService Interface

The following code sample shows how to use the IPipelineService interface to merge HTML text with a stylesheet.

ProducerFromStream html = ...
IContent content = null;

IPipelineService pipeline = (IPipelineService)ResourceFactory.getInstance().getServiceFactory().getService(IServiceTypesConst.PIPELINE_SERVICE);
Properties prop = new Properties();
prop.put("STYLESHEET", "file:///C:/myFolder/controls_ie5.css");

DefaultProcessor dp = new DefaultProcessor();

dp.addWcmProcess(0, "htmlcss", null);
dp.addWcmFormat("application/octet-stream");

content = pipeline.handle(html, dp, prop);

Implementation Notes

The following table gives an overview of the main interfaces of the pipeline, the KM classes that implement them and the purpose of the classes.

Interface	Package	Classes
IProducer	pipeline.producer	ProducerFromResource prepares content provided by a resource ProducerFromStream prepares content provides as a stream ProducerFromUrl prepares content provided as the target of a URL ProducerFromString prepares content provided by a string
IProcessor	pipeline.processor	HTMLProcessor merges HTML with a CSS XSLT Processor transforms an XML DOM with an XSL stylesheet
IFormatter	pipeline.formatter	JaxpSerializeFormatter generates text from an XML DOM StreamFormatter passes stream data on to another instance for output FOFormatter transforms an XML DOM into PDF
IXmlParser	pipeline.tools	JaxpParser checks validity of XML and creates the DOM from an XML
IXslTransformer	pipeline.tools	JaxpTransformer processes the DOM with a stylesheet