Filters
As described in the previous chapter, filters are objects that can be used to import or export content into or from OpenOffice.org documents. The API defines the two services com.sun.star.document.ImportFilter and com.sun.star.document.ExportFilter. A filter implementation can support one or both of them. If a particular filter that only supports import is used, the imported document is modified by the user and then the user presses the "Save" button, a "Save As" operation will be carried out instead as OpenOffice.org must assume that the filter component is "import only" and so storing must be done in a different format. It doesn't help to have a different export filter for the same content. If a direct "Save" operation should be possible, both filter services must be supported at the same filter object.
A filter is created from the factory service com.sun.star.document.FilterFactory. This service also provides a low-level access to the configuration that knows all registered filters of OpenOffice.org and their properties, supports search functionality, and creates and initializes filter components.
Filters can be initialized if they implement the interface com.sun.star.lang.XInitialization. The method initialize() is used by the filter factory service directly after creation of the filter object, before the filter is returned to the code that requested the filter. It passes the configuration data of the filter and all parameters and options that have been specified by the creation request to the factory. These properties usually originate from the MediaDescriptot and have been put there either by the code requesting the loading or storing or by user input in a filter options dialog. How such filter dialog can be implemented is explained in the chapter about parameters of the filter configuration.
The parameter list of initialize() uses the following protocol:
- The first item in the list is a sequence of com.sun.star.beans.PropertyValue structs, that describe the configuration properties of the filter.
- All other items are directly copied from the parameter Arguments of the factory interface method <idlml>com.sun.star.lang.XMultiServiceFactory:createInstanceWithArguments</idlml>().
A filter should be initialized, because one generic implementation is registered to handle different types, it must know which specialization is required. The simplest way to achieve this for the filter is to know its own configuration data, especially the unique internal name.
This information is used internally then, or it is provided by the interface com.sun.star.container.XNamed. An owner of a filter uses the provided name to find specific information about this component by using the FilterFactory service.
 |
The interface provides functionality for reading and writing of this name. It is not allowed to change an internal filter name during runtime of OpenOffice.org, because all filter names must be unique and it is not possible for a filter instance to alter its name. Calls to <idlml>com.sun.star.container.XNamed:setName</idlml>() should be ignored or forwarded to the FilterFactory service, which knows all unique names and can solve ambiguities! |
This code snippet initializes a filter instance:
private String m_sInternalName; public void initialize( Object[] lArguments ) throws com.sun.star.uno.Exception { // no arguments - no initialization if (lArguments.length<1) return; // Arguments[0] = own configuration data com.sun.star.beans.PropertyValue[] lConfig = (com.sun.star.beans.PropertyValue[])lArguments[0]; // Arguments[1..n] = optional arguments of create request for (int n=1; n<lArguments.length; ++n) { ... } // analyze own configuration data for our own internal // filter name! Important for generic filter services, // which are registered more then once. They can use this // information to find out, which specialization of it // is required. for (int i=0; i<lConfig.length; ++i) { if (lConfig[i].Name.equals("Name")) { m_sInternalName = AnyConverter.toString(lConfig[i].Value); // Tip: A generic filter implementation can use this internal // name at runtime, to detect which specialization of it is required. if (m_sInternalName=="filter_format_1") m_eHandle = E_FORMAT_1; else if (m_sInternalName=="filter_format_2") ... } } }
In one single workflow filters can act as an import or an export filter. If content is loaded, the creator of the filter will use the com.sun.star.document.XImporter interface and its method setTargetDocument() to bind the filter to the document it should import into. If content is stored, the interface com.sun.star.document.XExporter and its method setSourceDocument() will bind the filter to the document it shall get data from. The filtering process is done by the same method in both cases: it's the filter() method of the com.sun.star.document.XFilter interface that both kinds of filters must support. Here the MediaDescriptor is passed to the filter.
This example code shows how the required filter operation can be tracked inside the filter implementation easily:
private boolean m_bImport; // used to tell us: "you will be used for import" public void setTargetDocument( com.sun.star.lang.XComponent xDocument ) throws com.sun.star.lang.IllegalArgumentException { m_bImport = true; } // used to tell us: "you will be used for export" public void setSourceDocument( com.sun.star.lang.XComponent xDocument ) throws com.sun.star.lang.IllegalArgumentException { m_bImport = false; } // detect required type of filter operation public boolean filter( com.sun.star.beans.PropertyValue[] lDescriptor ) { boolean bState = false; if (m_bImport==true) bState = impl_import( lDescriptor ); else bState = impl_export( lDescriptor ); return bState; }
| Content on this page is licensed under the Public Documentation License (PDL). |
