Filter
As described in the previous chapter, filters are objects that can be used to import or export content into OpenOffice.org documents. Its API defines the two services com.sun.star.document.ImportFilter and com.sun.star.document.ExportFilter. A filter implementation can support both of them. If a particular filter only supports import, the users modifies the imported document and then presses the "Save" button, he will redirected to the "Save As" dialog as OpenOffice.org must assume that the filter component is "import only". 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, 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 directly after creation by the factory and is the first call to a new filter instance. It passes the configuration data of the filter and any possible 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")
...
}
}
}
Furthermore, depending on its action a filter supports the services com.sun.star.document.ImportFilter for import or com.sun.star.document.ExportFilter for export functionality.
The common interface of both services is com.sun.star.document.XFilter starts or cancels the filter process. How the canceling is implemented is an internal detail of the filter implementation, however a thread is a good solution.
On calling <idlml>com.sun.star.document.XFilter:filter</idlml>(), the already mentioned MediaDescriptor is passed to the service. It includes the necessary information about the content, for example, the URL or the stream, but not the source or the target model for the filter process.
Additional interfaces are part of the service description, com.sun.star.document.XImporter and com.sun.star.document.XExporter to get this information. These interfaces are used directly before the filter operation is started. A filter saves the model set by setTargetDocument() and setSourceDocument(), and uses it inside its filter operation.
This example code detects the required filter operation:
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;
}
The MediaDescriptor does not include the model, but it should include the already opened stream, true for the current implementation in OpenOffice.org. If it is there, it must be used. Only if a stream does not exist, it indicates that someone else uses this filter service, for example, outside OpenOffice.org, it creates a stream of your own by using the URL parameter of the descriptor.
In general, a filter must not change the position of an incoming stream without reading or writing data. The position inside the stream is 0. Follow the previously mentioned rules for handling streams of the section about the MediaDescriptor above. We can make these rules easier, because currently there are no external filters used inside office. See descriptions of the chapter "MediaDescriptor" before ... )).
| Content on this page is licensed under the Public Documentation License (PDL). |
