Difference between revisions of "Documentation/DevGuide/OfficeDev/XML Based Filter Development"

From Apache OpenOffice Wiki
Jump to: navigation, search
(Introduction)
(Introduction)
Line 14: Line 14:
 
The advantage of the XML filter adapter framework is that you do not have to work with document models to create a document from an import file, nor do you have to iterate over a document model to export it to a different file format. Rather, you can use the {{PRODUCTNAME}} XML file format to import and export. When importing, you parse your import file and send {{PRODUCTNAME}} XML to the filter adaptor, which creates a document for you in the GUI. When exporting, the office sends a description of the current document as {{PRODUCTNAME}} XML, so that you can export without having to iterate over a document model.
 
The advantage of the XML filter adapter framework is that you do not have to work with document models to create a document from an import file, nor do you have to iterate over a document model to export it to a different file format. Rather, you can use the {{PRODUCTNAME}} XML file format to import and export. When importing, you parse your import file and send {{PRODUCTNAME}} XML to the filter adaptor, which creates a document for you in the GUI. When exporting, the office sends a description of the current document as {{PRODUCTNAME}} XML, so that you can export without having to iterate over a document model.
  
As described in the chapter about [[Documentation/DevGuide/OfficeDev/Filter|filters]] a filter works through its method <code>filter()</code>. In case of XML based filters this method is implemented by the XML filter adaptor. Based on its [[Documentation/DevGuide/OfficeDev/Properties_of_a_Filter|"UserData" property]] it instantiates an XML import filter and uses its method <idlm>com.sun.star.xml.XImportFilter:importer</idlm>() to pass a MediaDescriptor for the source, a specialized XML document handler for {{PRODUCTNAME}} XML, and user data. The import filter must read the import source and deliver {{PRODUCTNAME}} XML to the document handler received in the call to <code>importer()</code>, emulating a SAX parser that calls the parser callback functions.  
+
As described in the chapter about [[Documentation/DevGuide/OfficeDev/Filter|filters]] a filter works through its method <code>filter()</code>. In case of XML based filters this method is implemented by the XML filter adaptor. Based on its [[Documentation/DevGuide/OfficeDev/Properties_of_a_Filter#Sample_configuration_for_an_XML_based_filter|"UserData" property]] it instantiates an XML import filter and uses its method <idlm>com.sun.star.xml.XImportFilter:importer</idlm>() to pass a MediaDescriptor for the source, a specialized XML document handler for {{PRODUCTNAME}} XML, and user data. The import filter must read the import source and deliver {{PRODUCTNAME}} XML to the document handler received in the call to <code>importer()</code>, emulating a SAX parser that calls the parser callback functions.  
  
 
In case of export filters the same <code>filter()</code> call will use the "UserData" property to instaniate an XML export filter and use its method <idlm>com.sun.star.xml.XExportFilter:exporter</idlm>() to pass a target location and user data. In this case, the office expects the export filter to be a <idl>com.sun.star.xml.sax.XDocumentHandler</idl>, which is able to handle {{PRODUCTNAME}} XML. The office creates an export stream with {{PRODUCTNAME}} XML, and parses this XML so that the export filter receives the SAX callbacks and can translate them to whatever is necessary, writing the result to the target received in the call to [http://api.openoffice.org/docs/common/ref/com/sun/star/xml/XExportFilter.html#exporter com.sun.star.xml.XExportFilter:exporter]().
 
In case of export filters the same <code>filter()</code> call will use the "UserData" property to instaniate an XML export filter and use its method <idlm>com.sun.star.xml.XExportFilter:exporter</idlm>() to pass a target location and user data. In this case, the office expects the export filter to be a <idl>com.sun.star.xml.sax.XDocumentHandler</idl>, which is able to handle {{PRODUCTNAME}} XML. The office creates an export stream with {{PRODUCTNAME}} XML, and parses this XML so that the export filter receives the SAX callbacks and can translate them to whatever is necessary, writing the result to the target received in the call to [http://api.openoffice.org/docs/common/ref/com/sun/star/xml/XExportFilter.html#exporter com.sun.star.xml.XExportFilter:exporter]().
 
For a filter of this type to operate, three things are necessary.
 
 
# The XML filter adaptor.
 
# A filtering component that implements the required interfaces.
 
# A valid filter and type definition.
 
 
Both the XML filter adaptor and the filtering component are UNO components that can be instantiated through the [http://api.openoffice.org/docs/common/ref/com/sun/star/lang/XMultiServiceFactory.html#createInstance /com.sun.star.lang.XMultiServiceFactory:createInstance]() method. Since the XML filter adaptor is generic, the filtering component is all that needs to be implemented. Once this has been done, the ''TypeDetection.xcu'' file can be expanded to include the newly created filter definition.
 
 
A significant difficulty in conversions between formats is the conceptual mapping from one format to the other. {{PRODUCTNAME}} provides XML filter components that carry out the mapping at runtime, so that XML based filter implementers can read from XML streams when exporting and write to XML streams when importing.
 
  
 
===Sample implementations===
 
===Sample implementations===

Revision as of 16:14, 6 October 2008



Introduction

This chapter outlines the development of XML based filtering components that use the XML filter adaptor framework. Further information is also available at http://xml.openoffice.org/filter/. The XML filter adaptor is a generic com.sun.star.document.XFilter implementation. It has been designed to be reusable, and to supply a standard method of designing and referencing XML based import and export filters. The XML filter adaptor does not perform any of the filtering functionality itself, but instead is used to instantiate a filtering component.

The advantage of the XML filter adapter framework is that you do not have to work with document models to create a document from an import file, nor do you have to iterate over a document model to export it to a different file format. Rather, you can use the OpenOffice.org XML file format to import and export. When importing, you parse your import file and send OpenOffice.org XML to the filter adaptor, which creates a document for you in the GUI. When exporting, the office sends a description of the current document as OpenOffice.org XML, so that you can export without having to iterate over a document model.

As described in the chapter about filters a filter works through its method filter(). In case of XML based filters this method is implemented by the XML filter adaptor. Based on its "UserData" property it instantiates an XML import filter and uses its method importer() to pass a MediaDescriptor for the source, a specialized XML document handler for OpenOffice.org XML, and user data. The import filter must read the import source and deliver OpenOffice.org XML to the document handler received in the call to importer(), emulating a SAX parser that calls the parser callback functions.

In case of export filters the same filter() call will use the "UserData" property to instaniate an XML export filter and use its method exporter() to pass a target location and user data. In this case, the office expects the export filter to be a com.sun.star.xml.sax.XDocumentHandler, which is able to handle OpenOffice.org XML. The office creates an export stream with OpenOffice.org XML, and parses this XML so that the export filter receives the SAX callbacks and can translate them to whatever is necessary, writing the result to the target received in the call to com.sun.star.xml.XExportFilter:exporter().

Sample implementations

There are currently three filtering components which use the XML filter adapter.

The first one is the XMergeBridge. This has been created as a means of linking the XMerge Small Device filter framework with OpenOffice.org. This means that any available XMerge plugin, can also be used as a OpenOffice.org filter. This is currently hosted within the XMerge<code> project in OpenOffice cvs at

 xml/xmerge/java/org/openoffice/xmerge/xmergebridge

The final two are a Java and a C++ implementation of a Flat OpenOffice.org XML reader and writer. These are intended to be sample filter component implementations, and offer a skeleton filter component that can be expanded upon by developers wishing to create their own filtering components. These are temporarily hosted in cvs at

 xml/xmerge/java/org/openoffice/xmerge/xmergebridge/FlatXml


Content on this page is licensed under the Public Documentation License (PDL).
Personal tools