Interfaces

From Apache OpenOffice Wiki
< Documentation‎ | DevGuide
Revision as of 19:34, 5 October 2008 by Cking (Talk | contribs)

Jump to: navigation, search


Communication between UNO objects is based on object interfaces. Interfaces can be seen from the outside or the inside of an object.

From the outside of an object, an interface provides a functionality or special aspect of the object. Interfaces provide access to objects by publishing a set of operations that cover a certain aspect of an object without telling anything about its internals.

The concept of interfaces is quite natural and frequently used in everyday life. Interfaces allow the creation of things that fit in with each other without knowing internal details about them. A power plug that fits into a standard socket or a one-size-fits-all working glove are simple examples. They all work by standardizing the minimal conditions that must be met to make things work together.

A more advanced example would be the "remote control aspect" of a simple TV system. One possible feature of a TV system is a remote control. The remote control functions can be described by an XPower and an XChannel interface. The illustration below shows a RemoteControl object with these interfaces:

RemoteControl service

The XPower interface has the functions turnOn() and turnOff() to control the power and the XChannel interface has the functions select(), next(), previous() to control the current channel. The user of these interfaces does not care if he uses an original remote control that came with a TV set or a universal remote control as long as it carries out these functions. The user is only dissatisfied if some of the functions promised by the interface do not work with a remote control.

From the inside of an object, or from the perspective of someone who implements a UNO object, interfaces are abstract specifications. The abstract specification of all the interfaces in the OpenOffice.org API has the advantage that user and implementer can enter into a contract, agreeing to adhere to the interface specification. A program that strictly uses the OpenOffice.org API according to the specification will always work, while an implementer can do whatever he wants with his objects, as long as he serves the contract.

UNO uses the interface type to describe such aspects of UNO objects. By convention, all interface names start with the letter X to distinguish them from other types. All interface types must inherit the com.sun.star.uno.XInterface root interface, either directly or in the inheritance hierarchy. XInterface is explained in Using UNO Interfaces. The interface types define methods (sometimes also called operations) to provide access to the specified UNO objects.

Interfaces allow access to the data inside an object through dedicated methods (member functions) which encapsulate the data of the object. The methods always have a parameter list and a return value, and they may define exceptions for smart error handling.

The exception concept in the OpenOffice.org API is comparable with the exception concepts known from Java or C++. All operations can raise RuntimeException without explicit specification, but all other exceptions must be specified. UNO exceptions are explained in the section Exception Handling.

Consider the following two examples for interface definitions in UNOIDL (UNO Interface Definition Language) notation. UNOIDL interfaces resemble Java interfaces, and methods look similar to Java method signatures. However, note the flags in square brackets in the following example:

// base interface for all UNO interfaces 
  interface XInterface 
  { 
          any queryInterface( [in] type aType ); 
          [oneway] void acquire(); 
          [oneway] void release(); 
 
  };  
 
  // fragment of the Interface com.sun.star.io.XInputStream 
 
  interface XInputStream: com::sun::star::uno::XInterface 
  {  
      long readBytes( [out] sequence<byte> aData, 
                      [in] long nBytesToRead ) 
                  raises( com::sun::star::io::NotConnectedException, 
                          com::sun::star::io::BufferSizeExceededException, 
                          com::sun::star::io::IOException); 
      ... 
  };

The [oneway] flag indicates that an operation can be executed asynchronously if the underlying method invocation system does support this feature. For example, a UNO Remote Protocol (URP) bridge is a system that supports oneway calls.

Documentation caution.png Although there are no general problems with the specification and the implementation of the UNO oneway feature, there are several API remote usage scenarios where oneway calls cause deadlocks in OpenOffice.org. Therefore, do not introduce new oneway methods with new OpenOffice.org UNO APIs.

There are also parameter flags. Each parameter definition begins with one of the direction flags in, out, or inout to specify the use of the parameter:

  • in specifies that the parameter will be used as an input parameter only
  • out specifies that the parameter will be used as an output parameter only
  • inout specifies that the parameter will be used as an input and output parameter

These parameter flags do not appear in the API reference. The fact that a parameter is an [out] or [inout] parameter is explained in the method details.

Interfaces consisting of methods form the basis for service specifications.

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