Defining a Service

From Apache OpenOffice Wiki
Jump to: navigation, search



The new-style UNOIDL services combine interfaces and properties to specify a certain functionality. In addition, old-style services can include other services. For these purposes, interface, property and service declarations are used within service specifications. Usually, services are the basis for an object implementation, although there are old-style services in the Apache OpenOffice API that only serve as a foundation for, or addition to, other services, but are not meant to be implemented by themselves.

We are ready to assemble our ImageShrink service. Our service will read image files from a source directory and write shrunk versions of the found images to a destination directory. Our XImageShrink interface offers the needed capabilities, together with the interface com.sun.star.document.XFilter that supports two methods:

  boolean filter( [in] sequence< com::sun::star::beans::PropertyValue > aDescriptor)
  void cancel()

A new-style service can only encompass one interface, so we need to combine XImageShrink and XFilter in a single, multiple-inheritance interface:

  #ifndef __org_openoffice_test_XImageShrinkFilter_idl__
  #define __org_openoffice_test_XImageShrinkFilter_idl__
  #include <com/sun/star/document/XFilter.idl>
  #include <org/openoffice/test/XImageShrink.idl>
 
  module org { module openoffice { module test {
 
  interface XImageShrinkFilter {
      interface XImageShrink;
      interface com::sun::star::document::XFilter;
  };
 
  }; }; };
 
  #endif

The ImageShrink service specification is provided by the following code:

  #ifndef __org_openoffice_test_ImageShrink_idl__
  #define __org_openoffice_test_ImageShrink_idl__
  #include <org/openoffice/test/XImageShrinkFilter.idl>
 
  module org { module openoffice { module test {
 
  service ImageShrink: XImageShrinkFilter;
 
  }; }; };
 
  #endif

A new-style service is defined using the service declaration. A new-style service opens with the keyword service, followed by a service name, a colon, the name of the interface supported by the service, and, finally, a semicolon. The first letter of the service name should be upper-case.

  service ServiceName: XInterface;

Old-style Services

An old-style service is much more complex. It opens with the keyword service, followed by a service name and the service body in braces, and, finally, a semicolon. The body of a service can reference interfaces and services using interface and service declarations, and it can identify properties supported by the service through [property] declarations.

  • Interface keywords followed by interface names in a service body indicates that the service supports these interfaces. By default, the interface forces the developer to implement this interface. To suggest an interface for a certain service, prepend an [optional] flag in front of the keyword interface. This weakens the specification to a permission. An optional interface can be implemented. Use one interface declaration for each supported interface or give a comma-separated list of interfaces to be exported by a service. You must terminate the interface declaration statement using a semicolon.
  • service declaration statements in a service body include other services. The effect is that all interface and property definitions of the other services become part of the current service. A service reference can be optional using the [optional] flag in front of the service keyword. Use one declaration per service or a comma-separated list for the services to reference. The service declaration ends with a semicolon.
  • [property] declaration s describe qualities of a service that can be reached from the outside under a particular name and type. As opposed to interface attributes, these qualities are not considered to be a structural part of a service. Refer to the section Properties in the chapter Professional UNO to determine when to use interface attributes and when to introduce properties in a service . The property keyword must be enclosed in square brackets, and continue with a known type and a property identifier. Just like a service and an interface, make a property non-mandatory writing [property, optional]. Besides optional,there is a number of other flags to use with properties. The following table shows all flags that can be used with [property]:
Property Flags Description
optional Property is non-mandatory.
readonly The value of the property cannot be changed using the setter methods for properties, such as setPropertyValue(string name).
bound Changes of values are broadcast to com.sun.star.beans.XPropertyChangeListeners registered with the component.
constrained The component must broadcast an event before a value changes, listeners can veto.
maybeambiguous The value cannot be determined in some cases, for example, in multiple selections.
maybedefault The value might come from a style or the application environment instead of from the object itself.
maybevoid The property type determines the range of possible values, but sometimes there may be situations where there is no information available. Instead of defining special values for each type denoting that there are no meaningful values, the UNO type void can be used. Its meaning is comparable to null in relational databases.
removable The property is removable. If a property is made removable, you must check for the existence of a property using hasPropertyByName() at the interface com.sun.star.beans.XPropertySetInfo and consider providing the capability to add or remove properties using com.sun.star.beans.XPropertyContainer.
transient The property will not be stored if the object is serialized (made persistent).
  • Several properties of the same type can be listed in one property declaration. Remember to add a semicolon at the end. Implement the interface com.sun.star.beans.XPropertySet when putting properties in your service, otherwise the properties specified will not work for others using the component.
Documentation note.png Some old-style services, which specify no interfaces at all, only properties, are used as a sequence of com.sun.star.beans.PropertyValue in Apache OpenOffice, for example, com.sun.star.document.MediaDescriptor.

The following UNOIDL snippet shows the service, the interfaces and the properties supported by the old-style service com.sun.star.text.TextDocument as defined in UNOIDL. Note the optional interfaces and the optional and read-only properties.

  service TextDocument
  {
  service com::sun::star::document::OfficeDocument;
 
  interface com::sun::star::text::XTextDocument;
  interface com::sun::star::util::XSearchable;
  interface com::sun::star::util::XRefreshable;
  interface com::sun::star::util::XNumberFormatsSupplier;
 
  [optional] interface com::sun::star::text::XFootnotesSupplier;
  [optional] interface com::sun::star::text::XEndnotesSupplier;
  [optional] interface com::sun::star::util::XReplaceable;
  [optional] interface com::sun::star::text::XPagePrintable;
  [optional] interface com::sun::star::text::XReferenceMarksSupplier;
  [optional] interface com::sun::star::text::XLineNumberingSupplier;
  [optional] interface com::sun::star::text::XChapterNumberingSupplier;
  [optional] interface com::sun::star::beans::XPropertySet;
  [optional] interface com::sun::star::text::XTextGraphicObjectsSupplier;
  [optional] interface com::sun::star::text::XTextEmbeddedObjectsSupplier;
  [optional] interface com::sun::star::text::XTextTablesSupplier;
  [optional] interface com::sun::star::style::XStyleFamiliesSupplier;
 
  [optional, property] com::sun::star::lang::Locale CharLocale;
  [optional, property] string WordSeparator;
 
  [optional, readonly, property] long CharacterCount;
  [optional, readonly, property] long ParagraphCount;
  [optional, readonly, property] long WordCount;
 
  };
Documentation note.png You might encounter two additional keywords in old-style service bodies. These keywords are observed and needs.

The keyword observes can stand in front of interface references and means that the given interfaces must be "observed". Since the observes concept is disapproved of, no further explanation is provided.

If a service references another service using the keyword needs in front of the reference, then this service depends on the availability of the needed service at runtime. Services should not use needs as it is considered too implementation specific.

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