Objects, Interfaces, and Services

From Apache OpenOffice Wiki
Jump to: navigation, search



Objects

In UNO, an object is a software artifact that has methods that you can call and attributes that you can get and set. Exactly which methods and attributes an object offers is specified by the set of interfaces it supports.

Interfaces

An interface specifies a set of attributes and methods that together define one single aspect of an object. For instance, the interface com.sun.star.resource.XResourceBundle specifies the attribute Parent and the methods getLocale() and getDirectElement().

  module com { module sun { module star { module resource { interface XResourceBundle: com::sun::star::container::XNameAccess {
      [attribute] XResourceBundle Parent;
      com::sun::star::lang::Locale getLocale();
      any getDirectElement([in] string key);
  };
  }; }; }; };

To allow for reuse of such interface specifications, an interface can inherit one or more other interfaces (as, for example, XResourceBundle inherits all the attributes and methods of com.sun.star.container.XNameAccess). Multiple inheritance, the ability to inherit more than one interface, was introduced in OpenOffice.org 2.0.

Strictly speaking, interface attributes are not needed in UNO. Each attribute could also be expressed as a combination of one method to get the attribute's value, and another method to set it (or just one method to get the value for a read-only attribute). However, there are at least two good reasons for the inclusion of interface attributes in UNO: First, the need for such combinations of getting and setting a value seems to be widespread enough to warrant extra support. Second, with attributes, a designer of an interface can better express nuances among the different features of an object. Attributes can be used for those features that are not considered integral or structural parts of an object, while explicit methods are reserved to access the core features. Historically, a UNO object typically supported a set of many independent interfaces, corresponding to its many different aspects. With multiple-inheritance interfaces, there is less need for this, as an object may now support just one interface that inherits from all the other interfaces that make up the object’s various aspects.

Services

Historically, the term “service” has been used with an unclear meaning in UNO. Starting with OpenOffice.org 2.0, the underlying concepts have been made cleaner. Unfortunately, this leaves two different meanings for the term “service” within UNO. In the following, we will use the term "new-style service" to denote an entity that conforms to the clarified, OpenOffice.org-2.0 service concept, while we use "old-style service" to denote an entity that only conforms to the historical, more vague concept. To make matters even more complicated, the term “service” is often used with still different meanings in contexts outside UNO.

Although technically there should no longer be any need for old-style services, the OpenOffice.org API still uses them extensively to remain backwards compatible. Therefore, be prepared to encounter uses of both service concepts in parallel when working with the OpenOffice.org API.

A new-style service is of the form

  module com { module sun { module star { module bridge {   
      service UnoUrlResolver: XUnoUrlResolver;
  }; }; }; };

and specifies that objects that support a certain interface (for example, com.sun.star.bridge.XUnoUrlResolver) will be available under a certain service name (e.g., "com.sun.star.bridge.UnoUrlResolver") at a component context’s service manager. (Formally, new-style services are called “single-interface–based services.”)

The various UNO language bindings offer special constructs to easily obtain instances of such new-style services, given a suitable component context; see Java Language Binding and C++ Language Binding.

An old-style service (formally called an “accumulation-based service”) is of the form

  module com { module sun { module star { module frame { service Desktop {
      service Frame;
      interface XDesktop;
      interface XComponentLoader;
      interface com::sun::star::document::XEventBroadcaster;
  };
  }; }; }; };

and is used to specify any of the following:

  • The general contract is that, if an object is documented to support a certain old-style service, then you can expect that object to support all interfaces exported by the service itself and any inherited services. For example, the method <idlml>com.sun.star.frame.XFrames:queryFrames</idlml> returns a sequence of objects that should all support the old-style service com.sun.star.frame.Frame, and thus all the interfaces exported by Frame.
  • Additionally, an old-style service may specify one or more properties, as in
  module com { module sun { module star { module frame { service Frame {   
      interface com::sun::star::frame::XFrame;
      interface com::sun::star::frame::XDispatchProvider;
      // ...
      [property] string Title;
      [property, optional] XDispatchRecorderSupplier RecorderSupplier;
      // ...
  };
  }; }; }; };
Properties, which are explained in detail in the following section, are similar to interface attributes, in that they describe additional features of an object. The main difference is that interface attributes can be accessed directly, while the properties of an old-style service are typically accessed via generic interfaces like com.sun.star.beans.XPropertySet. Often, interface attributes are used to represent integral features of an object, while properties represent additional, more volatile features.
  • Some old-style services are intended to be available at a component context’s service manager. For example, the service com.sun.star.frame.Desktop can be instantiated at a component context’s service manager under its service name "com.sun.star.frame.Desktop". (The problem is that you cannot tell whether a given old-style service is intended to be available at a component context; using a new-style service instead makes that intent explicit.)
  • Yet other old-style services only list properties, and do not export any interfaces at all. Instead of specifying the interfaces supported by certain objects, as the other kinds of old-style services do, such services are used to document a set of related properties. For example, the service com.sun.star.document.MediaDescriptor lists all the properties that can be passed to <idlml>com.sun.star.frame.XComponentLoader:loadComponentFromURL</idlml>.

A property is a feature of an object which is typically not considered an integral or structural part of the object and therefore is handled through generic getPropertyValue()/setPropertyValue() methods instead of specialized get methods, such as getPrinter(). Old-style services offer a special syntax to list all the properties of an object. An object containing properties only has to support the com.sun.star.beans.XPropertySet interface to be prepared to handle all kinds of properties. Typical examples are properties for character or paragraph formatting. With properties, you can set multiple features of an object through a single call to setPropertyValues(), which greatly improves the remote performance. For instance, paragraphs support the setPropertyValues() method through their com.sun.star.beans.XMultiPropertySet interface.

Content on this page is licensed under the Public Documentation License (PDL).
Personal tools
In other languages