Difference between revisions of "Documentation/DevGuide/OfficeDev/Filter"

Revision as of 10:22, 4 June 2008

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 com.sun.star.document.FilterFactory. It 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. 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 com.sun.star.lang.XInitialization. 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:

• 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.

Template:Documentation/Tip

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 ... )).