Difference between revisions of "Documentation/DevGuide/WritingUNO/Defining a Service"
m (Added a line showing the new-style service: "service ServiceName: XInterface;") |
|||
(8 intermediate revisions by 5 users not shown) | |||
Line 6: | Line 6: | ||
|NextPage=Documentation/DevGuide/WritingUNO/Defining a Sequence | |NextPage=Documentation/DevGuide/WritingUNO/Defining a Sequence | ||
}} | }} | ||
− | + | {{Documentation/DevGuideLanguages|Documentation/DevGuide/WritingUNO/{{SUBPAGENAME}}}} | |
{{DISPLAYTITLE:Defining a Service}} | {{DISPLAYTITLE:Defining a Service}} | ||
− | The new-style UNOIDL | + | 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 {{AOo}} 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.--> | <!--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 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: | 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: | ||
− | < | + | <syntaxhighlight lang="idl"> |
boolean filter( [in] sequence< com::sun::star::beans::PropertyValue > aDescriptor) | boolean filter( [in] sequence< com::sun::star::beans::PropertyValue > aDescriptor) | ||
void cancel() | void cancel() | ||
− | </ | + | </syntaxhighlight> |
A new-style service can only encompass one interface, so we need to combine <code>XImageShrink</code> and <code>XFilter</code> in a single, multiple-inheritance interface: | A new-style service can only encompass one interface, so we need to combine <code>XImageShrink</code> and <code>XFilter</code> in a single, multiple-inheritance interface: | ||
− | < | + | <syntaxhighlight lang="idl"> |
#ifndef __org_openoffice_test_XImageShrinkFilter_idl__ | #ifndef __org_openoffice_test_XImageShrinkFilter_idl__ | ||
#define __org_openoffice_test_XImageShrinkFilter_idl__ | #define __org_openoffice_test_XImageShrinkFilter_idl__ | ||
Line 33: | Line 33: | ||
#endif | #endif | ||
− | </ | + | </syntaxhighlight> |
The <code>ImageShrink</code> service specification is provided by the following code: | The <code>ImageShrink</code> service specification is provided by the following code: | ||
<!--[SOURCE:Components/Thumbs/org/openoffice/test/ImageShrink.idl]--> | <!--[SOURCE:Components/Thumbs/org/openoffice/test/ImageShrink.idl]--> | ||
− | < | + | <syntaxhighlight lang="idl"> |
#ifndef __org_openoffice_test_ImageShrink_idl__ | #ifndef __org_openoffice_test_ImageShrink_idl__ | ||
#define __org_openoffice_test_ImageShrink_idl__ | #define __org_openoffice_test_ImageShrink_idl__ | ||
Line 48: | Line 48: | ||
#endif | #endif | ||
− | </ | + | </syntaxhighlight> |
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. | 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. | ||
− | < | + | <syntaxhighlight lang="idl"> |
service ServiceName: XInterface; | service ServiceName: XInterface; | ||
− | </ | + | </syntaxhighlight> |
− | + | == Old-style Services == | |
− | + | 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> declarations, and it can identify properties supported by the service through <code>[property]</code> declarations. | |
− | * <code>service</code> | + | * <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> declaration statement using a semicolon. |
+ | |||
+ | * <code>service</code> 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 <code>[optional]</code> flag in front of the <code>service</code> keyword. Use one declaration per service or a comma-separated list for the services to reference. The <code>service</code> declaration ends with a semicolon. | ||
* <code>[property]</code> 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 [[Documentation/DevGuide/ProUNO/Properties|Properties]] in the chapter [[Documentation/DevGuide/ProUNO/Professional UNO|Professional UNO]] to determine when to use interface attributes and when to introduce properties in a service . The <code>property</code> 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 <code>[property, optional]</code>. Besides optional,there is a number of other flags to use with properties. The following table shows all flags that can be used with <code>[property]</code>: | * <code>[property]</code> 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 [[Documentation/DevGuide/ProUNO/Properties|Properties]] in the chapter [[Documentation/DevGuide/ProUNO/Professional UNO|Professional UNO]] to determine when to use interface attributes and when to introduce properties in a service . The <code>property</code> 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 <code>[property, optional]</code>. Besides optional,there is a number of other flags to use with properties. The following table shows all flags that can be used with <code>[property]</code>: | ||
Line 98: | Line 100: | ||
* Several properties of the same type can be listed in one <code>property</code> declaration. Remember to add a semicolon at the end. Implement the interface <idl>com.sun.star.beans.XPropertySet</idl> when putting properties in your service, otherwise the properties specified will not work for others using the component. | * Several properties of the same type can be listed in one <code>property</code> declaration. Remember to add a semicolon at the end. Implement the interface <idl>com.sun.star.beans.XPropertySet</idl> when putting properties in your service, otherwise the properties specified will not work for others using the component. | ||
− | {{ | + | {{Note|Some old-style services, which specify no interfaces at all, only properties, are used as a sequence of <idl>com.sun.star.beans.PropertyValue</idl> in {{AOo}}, for example, <idl>com.sun.star.document.MediaDescriptor</idl>.}} |
The following UNOIDL snippet shows the service, the interfaces and the properties supported by the old-style service <idl>com.sun.star.text.TextDocument</idl> as defined in UNOIDL. Note the optional interfaces and the optional and read-only properties. | The following UNOIDL snippet shows the service, the interfaces and the properties supported by the old-style service <idl>com.sun.star.text.TextDocument</idl> as defined in UNOIDL. Note the optional interfaces and the optional and read-only properties. | ||
− | < | + | <syntaxhighlight lang="idl"> |
service TextDocument | service TextDocument | ||
{ | { | ||
Line 132: | Line 134: | ||
}; | }; | ||
− | </ | + | </syntaxhighlight> |
− | {{ | + | {{Note|You might encounter two additional keywords in old-style service bodies. These keywords are <tt>observed</tt> and <tt>needs</tt>. |
+ | |||
+ | The keyword <tt>observes</tt> can stand in front of interface references and means that the given interfaces must be "observed". Since the <tt>observes</tt> concept is disapproved of, no further explanation is provided. | ||
If a service references another service using the keyword <tt>needs</tt> 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.}} | If a service references another service using the keyword <tt>needs</tt> 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.}} |
Latest revision as of 16:19, 23 December 2020
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, theinterface
forces the developer to implement this interface. To suggest an interface for a certain service, prepend an [optional] flag in front of the keywordinterface
. 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 theinterface
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 theservice
keyword. Use one declaration per service or a comma-separated list for the services to reference. Theservice
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 . Theproperty
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.
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; };
Content on this page is licensed under the Public Documentation License (PDL). |