Slave is anyone who blindly accepts someone's decisions. You make your decisions based on your knowledge. Learning the basics is the starting point.
Topics
About: UNO (Universal Network Objects)
The table of contents of this article
- Starting Context
- Target Context
- Orientation
- Main Body
- 1: A Caution About the Terminology We Use
- 2: What Is UNO Process?
- 3: What Is UNO Object?
- 4: What Is UNO Component?
- 5: What Is UNO Interface?
- 6: What Is UNO Proxy?
- 7: What Is UNO Service? What Is UNO Services Manager? What Is Global UNO Services Manager?
- 8: What Is 'UNO Service'-Specific Global UNO Service Instances Factory?
- 9: What Is UNO Objects Context?
- 10: What Is Property of UNO Object?
- 11: What Is Attribute of UNO Object?
- 12: What Is UNO Datum Type Unmerged File? What Is UNO Datum Types Merged File? What Is UNO Datum Types Registry?
- 13: What Is LibreOffice or Apache OpenOffice Extension (Also Known as UNO Extension)?
Starting Context
- The reader has a knowledge on what UNO is and how it is related to LibreOffice or Apache OpenOffice.
Target Context
- The reader will know what the basic elements of UNO are like.
Orientation
Here is addressed an indispensable knowledge for exploiting LibreOffice or Apache OpenOffice. Almost all of the subsequent articles will be based on the knowledge.
The essence of UNO and UNO's relationship to LibreOffice or OpenOffice, also an indispensable knowledge, has been addressed in the previous article.
How to decipher terms used in the official reference document and the UNOIDL API document (here for LibreOffice and here for Apache OpenOffice) of LibreOffice or Apache OpenOffice will be addressed in the next article.
Stage Direction
Here are Hypothesizer 7, Objector 3A, and Objector 3B in front of a computer.
Main Body
1: A Caution About the Terminology We Use
Hypothesizer 7
Although there is the official reference document, I cannot help but say regrettably that the terminology used there (which, I call, 'the standard terminology') is not fit to be used for any decent description.
Objector 3A
Wow, you are bad-mouthing!
Hypothesizer 7
Sir, I do not want to, really, but how can I do otherwise? I cannot use any unfit terminology, and I have to explain why I do not use the standard terminology, don't I?
Objector 3A
You can use the standard terminology.
Hypothesizer 7
I cannot, really: any decent description cannot be built on any unfit terminology.
Objector 3A
How come?
Hypothesizer 7
Sir, any terminology demarcates concepts; with concepts not being demarcated appropriately, how can I make any decent description, which is a depiction of a relationship between some concepts?
Objector 3A
Well, how are the demarcations of the standard terminology inappropriate, do you claim?
Hypothesizer 7
For example, "service" there is used in some multiple meanings, which are not really any service.
Objector 3A
You say "not really any service", but as they have defined them to be "services", they are legitimately "services" according to the terminology.
Hypothesizer 7
Sir, the word, 'service', has the globally-established meaning in the software community; someone should not arbitrarily redefine it against the globally-established meaning, to mean 'interface', 'factory', or whatever.
Objector 3A
Any terminology can define any term in any way arbitrarily, logical speaking.
Hypothesizer 7
Logically, it may be so, but practically, it is a very harmful act. For example, should someone define 'human' including only white people, while defining 'monkey' including monkeys and colored people?
Objector 3A
That's absurd!
Hypothesizer 7
Or should someone define 'sow' meaning women, because the definition is arbitrary?
Objector 3A
Absurd!
Hypothesizer 7
At least, you agree that it is not that "Any terminology can define any term in any way arbitrarily", don't you?
Objector 3A
I said "logical speaking"; personally, I never call women 'sows'.
Hypothesizer 7
Likewise, I never call interfaces "services".
Objector 3A
Hmm.
Hypothesizer 7
Another example of problematic terms there is "component", which is too abused for me to be able to fathom what each appearance represents; the writer (or writers) seems to have loved the word very much.
Objector 3A
As 'component' is a very general word, almost anything can be called 'component'.
Hypothesizer 7
I agree: anything is a component of the universe. So, I do not say that calling something 'component' is logically wrong, but it is not doing any job of identifying what that something is.
Objector 3B
I understand what you mean, but honestly, I don't want to learn any terminology you have concocted.
Hypothesizer 7
I understand, madam. However, what is an alternative? I repeat that using the unfit terminology is never any option for me.
Objector 3B
But, as the API document of LibreOffice is written in the "unfit" terminology, I wouldn't be able to understand the API document according to your terminology!
Hypothesizer 7
Ah, "the API document of LibreOffice" should mean the document that explains the specifications of UNO datum types included in LibreOffice, I guess?
Objector 3B
Yes.
Hypothesizer 7
Then, you are right. So, I will also explain how you should try to decipher the official reference document and the UNO API document, in the next article.
2: What Is UNO Process?
Hypothesizer 7
First, I will clarify what I mean by a term, 'UNO process', because that term will be sometimes used afterward.
UNO process is an operating system process (an instance of a program) that has one or more programming language runtime environments in that UNO is enabled, inside it.
Objector 3B
Huh? More than one programming language runtime environments in a single process?
Hypothesizer 7
Yes. A typical LibreOffice instance is a UNO process that is mainly a C++ runtime environment, but has also a Java runtime environment via JNI and a Python runtime environment via the Python/C API.
Objector 3B
Ah, JNI, etc. are used.
Hypothesizer 7
In fact, any UNO process is a LibreOffice or Apache OpenOffice process or an external UNO program process.
Objector 3B
So, we aren't talking about only macros, but also external programs . . .
3: What Is UNO Object?
Hypothesizer 7
UNO object is an object that is projected into the UNO space.
Objector 3B
Huh? How is that supposed to be understood?
Hypothesizer 7
If you do not understand that expression, the reason will be that you do not understand the essence of UNO.
Objector 3B
. . . Do I have to read such a damn article?
Hypothesizer 7
I say only that 'Starting Context' is not posted up there meaninglessly.
Objector 3A
I say only that your are impertinent.
4: What Is UNO Component?
Hypothesizer 7
UNO component is a class that can be instantiated into UNO objects.
Objector 3A
Do you mean that any UNO object is an instance of a UNO component?
Hypothesizer 7
Yes.
It is important to understand that any UNO component exists only in a specific programming environment (for example, a Java environment) and is not recognized by the UNO space.
Objector 3A
Huh? Are you OK?
Hypothesizer 7
I am fine.
Objector 3A
You were taking in a delirium.
Hypothesizer 7
. . . As is explained in the previous article, the UNO space contains no implementation; so any UNO component, which is an implementation, does not belong to the UNO space.
Objector 3A
I understand that the UNO component doses not belong to the UNO space, but that does not necessarily mean that it's not even recognized by the UNO space.
Hypothesizer 7
You are right, but it is really not even recognized by the UNO space.
Objector 3A
That's odd! The UNO space sees a UNO object, but not recognize its class!
Hypothesizer 7
But that is how it is, which dictates how you do UNO programming and explains why the UNO API document is like that.
Objector 3A
What do you mean by "like that"?
Hypothesizer 7
That document describes UNO interfaces (explained in the next section), but not any UNO component.
Objector 3A
That's why the document isn't helpful! The UNO API doesn't explain what UNO object implements what interfaces!
Hypothesizer 7
That is because that information is about UNO components, which are not recognized in the UNO space, which the document is about.
Objector 3A
. . . I understand the logic, but that doesn't alleviate the unhelpful-ness at all.
Hypothesizer 7
I am trying to alleviate it, but the effort is in progress.
Anyway, I assure that 'UNO component' and 'UNO object' are strictly used as a class and an instance by me, while in the official document, 'UNO component' or 'UNO object' is unfathomable whether it is a class or an object at each appearance.
Objector 3B
Can any ordinary Java (for example) class be "instantiated into UNO objects"?
Hypothesizer 7
That is a good question, madam. The answer is no: any UNO component has to have implemented a specific interface ('::com::sun::star::uno::XInterface').
Objector 3B
So, UNO component is a class that has implemented the specific interface?
Hypothesizer 7
Yes. That is a legitimate alternative definition of UNO component.
5: What Is UNO Interface?
Hypothesizer 7
UNO interface is an interface that is registered into the UNO datum types registry as a UNO interface, which is '::com::sun::star::uno::XInterface' or its descendant, and works as the abstract outward manifestation of an aspect of each UNO component that implements the interface.
Objector 3A
You were talking in a delirium again.
Hypothesizer 7
I am fine.
Objector 3A
But you were babbling like "the UNO datum types registry".
Hypothesizer 7
Here, please assume that there is such a registry (it will be explained later). What is important here is that any UNO interface has to be defined in the UNO space (registering the UNO interface into the UNO datum types registry represents defining it in the UNO space), which means that just creating a '::com::sun::star::uno::XInterface' descendant in a specific programming language is not creating any UNO interface.
Objector 3A
But you were also babbling like "the abstract outward mani" . . . something.
Hypothesizer 7
As the UNO component is not recognized in the UNO space, another programming language runtime environment cannot see the UNO component, but the UNO interfaces implemented by the UNO component.
Objector 3A
So, it works as a "manifold"?
Hypothesizer 7
Manifestation, sir.
Anyway, I warn that each of some UNO components has implemented very many UNO interfaces.
Objector 3A
How many is "very many"?
Hypothesizer 7
Some tens, if not a hundred, I guess.
Objector 3A
That's many, but how does that concern me?
Hypothesizer 7
You will see how, in the next section.
6: What Is UNO Proxy?
Hypothesizer 7
When we handle a UNO object that lives in another programming language runtime environment, we cannot directly handle the UNO object that does not live in the local environment, but get a proxy (a UNO proxy) to the remote UNO object and handle the proxy.
It is important to understand that the UNO proxy represents a single UNO interface of the remote UNO object.
Objector 3A
Um? Hmm, does that mean that I have to get many UNO proxies in order to handle a single UNO object?
Hypothesizer 7
If your concern pervades many UNO interfaces, yes, that does.
Objector 3A
You said that a UNO component might have implemented some tens of UNO interfaces . . .
Hypothesizer 7
Yes, I did. That is how UNO programming is sometimes tedious (although not difficult at all, I say).
Objector 3B
But I never did such thing as getting UNO proxies in my little Basic UNO programming, I'm sure . . .
Hypothesizer 7
That is a good point, madam. In some programming languages (for example, Python and Basic), such operations are handled by the runtime without the programmer's specifying so explicitly in source code. Still, the mechanism is the same.
Objector 3B
So, I can forget all together about UNO proxies or UNO interfaces for UNO programming in Basic.
Hypothesizer 7
I do not think that wise, madam. Knowing the mechanism is beneficial, and at least, you will have to know about UNO interfaces in order to know what methods can be called on each UNO object.
7: What Is UNO Service? What Is UNO Services Manager? What Is Global UNO Services Manager?
Hypothesizer 7
As I said earlier, in the official reference document, the word, "service", is used to refer to multiple concepts (including what are not any service at all), but we use the term, 'UNO service', to refer to only a single concept because readers have to unambiguously identify what is meant by the term.
We will begin with what UNO services manager is. Any UNO services manager is a factory of UNO objects, that (the UNO services manager) implements a UNO interface, '::com::sun::star::lang::XMultiComponentFactory'.
Objector 3A
"factory"?
Hypothesizer 7
Let's review the concept of factory. We can primitively create objects from a class (in Java, we call the 'new' operator), but we have to specify the exact class to do so. Instead, the factory assumes the work of creating objects, determining what class to use for each request and sometimes pooling objects.
Objector 3A
Ah-ha . . .
Hypothesizer 7
The UNO service is an item registered in a UNO services manager.
Objector 3A
"an item"?
Hypothesizer 7
When we request an UNO object from the UNO services manager, we specify an item out of all the items registered in the UNO services manager.
Objector 3A
How can I specify the item?
Hypothesizer 7
Each item has a unique name ('UNO service name') in the UNO services manager, and you will specify the name.
Objector 3A
I can also primitively create UNO objects from a UNO component without through any UNO services manager, can't I?
Hypothesizer 7
If you are going to create a UNO object in your own programming language runtime environment from a UNO component written in your programming language, yes, you can. However, UNO services managers are required because UNO objects are supposed to be able to be created also from other programming language runtime environments.
Objector 3A
Ah, I cannot just call 'new' to create a UNO object in another programming language runtime environment.
Hypothesizer 7
LibreOffice or Apache OpenOffice has multiple UNO services managers because some UNO services managers have to have their own contexts.
Objector 3A
Ah, a UNO services manager belongs to a spread sheets document . . .
Hypothesizer 7
For example, yes. On the other hand, each UNO process has the UNO services manager that we can use at any time, which is called 'global UNO services manager'. And we will call any UNO service registered in the global UNO services manager 'global UNO service'.
Objector 3A
Um? Does "each UNO process", not 'each UNO programming language environment', have the global UNO services manager?
Hypothesizer 7
Actually, yes. The JVM (or the Python runtime environment or any like) in a LibreOffice process doesn't have its own global UNO services manager.
Objector 3A
Then, how can a Basic macro create a UNO object in the JVM?
Hypothesizer 7
The global UNO services manager in the C++ runtime environment of the LibreOffice process can create UNO objects in the JVM.
Objector 3A
Then how about creating UNO objects in the Basic runtime environment in the LibreOffice process, from the JVM?
Hypothesizer 7
You cannot do such a thing.
Objector 3A
Huh? Why?
Hypothesizer 7
Because anyone cannot write any UNO component in Basic.
Objector 3A
Can't they?
Hypothesizer 7
Anyone cannot, because Basic does not allow creating even any class.
Objector 3A
Oh, of course. Then, how about Python?
Hypothesizer 7
As far as I know, the global UNO services manager cannot create any UNO object in the Python runtime environment, but you can create your own factory that creates Python UNO objects, as a Python macro function.
Objector 3A
How, exactly?
Hypothesizer 7
Well, I can show you how, in a future article.
8: What Is 'UNO Service'-Specific Global UNO Service Instances Factory?
Hypothesizer 7
'UNO service'-specific global UNO service instances factory is a factory that creates instances of a single global UNO service.
In the official reference document, it is called "service" (quite confusingly), but it is really a factory, not any service.
Objector 3B
The name is too long!
Hypothesizer 7
I could not come up with any shorter name that represents the concept correctly distinguishing-ly.
Objector 3B
"correctly distinguishing-ly"?
Hypothesizer 7
I mean, "service" is absolutely wrong; "global UNO service instances factory" (even which may be too long for you) does not distinguish it from global UNO services managers at all; what is another option?
Objector 3B
A name like 'service factory type B', perhaps?
Hypothesizer 7
1st, it creates service instances, not a service; 2nd, it is about a global UNO service, not a service in general; 3rd, "type B"? Well?
Objector 3B
"Well" what?
Hypothesizer 7
Well, wouldn't most people think, "What, the hell, is "type B"?"?
Objector 3B
Well . . .
Hypothesizer 7
"'UNO service'-specific global UNO service instances factory" will be understood, I hope, if long.
Objector 3B
Anyway, why is a thing like "'UNO service'-specific global UNO service instances factory" necessary? Isn't the global UNO services manager enough?
Hypothesizer 7
In fact, it is not particularly necessary; any 'UNO service'-specific global UNO service instances factory is just a front end to the global UNO services manager.
But some people may find it handy: you have to pass the arguments of the service instantiation as an array into the global UNO services manager, but you can define factory methods (called "constructors" in the official reference document) that have specific arguments, in the 'UNO service'-specific global UNO service instances factory.
9: What Is UNO Objects Context?
Hypothesizer 7
Conceptually, any UNO objects context is a context for some UNO objects; each UNO object is attached to a UNO objects context.
UNO objects context is called "component context" in the official reference document, but it is not really any context for any UNO component, but for some UNO objects.
Objector 3A
What is the difference?
Hypothesizer 7
For example, a UNO object of a UNO component is attached to a UNO objects context, while another UNO object of the same UNO component is attached to another UNO objects context.
Objector 3A
So, "component context" isn't about UNO components, but about UNO objects . . .
Hypothesizer 7
As "component" in the official reference document is quite ambiguous, "component context" is not distinguishing what it means.
Objector 3A
Anyway, what is "context"? Why does a UNO object need a context?
Hypothesizer 7
It is a container of some properties, and the address of the global services manager is an important one of them.
As for "Why", the UNO object behaves according to the property values in the context.
Objector 3A
So it's really a context . . .
Hypothesizer 7
What did you expect? I do not name what is not really any context "context".
Objector 3A
So, there are multiple UNO objects contexts.
Hypothesizer 7
At least, there can be, and you can create your own UNO objects contexts.
Objector 3A
I don't know if I will want to.
Hypothesizer 7
Anyway, when your external program is initialized as a UNO program, the program gets a UNO objects contexts to the local runtime environment; when the external program connects to a UNO server (typically a LibreOffice or Apache OpenOffice instance), it gets a UNO objects contexts to the UNO server; when your macro is invoked, it has an access to a UNO objects contexts to the LibreOffice or Apache OpenOffice instance; when your global UNO service is instantiated, the instance gets the specified UNO objects context. And the UNO objects context for each case is the entry point for UNO operations, for your artifact.
Objector 3A
What do you mean by "the specified UNO objects context"?
Hypothesizer 7
When you instantiate the global UNO service, you explicitly (recommendedly) specify the UNO objects context.
10: What Is Property of UNO Object?
Hypothesizer 7
There is a UNO interface named '::com::sun::star::beans::XPropertySet', which has methods, 'getPropertyValue' and 'setPropertyValue' among others, and when a UNO component implements the UNO interface, each name-value pair that can be managed through the UNO interface is called 'property' of any instance of the UNO component.
Objector 3A
So, properties aren't particularly special from the point of view of mechanism, but just data that can be managed through a UNO interface . . .
Hypothesizer 7
Actually, yes, but I introduced them here because they are prevalently used in LibreOffice and Apache OpenOffice, and we will handle them frequently.
11: What Is Attribute of UNO Object?
Hypothesizer 7
A UNO interface may have some attributes, each of which is actually a pair of a getter method and a setter method (if the attribute is writable) or a getter method (if the attribute is read-only).
Objector 3A
Why do I need both 'properties' and 'attributes'?
Hypothesizer 7
You do not particularly, but in fact, there are both in LibreOffice and Apache OpenOffice (although attributes are not so prevalent as properties), and you may have to use both when you handle the LibreOffice or Apache OpenOffice process.
12: What Is UNO Datum Type Unmerged File? What Is UNO Datum Types Merged File? What Is UNO Datum Types Registry?
Hypothesizer 7
We define any UNO compound datum type in a UNOIDL file; the UNOIDL compiler, 'idlc', compiles the UNOIDL file into a UNO datum type unmerged file; the tool, 'regmerge', merges some UNO datum type unmerged files into a UNO datum types merged file; we register such UNO datum types merged files into the UNO datum types registry.
Objector 3A
How can I register a UNO datum types merged file into the UNO datum types registry?
Hypothesizer 7
You can do so by just copying the UNO datum types merged file (or creating a link to it) into a specific directory or by appropriately putting the UNO datum types merged file into a LibreOffice or Apache OpenOffice extension (we will learn what the LibreOffice or Apache OpenOffice extension is, later) and registering the extension.
Objector 3A
How can I create the Java datum types (especially, Java interfaces) that are mapped from the UNO compound datum types?
Hypothesizer 7
There is a tool, 'javamaker' ('cppumaker' for C++ and 'climaker' for Microsoft .NET Framework), that creates the Java datum types from the UNO datum types merged file.
Objector 3B
How about Python?
Hypothesizer 7
There is no such tool for Python.
Objector 3B
Being told just "no such tool" . . .
Hypothesizer 7
You can manually create the interfaces, if you need them.
Objector 3B
Don't I need them?
Hypothesizer 7
That depends on you: as Python UNO handles UNO proxies implicitly, usually, you do not necessarily need them.
Objector 3B
I don't understand . . .
Hypothesizer 7
That is quite natural at this stage; we will dig into the details of Python UNO in some future articles.
13: What Is LibreOffice or Apache OpenOffice Extension (Also Known as UNO Extension)?
Hypothesizer 7
When we add a functionality into LibreOffice or Apache OpenOffice, a standard way to do so is to create a LibreOffice or Apache OpenOffice extension and register the extension into LibreOffice or Apache OpenOffice. In short, the LibreOffice or Apache OpenOffice extension is a package of a functionality.
Objector 3A
"a standard way"?
Hypothesizer 7
It is not any 'only way': we can add a Python macro just by putting the Python module file into a specific directory although we can include the Python macro in an extension. However, when we want to register a UNO service or some other things, it is the most established way, and I do not know why we should find another way.
We will call the LibreOffice or Apache OpenOffice extension also 'UNO extension' in the meaning that the extension conforms to the UNO specifications.
References
- Apache OpenOffice Wiki. (2014/01/02). Apache OpenOffice Developer's Guide. Retrieved from https://wiki.openoffice.org/wiki/Documentation/DevGuide/OpenOffice.org_Developers_Guide
- N/A. (N/A). LibreOffice: Main Page. Retrieved from https://api.libreoffice.org/docs/idl/ref/index.html
- The Apache Software Foundation. (2013). Module star. Retrieved from https://www.openoffice.org/api/docs/common/ref/com/sun/star/module-ix.html
