Difference between revisions of "Documentation/DevGuide/WritingUNO/Defining a Service"

Revision as of 22:50, 5 October 2008

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 OpenOffice.org 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;

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 instructions, and it can identify properties supported by the service through [property] instructions.

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 instruction using a semicolon.

service instructions 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.

Template:Documentation/Note

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;
 
  };

Template:Documentation/Note

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

@@ Line 8: / Line 8: @@
 [[zh:Zh/Documentation/DevGuide/WritingUNO/Defining a Service]]
 {{DISPLAYTITLE:Defining a Service}}
-UNOIDL Services combine interfaces and properties to specify a certain functionality. In addition, old-style services can include other services. For these purposes, <code>interface</code>, <code>property</code> and <code>service</code> declarations are used within service specifications. Usually services are the basis for an object implementation, although there are old-style services in the {{PRODUCTNAME}} API that only serve as foundation or addition to other services, but are not meant to be implemented by themselves.
+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, <code>interface</code>, <code>property</code> and <code>service</code> declarations are used within service specifications. Usually, services are the basis for an object implementation, although there are old-style services in the {{PRODUCTNAME}} API that only serve as a foundation for, or addition to, other services, but are not meant to be implemented by themselves.
 <!--fn The services [IDL:com.sun.star.text.BaseFrame] or [IDL:com.sun.star.style.CharacterProperties] are part of other services, but are not implemented as such anywhere.-->
-We are ready to assemble our <code>ImageShrink</code> service. Our service will read image files from a source directory and write shrinked versions of the found images to a destination directory. Our <code>XImageShrink</code> interface offers the needed capabilities, together with the interface <idl>com.sun.star.document.XFilter</idl> that supports two methods:
+We are ready to assemble our <code>ImageShrink</code> service. Our service will read image files from a source directory and write shrunk versions of the found images to a destination directory. Our <code>XImageShrink</code> interface offers the needed capabilities, together with the interface <idl>com.sun.star.document.XFilter</idl> that supports two methods:
 <source lang="idl">
    boolean filter( [in] sequence< com::sun::star::beans::PropertyValue > aDescriptor)
@@ Line 34: / Line 34: @@
    #endif
 </source>
-The following code shows the <code>ImageShrink</code> service specification:
+The <code>ImageShrink</code> service specification is provided by the following code:
 <!--[SOURCE:Components/Thumbs/org/openoffice/test/ImageShrink.idl]-->
 <source lang="idl">
@@ Line 49: / Line 49: @@
    #endif
 </source>
-Define a service using the <code>service</code> declaration. A new-style service opens with the keyword <code>service</code>, followed by a service name, a colon, the name of the interface supported by the service, and is terminated by a semicolon. The first letter of a service name should be an upper-case letter.
+A new-style service is defined using the <code>service</code> declaration. A new-style service opens with the keyword <code>service</code>, 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.
-An old-style service is much more complex. It opens with the keyword <code>service</code>, followed by a service name and the service body in braces. The <code>service</code> instruction concludes with a semicolon. The body of a service can reference interfaces and services using <code>interface</code> and <code>service</code> instructions, and it can identify properties supported by the service through <code>[property]</code> instructions.
+<source lang="idl">
+  service ServiceName: XInterface;
+</source>
+An old-style service is much more complex. It opens with the keyword <code>service</code>, 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 <code>interface</code> and <code>service</code> instructions, and it can identify properties supported by the service through <code>[property]</code> instructions.
 * <code>Interface</code> keywords followed by interface names in a service body indicates that the service supports these interfaces. By default, the <code>interface</code> forces the developer to implement this interface. To suggest an interface for a certain service, prepend an [optional] flag in front of the keyword <code>interface</code>. 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 <code>interface</code> instruction using a semicolon.

Difference between revisions of "Documentation/DevGuide/WritingUNO/Defining a Service"

Revision as of 22:50, 5 October 2008

Views

Personal tools

Navigation

Search

Tools

In other languages