2021-05-30

61: Create Any UNO Component in Java

<The previous article in this series | The table of contents of this series | The next article in this series>
For example, a listener, a Swing GUI component, a hard-to-be-implemented-in-a-macro-language function component, etc.

Topics


About: UNO (Universal Network Objects)
About: LibreOffice
About: Apache OpenOffice
About: the Java programming language

The table of contents of this article

Starting Context

Target Context


  • The reader will know how to create his or her own UNO component in Java.

Orientation


There is an article on how to create and register any UNO Interface and generate the mapping images.

There is an article on how to create any UNO component in C++.

Main Body

Stage Direction
Here are Hypothesizer 7, Objector 61A, and Objector 61B in front of a computer.

1: Motivation


Hypothesizer 7
 The primal motivation to create any UNO component is to let an instance of it (a UNO object) be handled from another programming language environment.

Objector 61A
 Oh? You sound so confident! Is that really the only motivation?

Hypothesizer 7
 I said that it was the "primal" motivation, sir.

Objector 61A
 Why shouldn't I create a UNO component just because I love centipedes?

Hypothesizer 7
 I am talking about well-founded motivations.

Objector 61A
 What's wrong with centipedes?

Hypothesizer 7
 I did not say that centipedes were "wrong"; I said that your motivation was not well-founded.

Objector 61B
 They are wrong; too many legs.

Hypothesizer 7
 They have their reasons, probably, madam.

Objector 61B
 But that synchronized movement of the legs! Creepy!

Hypothesizer 7
 They are beings that are supposed to creep.

Objector 61B
 Anyway, I don't want to "let an instance of it be handled from another programming language environment"; I just want to create a listener.

Hypothesizer 7
 Madam, the listener class has to be a UNO component because any instance of it is supposed to be able to be handled from another programming language environment.

Objector 61B
 I don't have any another programming language environment but a single Java environment . . .

Hypothesizer 7
 Usually, your Java program is attached to and handles a LibreOffice or Apache OpenOffice instance, which is basically a C++ environment.

Objector 61B
 So?

Hypothesizer 7
 Usually, the broadcaster is in the C++ environment, and the broadcaster handles the listener.

Objector 61B
 What is "the broadcaster"?

Hypothesizer 7
 The broadcaster is the object into which you have registered the listener.

Objector 61B
 Have I?

Hypothesizer 7
 . . . You have to.

Objector 61A
 But the broadcaster may be in the Java environment, may it not?

Hypothesizer 7
 There may be such cases, but the broadcaster requires the listener to be a UNO object in order for the listener to be allowed to be from another programming language environment, which is what I mean by "primal motivation".

Objector 61A
 "UNO object"? Do you mean UNO component?

Hypothesizer 7
 I mean UNO object; please understand how I use terms rigorously, although the official document uses terms, especially "component", wantonly, such that I cannot identify what each appearance of "component" means.

Objector 61B
 Anyway, only listeners are ones I want as UNO components, aren't they?

Hypothesizer 7
 I do not know what you want, but a typical case is that a Java UNO component implements a function that cannot be implemented by your macro language.

Objector 61B
 Why can't it be implemented?

Hypothesizer 7
 As Basic is very poor, it cannot implement a lot of kinds of things, for example, network handling, multi threading, etc, and it can implement some things like XML handling and JSON handling if you dare, but it will be very tiresome because it does not have corresponding handy libraries.

And a useful option is to create GUI components in Java Swing.

Objector 61B
 I can create GUI components in Basic.

Hypothesizer 7
 Do you mean Basic dialog boxes?

Objector 61B
 Yes.

Hypothesizer 7
 They are poor, I have to say.

Objector 61B
 I don't say they are rich.

Objector 61A
 Can't I use Python GUI, like tkinter?

Hypothesizer 7
 I guess not, in Linux.

Objector 61A
 Then, OK in Windows?

Hypothesizer 7
 Probably.

Objector 61A
 Can't I use JavaFX?

Hypothesizer 7
 No, in Linux.

Objector 61A
 Why not in Linux?

Hypothesizer 7
 Because the event loop of JavaFX, or tkinter, interferes with the event loop of LibreOffice or Apache OpenOffice itself.

Objector 61A
 That is not the case with Swing?

Hypothesizer 7
 As far as I know, Swing works fine in the LibreOffice JVM.

2: Preparation


Hypothesizer 7
 Often, your UNO component implements some of your UNO interfaces.

Objector 61B
 My "UNO interfaces"? . . . Where are they?

Hypothesizer 7
 Ah, someone who wants only some listeners for existing broadcasters will not have any of your UNO interfaces, and it is fine.

Objector 61B
 Being told "fine", I feel alienated . . .

Hypothesizer 7
 You do not need any.

Objector 61B
 I want!

Hypothesizer 7
 Well, if you want one, you can create one and generate its Java mapping image according to the previous article.

Objector 61B
 . . . Well, I don't want one after all.

3: Code


Hypothesizer 7
 This is a typical code piece that creates a UNO component.

@Java Source Code 
package theBiasPlanet.unoUtilitiesTests.localUnoObjectsTest1;

import com.sun.star.lang.XServiceInfo;
import com.sun.star.lib.uno.helper.WeakBase;

public class TestUnoComponent extends WeakBase implements XServiceInfo {
	public TestUnoComponent () {
	}
	
	@Override
	public String getImplementationName () {
		return "not specified";
	}
	
	@Override
	public boolean supportsService (String a_serviceName) {
		return false;
	}
	
	@Override
	public String [] getSupportedServiceNames () {
		return new String [0];
	}
}

Objector 61B
 . . . "WeakBase"?

Hypothesizer 7
 'com.sun.star.lib.uno.helper.WeakBase' is a helper class that has already implemented some UNO interfaces ('com.sun.star.uno.XWeak' and 'com.sun.star.lang.XTypeProvider', to be exact), and I do not see any reason why you should not use it, but if you want just a listener for a C++ or Java broadcaster, you will not particularly need it.

Objector 61B
 . . . Being told "not ~ need it", what should I do then?

Hypothesizer 7
 Your UNO component can just implement the listener UNO interface(s).

Objector 61A
 What are those interfaces implemented by 'WeakBase'?

Hypothesizer 7
 'XWeak' is for making any instance of it be able to be weakly-pointed.

'XTypeProvider' is for making it accessible from macro languages.

Objector 61A
 "weakly-pointed"?

Hypothesizer 7
 As is detailed in a previous article, 'weakly-pointed' means that the usage count of the instance is incremented just before the instance is really accessed and is decremented immediately after the access is finished.

Objector 61B
 I don't understand at all . . .

Hypothesizer 7
 If you do not do any C++ UNO programming, it will not matter actually.

Anyway, implementing 'XWeak' will not harm anything even if you do not use any weak-pointing at all.

4: A Notice About Creating Any UNO Service


Hypothesizer 7
 Any UNO service is, roughly speaking, a UNO component registered into a UNO services manager, which is a factory of UNO objects.

Objector 61A
 So, I can just create the UNO component like the above, right?

Hypothesizer 7
 You can create the UNO component like the above, but it has to implement some specific UNO interfaces.

Objector 61A
 What interfaces?

Hypothesizer 7
 That will be detailed in a future article on creating any UNO service, but I wanted to say here that while the above is the general way of creating any UNO component, there are some more requirements for any registered-as-'UNO service' UNO component.

5: Usage


Hypothesizer 7
 The class file of the UNO component, of course, has to be put into the classes paths somehow.

Objector 61A
 "somehow" . . .

Hypothesizer 7
 If your program is an independent program (which means that it is not any LibreOffice or Apache OpenOffice JVM program), you can put it as usual as for any ordinary Java program.

If not, there are 2 ways: 1) register the path in the 'URE_MORE_JAVA_TYPES' item in '%the LibreOffice or Apache OpenOffice product directory%/program/fundamentalrc' in Linux or in '%the LibreOffice or Apache OpenOffice product directory%\program\fundamental.ini' in Windows 2) include the class file in the extension Jar file or macro Jar file (note that it is visible only from the extension or macro).

Objector 61A
 On the contrary, I can put the class in an existing path in the 'URE_MORE_JAVA_TYPES' item, can't I?

Hypothesizer 7
 Well, I do not particularly recommend it, but I do not say that it is impossible.

Objector 61A
 Hmm . . .

Hypothesizer 7
 Anyway, in order to create any instance of the UNO component in the Java environment, you can just call any constructor of the class.

Objector 61B
 Oh? How can I use the instance?

Hypothesizer 7
 You can use it as an ordinary Java object in the Java environment.

Objector 61B
 Huh? I have to do "UnoRuntime.queryInterface" things, don't I?

Hypothesizer 7
 No, you do not: as the UNO object lives in the environment, no UNO proxy is used there.

Objector 61B
 Hmm . . .

Hypothesizer 7
 If you handle the UNO object from another environment, of course, you will have to handle it as it is a remote UNO object.

Objector 61B
 Do you mean, from another programming language?

Hypothesizer 7
 Even from the same programming language, if it is from another environment.

Objector 61B
 Huh? "the same programming language", but "another environment"?

Hypothesizer 7
 Any console Java client is another environment if the UNO object lives in the LibreOffice JVM. . . . Note that when I say "another programming language environment", I mean 'another (programming language environment)', not '(another programming language) environment'.

Objector 61B
 The console Java client has to have the UNO component class in the classes paths, of course?

Hypothesizer 7
 Of course not. The console client uses the UNO interfaces, but not the UNO component.

Objector 61B
 Huh? That's odd!

Hypothesizer 7
 That is not odd at all: that is how UNO works.

Objector 61B
 How can the UNO component be instantiated from another environment?

Hypothesizer 7
 Usually, you create a UNO service, which will be dealt in a future article.

References
<The previous article in this series | The table of contents of this series | The next article in this series>
Posted by at
Labels: