Processing Chain

OpenOffice.org Developer's Guide

Office Development

< Previous Section

Next Section >

• OpenOffice.org Application Environment

• Desktop Environment
• Framework API

• Frame-Controller-Model Paradigm in OpenOffice.org
• Frames
• Controllers
• Windows
• Dispatch Framework

• Using the Desktop
• Using the Component Framework

• Getting Frames, Controllers and Models from Each Other
• Frames
• Controllers
• Models
• Window Interfaces

• Creating Frames Manually
• Handling Documents

• Closing Documents
• Storing Documents

• Using the Dispatch Framework

• Command URL
• Processing Chain
• Dispatch Process
• Dispatch Results
• Dispatch Interception

• Java Window Integration

• Common Application Features

• Internationalization

• Overview and Using the API
• Implementing a New Locale

• Linguistics

• Using Spellchecker
• Using Hyphenator
• Using Thesaurus
• Events
• Implementing a Spell Checker
• Implementing a Hyphenator
• Implementing a Thesaurus

• Integrating Import and Export Filters

• Filtering Process
• Filters
• Type Detection and its Configuration
• Properties of a Type
• Properties of a Filter
• Filter Options
• Properties of a FrameLoader
• Document API Filter Development

• XML Based Filter Development

• Writing the Filtering Component
• The Importer
• The Exporter
• XML Filter Detection

• Number Formats

• Managing Number Formats
• Applying Number Formats

• Document Events
• Path Organization

• Path Settings
• Path Variables

• Predefined Variables
• Custom Path Variables
• Resolving Path Variables

• OpenOffice.org Single Sign-On API
• RDF metadata

< Previous Page

Next Page >

A request is created by any object.User interface objects can create requests. Consider a toolbox where different functions acting on the office component are presented as buttons. When a button is clicked, the desired functionality is executed. If the code assigned to the button is provided with a suitable command URL, it handles the user action by creating the request and finding a component that can handle it. The button handler does not require any prior knowledge of the component and how it would go about its task.

This situation is handled by the design pattern chain of responsibility. Everything a component needs to know to execute a request is the last link of a chain of objects capable of executing requests. If this object gets the request, it checks if it can handle it or passes it to the next chain member until the request is executed, or the end of the chain is reached.

The chain members in the dispatch framework are objects implementing the interface com.sun.star.frame.XDispatchProvider. Every frame and controller supports it.In the simplest case, the chain consists of two members, a frame and its controller, but concatenating several chain parts on demand of a frame or a controller is possible. Once called, a controller passes on the call, that is, it can use internal frames created by its implementation. A frame also passes the call to other objects, for example, its parent frame.

The current implementation of the chain is different from a simple chain. A frame is always the leading chain member and must be called initially, but in the default implementation used in Apache OpenOffice, the frame first asks its controller before it goes on with the request. Other frame implementations handle this in a different way. Other chain members are inserted into the call sequence before the controller uses the dispatch interception capability of a frame. The developers should not rely on any particular order inside the chain.

The dispatch framework uses a generic approach to describe and handle requests with a lose coupling between the participating objects. To work correctly, it is necessary to follow certain rules:

1. Every chain starts at a frame, and this object decides if it passes on the call to its controller. The controller is not called directly from the outside. This is not compulsory for internal usage of the dispatch API inside an office component implementation. The two reasons for this rule are:

• A frame provides a com.sun.star.frame.XDispatchProviderInterception interface, where other dispatch providers dock. The frame implementation guarantees that these interceptors are called before the frame handles the request or passes it to the controller. This allows a sophisticated customization of the dispatch handling.
• If a component is placed into a context where parts of its functionality are not to be exposed to the outside, a special frame implementation is used to suppress or handle requests before they are passed to the controller. This frame can add or remove arguments to requests and exchange them.

2. A command URL is parsed into a com.sun.star.util.URL struct before passing it to a dispatch provider, because it is assumed that the call is passed on to several objects. Having a pre-parsed URL saves parsing the command string repeatedly. Parsing means that the members Complete, Main, Protocol and at least one more member of the com.sun.star.util.URL struct, depending on the given protocol scheme have to be set. Additional members are set if the concrete URL protocol supports them. For well known protocol schemes and protocol schemes specific to Apache OpenOffice, the service com.sun.star.util.URLTransformer is used to fill the struct from a command URL string. For other protocols, the members are set explicitly, but it is also possible to write an extended version of the URLTransformer service to carry out URL parsing. An extended URLTransformer must support all protocols supported by the default URLTransformer implementation, for example, by instantiating the old implementation by its implementation name and forwarding all known URLs to it, except URLs with new protocols.

The dispatch framework connects an object that creates a request with another object that reacts on the request. In addition, it provides feedback to the requester. It can tell if the request is currently allowed or not. If the request acts on a specific attribute of an object, it provides the current status of this attribute. Altogether, this is called status information, represented by a com.sun.star.frame.FeatureStateEvent struct. This information is reflected in a user interface by enabling or disabling controls to show their availability, or by displaying the status of objects. For example, a pressed button for the bold attribute of text, or a numeric value for the text height in a combo box.

The com.sun.star.frame.XDispatchProvider interface does not handle requests, but delegates every request to an individual dispatch object implementing com.sun.star.frame.XDispatch.

This is the concept, but the implementation is not forced and it may decide to return the same object for every request. It is not recommended using the dispatch provider object as a dispatch object.

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