Revision as of 14:04, 26 May 2006

For an introduction, you can read tutorial.

Services and Interfaces

Introduction

See tutorial (in pdf) chapter 2 In OpenOffice API, a "service" is an abstract concept providing certain interfaces and properties/attributes. As Developer's Guide states : “Properties are data in an object that are provided by name over a generic interface for property access, that contains getPropertyValue() and setPropertyValue() access methods.”. It would be better to distinguish between attribute and property. A service has a collection of properties and an interface is a collection of methods that provide a means to change properties.

Danny Brewer's rules

Services are similar to objects in java.

1. A service can inherit from zero or one other service. (which each service can recursively follow these rules.) 2. A service can include zero or more services. (which each service can recursively follow these rules.) 3. A service can export (implement) interfaces. 4. A service can have properties.

5. An interface can inherit from zero or one other interface. (which each interface can recursively follow these rules.) 6. An interface can include from zero or more interfaces. (which each interface can recursively apply these rules.) 7. An interface can implement methods. 8. An interface is always named with an X.

From these rules you can deduce that methods are ALWAYS found in interfaces, and properties are ALWAYS found in services.

IDL specification

Interfaces are specified using an Interface definition language (IDL). UNO uses UNO-IDL as the interface definition language. The Interface Definition Language (IDL) is a descriptive language (not a programming language) to describe the interfaces being implemented by the objects. Within IDL, you define the name of the interface, the names of each of the attributes and methods, and so forth. Once you've created the IDL file, you can use an IDL compiler to generate the header files in the C++ programming language. The way to specify simple modules with IDL is so straightforward that we choose to give only examples at first.

Specifying an interface

We choose as an example, the interface XdrivingDirection (not in OOo):

// IDL
interface XdrivingDirection
	{
		void turnLeft();
		void turnRight();
	};

Specifying a service

Example above is still used, here is the corresponding IDL specification :

// IDL
interface XdrivingDirection
	{
		void turnLeft();
		void turnRight();
	};
interface XaccelerationControl
	{
		void speedUp();
		void slowDown();
	};
service car
	{
		// exported interfaces:
		interface XdrivingDirection;
		interface XaccelerationControl;
		[attribute] float speed; 
		[attribute] float angle;
	};

We see a float type and we would use other IDL types later.

Specifying a module

Now, the same example would give this IDL specification :

// IDL
module my_module
	{
	interface Xsomething
		{
			void methodone();
		};
	service my_service1
		{
			// exported interfaces:
			interface Xsomething;
		};
	interface XsomethingElse
		{
			void methodTwo();
			void methodThree();
		};
	service my_service2
		{
			// exported interfaces:
			interface XsomethingElse;
		};
};

Further with IDL

The IDL's types are :

Methods can have arguments. Each argument in the argument list must begin with one of the direction flags [ in ] , [ out ] or [ inout ] before a known type and identifier for the argument is given. We give an example that we will often encounter in this document : the counter example

An interface can be derived from a base interface. A derived interface can declare its own attributes and methods. Attributes and methods cannot be redefined in the derived interface. An example of interface inheritance :

//IDL
interface animal {
	attribute long age;
};
interface dog : animal {
	attribute short leg;
}

Multiple inheritance is also possible :

// IDL
interface dog : animal, friend {

Inheritance in service is presented in the next chapter.

In the OOo object terminology there is a difference between attribute and property. The only difference is how to access them. Properties are accessed with setPropertyValue(PropertyName,Any) whereas attributes are accessed with set/get(AttributeName) methods. We have already encounter properties manipulation when examining shapes.

Gathering UNO information with IDL files

There are several ways to find information on UNO.

One way is to use OooBasic and Bernard Marcelly's Xray tool (available here). Problem : OooBasic doesn't show exact methods and properties.

An other way is to use web service at : general WEB Index

We have provided examples in previous chapters (particularly programming OOoWriter in C++) and then normally reader has skills on the subject.