Difference between revisions of "Documentation/DevGuide/OfficeDev/Integrating Import and Export Filters"

Revision as of 11:12, 1 October 2008

OpenOffice.org provides several implementations for objects that can be displayed in a task window. In the context of the Component Framework they are called Office Components. These components can be created from a content, e.g. stored in a file on disk. Most of the time this will be done by creating a document and loading the content into it using a filter. This section explains the implementation of OpenOffice.org import and export filter components. OpenOffice.org also allows to load content into a component directly by using a frame loader, but this is described in this section only briefly.

Introduction

Inside OpenOffice.org a document is represented by its document service, called model. For a list of available document services, refer to the section Document Specific Features. On disk, the same document is represented as a file or possibly as a dynamically generated output, for example, of a database statement. To generalize this and abstract from single disk files we just call it "content". The content is a serialization of a model, e.g. the ODF or the Word model. A filter component is used to convert between this model and the internal model defined by the document core model as shown in the following diagram.

Import/Export Filter Process

In our API the three entities in the above diagram, content, model, and filter, are defined as UNO services. The services consist of several interfaces that map to a specific implementation, for example, using C++ or Java.

The filter implementer has to develop a class that implements the com.sun.star.document.ExportFilter or com.sun.star.document.ImportFilter service, or both in case the filter should support import and export. The filter will get a com.sun.star.document.MediaDescriptor that defines the stream the filter must use for its input or output.

Approaches

To implement said filter class, a developer can

• link against the application core
• use the document API
• use the XML based techniques (sax or xslt)

Each method has unique advantages and disadvantages, that are summarized briefly:

Using the core data structure and linking against the application core is the way how all elder filters (originating from the "pre-UNO" area) are implemented in OpenOffice.org. As the disadvantages are huge (maintenance nightmare when core data structures or interfaces change), this approach is not recommended for new filter development in general.

Using the OpenOffice.org API based on UNO is more advantageous, since it solves the technical problems indicated in the above paragraph. The idea is to read data from a file on loading and build up a document using the OpenOffice.org API, and to iterate over a document model and write the corresponding data to a file on storing. The UNO component technology insulates the filter from binary layout, and other compiler and version dependent issues. Additionally, the API is expected to be more stable than the core interfaces, and provides an abstraction from the core applications.

The third is to import and export documents using the XML-based file format. UNO-based XML import and export components feature all of the advantages of the previous method, but additionally provide the filter implementer with a clean, structured, and fully documented view of the document. A significant difficulty in conversion between formats is the conceptual mapping from the one format to the other. From OpenOffice.org 1.1.0 there are XML filter components that carry out the mapping at runtime, so that filter implementers can read from XML streams when exporting and write to XML streams when importing.

In addition to the filter itself the developer must provide some information about it to enable OpenOffice.org to integrate it into the application framework. This information is provided as a configuration file. To understand better what needs to be in this file let's have a look on how OpenOffice.org deals with filters.

Checklist for filter developers

Integrating a filter into OpenOffice.org requires the following steps that will be explained in the following sections:

1. Implement a filter (required).
2. Implement an com.sun.star.document.ExtendedTypeDetection service to support detection by content (optional).
3. Implement a filter options dialog if the implemented filter requires additional parameters (optional).
4. Register the component libraries as UNO services (required). If the filter is deployed as an extension this is a part of it. If the filter will become a part of the OpenOffice.org installation, the registration must be done as described in the chapter Deployment Options for Components.
5. Add configuration information to the org.openoffice.TypeDetection node of the configuration. If the filter is deployed as an extension, the extension will contain a configuration file. OpenOffice.org will access it as part of the extensions layer of the Configuration Manager. If the filter will become a part of the OpenOffice.org installation, the configuration must be intergrated into the build process.

It is recommended to read the following chapters before carrying out any of these steps.