From Apache OpenOffice Wiki
< Documentation‎ | DevGuide
Revision as of 12:21, 1 November 2007 by Jsc (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Most of the services described before are used for loading. Normally, they are not necessary for saving, except the MediaDescriptor. Only filters are fixed members of both processes.

These objects also represent a service. Their task is to import or export the content of a type into or from a model. Accordingly, import filters are distinguished from export filters. It is possible to provide both functionality in the same implementation.

A filter is acquired from the factory service It provides a low-level access to the configuration that knows all registered filters of, supports search functionality, and creates and initializes filter components. The description of this factory and its configuration are provided below.

If a filter wants to be initialized with its own configuration data or get existing parameters of the corresponding create request, it implements the interface The method initialize() is used directly after creation by the factory and is the first request on a new filter instance. The parameter list of initialize() uses the following protocol:

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 An owner of a filter uses the provided name to find specific information about this component by using the FilterFactory service.

Documentation caution.png The interface provides functionality for reading and writing of this name. It is not allowed to change an internal filter name during runtime of, because all filter names must be unique and it is not possible for a filter instance to alter its name. Calls to 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 )  
         // no arguments - no initialization  
         if (lArguments.length<1)
         // Arguments[0] = own configuration data[] lConfig =
         // 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 =     
                         // 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;    
                         if (m_sInternalName=="filter_format_2")

Furthermore, depending on its action a filter supports the services for import or for export functionality.

The common interface of both services is 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, the already mentioned MediaDescriptor<//code> 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, and to get this information. These interfaces are used directly before the filter operation is started. A filter saves the model set by <code>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( xDocument ) 
     m_bImport = true;
 // used to tell us: "you will be used for export" 
 public void setSourceDocument( xDocument ) 
     m_bImport = false; 
 // detect required type of filter operation 
 public boolean filter([] lDescriptor ) 
      boolean bState = false; 
      if (m_bImport==true) 
        bState = impl_import( lDescriptor ); 
        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 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, 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).
Personal tools