Difference between revisions of "Documentation/DevGuide/FirstSteps/Objects, Interfaces, and Services"

From Apache OpenOffice Wiki
Jump to: navigation, search
(Fix some typos where "service" wasn't spaced from the succeeding word)
(16 intermediate revisions by 7 users not shown)
Line 5: Line 5:
 
|NextPage=Documentation/DevGuide/FirstSteps/Using Services
 
|NextPage=Documentation/DevGuide/FirstSteps/Using Services
 
}}
 
}}
 +
{{Documentation/DevGuideLanguages|Documentation/DevGuide/FirstSteps/{{SUBPAGENAME}}}}
 
{{DISPLAYTITLE:Objects, Interfaces, and Services}}
 
{{DISPLAYTITLE:Objects, Interfaces, and Services}}
 
===Objects===
 
===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 what methods and attributes an object offers is specified by the set of interfaces it supports.
+
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===
 
===Interfaces===
Line 15: Line 16:
  
 
   <source lang="idl">
 
   <source lang="idl">
   module com { module sun { module star { module resource { interfaceXResourceBundle: com::sun::star::container::XNameAccess {
+
   module com { module sun { module star { module resource { interface XResourceBundle: com::sun::star::container::XNameAccess {
 
       [attribute] XResourceBundle Parent;
 
       [attribute] XResourceBundle Parent;
 
       com::sun::star::lang::Locale getLocale();
 
       com::sun::star::lang::Locale getLocale();
Line 23: Line 24:
 
   </source>
 
   </source>
  
To allow for reuse of such interface specifications, an interface can inherit one or more other interfaces (as, for example, <idls>com.sun.star.resource.XResourceBundle</idls> inherits all the attributes and methods of <idl>com.sun.star.container.XNameAccess</idl>). Multiple inheritance, the ability to inherit more than one interface, is new in {{PRODUCTNAME}} {{OOo2.x}}.
+
To allow for reuse of such interface specifications, an interface can inherit one or more other interfaces (as, for example, <idls>com.sun.star.resource.XResourceBundle</idls> inherits all the attributes and methods of <idl>com.sun.star.container.XNameAccess</idl>). Multiple inheritance, the ability to inherit more than one interface, was introduced in {{PRODUCTNAME}} {{OOo2.x}}.
  
 
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.
 
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.
Line 32: Line 33:
 
Historically, the term “service” has been used with an unclear meaning in UNO. Starting with {{PRODUCTNAME}} {{OOo2.x}}, 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, {{PRODUCTNAME}}-{{OOo2.x}} 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.
 
Historically, the term “service” has been used with an unclear meaning in UNO. Starting with {{PRODUCTNAME}} {{OOo2.x}}, 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, {{PRODUCTNAME}}-{{OOo2.x}} 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 {{PRODUCTNAME}} 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 {{PRODUCTNAME}} API.
+
Although technically there should no longer be any need for old-style services, the {{PRODUCTNAME}} 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 {{PRODUCTNAME}} API.
  
 
A ''new-style service'' is of the form
 
A ''new-style service'' is of the form
Line 38: Line 39:
 
   <source lang="idl">
 
   <source lang="idl">
 
   module com { module sun { module star { module bridge {   
 
   module com { module sun { module star { module bridge {   
       serviceUnoUrlResolver: XUnoUrlResolver;
+
       service UnoUrlResolver: XUnoUrlResolver;
 
   }; }; }; };
 
   }; }; }; };
 
   </source>
 
   </source>
  
and specifies that objects that support a certain interface (for example, <idl>com.sun.star.bridge.XUnoUrlResolver</idl>) 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.”)
+
and specifies that objects that support a certain interface (for example, <idl>com.sun.star.bridge.XUnoUrlResolver</idl>) 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 [[Documentation/DevGuide/ProUNO/Java/Java Language Binding|Java Language Binding]] and [[Documentation/DevGuide/ProUNO/C++/C++ Language Binding|C++ Language Binding]].
 
The various UNO language bindings offer special constructs to easily obtain instances of such new-style services, given a suitable component context; see [[Documentation/DevGuide/ProUNO/Java/Java Language Binding|Java Language Binding]] and [[Documentation/DevGuide/ProUNO/C++/C++ Language Binding|C++ Language Binding]].
Line 49: Line 50:
  
 
   <source lang="idl">
 
   <source lang="idl">
   module com { module sun { module star { module frame {serviceDesktop {
+
   module com { module sun { module star { module frame { service Desktop {
 
       service Frame;
 
       service Frame;
 
       interface XDesktop;
 
       interface XDesktop;
Line 60: Line 61:
 
and is used to specify any of the following:
 
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 <idlm>com.sun.star.frame.XFrames:queryFrames<idlm> returns a sequence of objects that should all support the old-style service <idl>com.sun.star.frame.Frame</idl>, and thus all the interfaces exported by <idls>com.sun.star.frame.Frame</idls>.
+
* 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 <idl>com.sun.star.frame.Frame</idl>, and thus all the interfaces exported by <idls>com.sun.star.frame.Frame</idls>.
 
* Additionally, an old-style service may specify one or more properties, as in
 
* Additionally, an old-style service may specify one or more properties, as in
  
 
   <source lang="idl">
 
   <source lang="idl">
   module com { module sun { module star { module frame {service Frame {   
+
   module com { module sun { module star { module frame { service Frame {   
 
       interface com::sun::star::frame::XFrame;
 
       interface com::sun::star::frame::XFrame;
 
       interface com::sun::star::frame::XDispatchProvider;
 
       interface com::sun::star::frame::XDispatchProvider;
Line 81: Line 82:
 
* Other old-style services are designed as generic super-services that are inherited by other services. For example, the service <idl>com.sun.star.document.OfficeDocument</idl> serves as a generic base for all different sorts of concrete document services, like <idl>com.sun.star.text.TextDocument</idl> and <idl>com.sun.star.drawing.DrawingDocument</idl>. (Multiple-inheritance interfaces are now the preferred mechanism to express such generic base services.)
 
* Other old-style services are designed as generic super-services that are inherited by other services. For example, the service <idl>com.sun.star.document.OfficeDocument</idl> serves as a generic base for all different sorts of concrete document services, like <idl>com.sun.star.text.TextDocument</idl> and <idl>com.sun.star.drawing.DrawingDocument</idl>. (Multiple-inheritance interfaces are now the preferred mechanism to express such generic base services.)
  
* 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 <idl>com.sun.star.document.MediaDescriptor</idl> lists all the properties that can be passed to <idlm>com.sun.star.frame.XComponentLoader:loadComponentFromURL</idlm>.
+
* 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 <idl>com.sun.star.document.MediaDescriptor</idl> 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 <code>getPropertyValue()</code>/<code>setPropertyValue()</code> methods instead of specialized get methods, such as <code>getPrinter()</code>. Old-style services offer a special syntax to list all the properties of an object. An object containing properties only has to support the <idl>com.sun.star.beans.XPropertySet</idl> 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 <code>setPropertyValues()</code>, which greatly improves the remote performance. For instance, paragraphs support the <code>setPropertyValues()</code> method through their <idl>com.sun.star.beans.XMultiPropertySet</idl> interface.
 
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 <code>getPropertyValue()</code>/<code>setPropertyValue()</code> methods instead of specialized get methods, such as <code>getPrinter()</code>. Old-style services offer a special syntax to list all the properties of an object. An object containing properties only has to support the <idl>com.sun.star.beans.XPropertySet</idl> 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 <code>setPropertyValues()</code>, which greatly improves the remote performance. For instance, paragraphs support the <code>setPropertyValues()</code> method through their <idl>com.sun.star.beans.XMultiPropertySet</idl> interface.
  
 
{{PDL1}}
 
{{PDL1}}
[[Category: First Steps]]
+
 
 +
[[Category:Documentation/Developer's Guide/First Steps]]

Revision as of 16:27, 20 December 2015



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