Return-Path: X-Original-To: apmail-incubator-ooo-commits-archive@minotaur.apache.org Delivered-To: apmail-incubator-ooo-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 629EE728A for ; Sun, 27 Nov 2011 22:51:00 +0000 (UTC) Received: (qmail 71978 invoked by uid 500); 27 Nov 2011 22:51:00 -0000 Delivered-To: apmail-incubator-ooo-commits-archive@incubator.apache.org Received: (qmail 71943 invoked by uid 500); 27 Nov 2011 22:51:00 -0000 Mailing-List: contact ooo-commits-help@incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: ooo-dev@incubator.apache.org Delivered-To: mailing list ooo-commits@incubator.apache.org Received: (qmail 71936 invoked by uid 99); 27 Nov 2011 22:51:00 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 27 Nov 2011 22:51:00 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 27 Nov 2011 22:50:56 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id 827EC2388B1B; Sun, 27 Nov 2011 22:50:12 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1206895 [7/12] - in /incubator/ooo/ooo-site/trunk/content/udk/common: ./ man/ man/concept/ man/draft/ man/draft/scripting/ man/draft/scripting/DesignDoc/ man/images/ man/spec/ man/tasks/ man/tutorial/ Date: Sun, 27 Nov 2011 22:50:08 -0000 To: ooo-commits@incubator.apache.org From: kschenk@apache.org X-Mailer: svnmailer-1.0.8-patched Message-Id: <20111127225012.827EC2388B1B@eris.apache.org> Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/module_description.html URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/module_description.html?rev=1206895&view=auto ============================================================================== --- incubator/ooo/ooo-site/trunk/content/udk/common/man/module_description.html (added) +++ incubator/ooo/ooo-site/trunk/content/udk/common/man/module_description.html Sun Nov 27 22:49:46 2011 @@ -0,0 +1,309 @@ + + + + + Module Description + + + + + + + + + + +

Module Description

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ Overview
+ Description of module-description.dtd
+ Integration + of the module description in the component
+ Example
+

+ Overview

+ +

A module description provides detailed information about the module and + its supported components, which is accessible in different manners. The included + description is available by reading directly, by generating a short html-description, or by + making an environment check for supported components to check if all + needed types and services are available in the environment where they will be + used. This environment check could take place during registration/installation + or during a separate consistency check for a component.

Description of + module-description.dtd

module-description.dtd

+ +

<?xml version="1.0" encoding="UTF-8"?> +  +

<!ENTITY % component-description-optional "reference-docu|service-dependency|type"> + <!ENTITY % module-description-optional "project-build-dependency|runtime-module-dependency|(%component-description-optional;)"> + <!ELEMENT module-description (module-name,component-description+,(%module-description-optional;)*)> + + <!ELEMENT component-description (author,name,description,loader-name,supported-service+,(%component-description-optional;)*) + > + + <!ELEMENT author (#PCDATA)> + <!ELEMENT name (#PCDATA)> + <!ELEMENT description (#PCDATA)> + + <!ELEMENT reference-docu EMPTY> + <!ATTLIST reference-doc + xmlns:xlink CDATA #FIXED "http://www.w3.org/1999/xlink/Namespace" + xlink:type (simple) #FIXED "simple" + xlink:href CDATA #REQUIRED + xlink:role NMTOKEN #IMPLIED + xlink:title CDATA #IMPLIED > + + <!ELEMENT module-name (#PCDATA)> + <!ELEMENT loader-name (#PCDATA)> + <!ELEMENT supported-service (#PCDATA)> + <!ELEMENT service-dependency (#PCDATA)> + <!ELEMENT project-build-dependency (#PCDATA)> + <!ELEMENT runtime-module-dependency (#PCDATA)> + <!ELEMENT language (#PCDATA)> + <!ELEMENT status EMPTY > + <!ATTLIST status value (under_construction | alpha | beta | final) + #REQUIRED> + <!ELEMENT type (#PCDATA)>

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

author	The name of the person who has implemented the component
name	+ The implementation name of a component. + (e.g., com.sun.star.comp.stoc.ORegistryServiceManager) +
description	+ A short description which should be understandable to all people in + the development process. +
reference-docu	specify an xlink to further documentation.
module-name	+ The name of a shared library without the system prefix (lib) or + postfix (.so, .dll, ...) + (e.g., smgr). An executable name. A Java class file name or the + JAR name. +
loader-name	+ The service name of the loader, which should be used to load the component. + (e.g., com.sun.star.loader.SharedLibrary) +
supported-service	+ All services supported by this component. + (e.g., com.sun.star.registry.SimpleRegistry) +
service-dependency	+ All services need this implementation. + (e.g., com.sun.star.lang.RegistryServiceManager (very often the + service manager component is used) ) +
project-build-dependency	+ All projects which are necessary. + (e.g., cppuhelper, cppu, vos, sal, stl) +
runtime-module-dependency	+ All projects which are used at runtime + (e.g., cppu1, vos1$(COM), sal1) +
language	+ The language in which the component is implemented. + (e.g., C++) +
status	+ The implementation state of the component. + (under construction, alpha, beta, or final) +
type	+ Which type descriptions are necessary to enable communication + with other environments. To ensure that the bridges can create proxies + and stubs, they must get the type description of the used types. + The special term "comprehensive" means that all type descriptions + are built into the component. + The type descriptions must be installed in the type repository (applicat.rdb). +

*$(COM) is the extension of the C++ compiler.
+ *$(SUPDCP) is the extension of a module which depends on an SUPD and the + platform.

All components written in C++ need the bridge library from uno to C++ for + scripting or remote communication. These are the msci_uno.dll with + the MSC4.2 and the MSC6.0; and the libsunpro5_uno.so library with the + SunPro 5.0 compiler.

+ +

+ Integration of the module description in the module(component)

+ +

Normally, the module description should also be available by calling the + module itself. In case of an implementation as a shared library, the shared + library should export a C-function which provides this xml description + as a return value of type sal_Char*. This function could be generated + from the xml description by using the tool xml2cmp. + The generated source file must be built with the component and the C-function + component_getDescriptionFunc must be exported.

Example for a simple registry component:

xml2cmp + -func simreg_desc.cxx simreg.xml +

+
+

Example:

Description for the simple registry component, simreg.xml: +

+ +

<?xml version='1.0' encoding="UTF-8"?> + <!DOCTYPE module-description PUBLIC "-//W3C//DTD HTML 3.2//EN" + "module-description.dtd"> + + <module-description xmlns:xlink=""http://www.w3.org/1999/xlink"> + <module-name> simreg </module-name> + <component-description> + + <author> Juergen Schmidt </author> + <name> com.sun.star.comp.stoc.SimpleRegistry </name> + + <description> + This component provides access to a simple hierarchical registry. The registry + based on one registry file. + </description> + + <loader-name> com.sun.star.loader.SharedLibrary </loader-name> + <language> c++ </language> + <status value="final"/> +

<supported-service> com.sun.star.registry.SimpleRegistry + </supported-service> +

<type> com.sun.star.lang.XTypeProvider </type> + <type> com.sun.star.lang.XServiceInfo </type> + <type> com.sun.star.lang.XSingleServiceFactory </type> + <type> com.sun.star.lang.XMultiServiceFactory </type> + <type> com.sun.star.registry.XSimpleRegistry </type> + <type> com.sun.star.registry.XRegistryKey </type> + <type> com.sun.star.uno.XAggregation </type> + <type> com.sun.star.uno.XWeak </type> + <type> com.sun.star.uno.TypeClass </type> +

</component-description>

<project-build-dependency> cppuhelper </project-build-dependency> + <project-build-dependency> cppu </project-build-dependency> + <project-build-dependency> registry </project-build-dependency> + <project-build-dependency> store </project-build-dependency> + <project-build-dependency> vos </project-build-dependency> + <project-build-dependency> sal </project-build-dependency> + + <runtime-module-dependency> cppuhelper </runtime-module-dependency> + <runtime-module-dependency> cppu1 </runtime-module-dependency> + <runtime-module-dependency> reg1 </runtime-module-dependency> + <runtime-module-dependency> store1 </runtime-module-dependency> + <runtime-module-dependency> vos1$(COM) </runtime-module-dependency> + <runtime-module-dependency> sal1 </runtime-module-dependency> + + </module-description>

+ +

Author: Jürgen + Schmidt ($Date: 2004/10/29 07:25:34 $)
+ Copyright 2001 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303 USA. +

+ + Propchange: incubator/ooo/ooo-site/trunk/content/udk/common/man/module_description.html ------------------------------------------------------------------------------ svn:eol-style = native Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/names.html URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/names.html?rev=1206895&view=auto ============================================================================== --- incubator/ooo/ooo-site/trunk/content/udk/common/man/names.html (added) +++ incubator/ooo/ooo-site/trunk/content/udk/common/man/names.html Sun Nov 27 22:49:46 2011 @@ -0,0 +1,11 @@ + + + + + + + + + + Propchange: incubator/ooo/ooo-site/trunk/content/udk/common/man/names.html ------------------------------------------------------------------------------ svn:eol-style = native Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/assemblyversioning.html URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/assemblyversioning.html?rev=1206895&view=auto ============================================================================== --- incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/assemblyversioning.html (added) +++ incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/assemblyversioning.html Sun Nov 27 22:49:46 2011 @@ -0,0 +1,247 @@ + + + + + + + +Author: Joachim Lingner
+ +

Important Change

+Because of the problem mentioned in Microsoft's knowledge base article +905238 +we will increase the assembly versions for every new major and minor +version of OOo. + +

Notes

For OOo 2.4.1 the version for policy.1.0.cli_basetypes.dll was changed from +9.0.0.0 to 9.1.0.0. This was done because a bug, possibly in .NET Framwork 1.1, +caused the test program (cli_ure/qa/versioning) to fail, when the version +was 10.0.0.0. or greater (11.0.0.0 etc.). +It failed, however, only when StarOffice was updated. A +stand-alone installation always worked. +

+The tests also failed with many updated respin versions of StarOffice. In all cases +.NET failed to find the latest policy assembly. For example, when version 6 and 13 of +policy.1.0.cli_ure.dll where installed, then the framwork chose the older version. +Here is an overview of the tests. Tested where different respin version with an update 11: +

+StarOffice     Test 
+version	       result
+(respin)       update u11
+----------------------------
+final           ok
+u1 		ok
+u2              failed 
+u3              failed
+u4              failed
+u5              failed
+u6              failed
+u7              failed
+u8              ok
+u9              ok
+u10             ok		
+

+It is possible that those respin versions which failed the test will also not +work with older updates. For example, I tested a StarOffice u4 with the updates +8,9 and 10. The tests failed with all three offices. +

+When the runtests.exe was configured +to use the .NET Framework 2.0 then it worked with all updated offices. +To configure runtests to use another runtime one has to provide config file +(runtests.exe.config), which contains for example: +

+<configuration>
+ <startup>
+   <supportedRuntime version="v2.0.50727" />
+ </startup>
+</configuration>
+

+ +

+Note that the configuration file is only necessary if .NET Framework 1.1 AND +.NET Framework 2.0 are installed. The easiest way to enforce the use of the latest +framework is to simple uninstall .NET Framework 1.1. +

+As of StarOffice 9 (OOo 3.0) this problem will not exist anymore, since that office +requires at least a .NET Framework 2.0. +

+ +

Versioning for assemblies of CLI-UNO Binding

This documents gives some background +about the versioning applied to the assemblies which are part of the +CLI-UNO binding. +

+The assemblies have all a strong names. +Hence the .NET runtime will strictly enforce versioning rules. That +is, a client application can only run with the assemblies it was +build with. The exception is, that users could change the application +or machine config file and redirect the version of the respective +assembly, or OOo installs policy assemblies.

+ +

+For this document we assume that the +reader has good knowledge of shared assemblies and policy assemblies.

+ +

Versioning Scheme

The version of an assembly consists of +four parts:

major.minor.build.revision

+ +

The meaning of every part can be freely +interpreted by developers. There is no need to use the parts exactly +as their names indicate.

For our assemblies we will use this +convention:

+ +

major: expresses a major change
minor: expresses a minor incompatible change
build: expresses a compatible change.
revision: expresses a compatible change.

+ +

For incompatible changes we will +increase the major part of the assembly. The minor will remain +unchanged, except for some urgent reasons. +

The CLI-UNO assemblies should not +become incompatible very often. In fact, we will try to keep them +compatible as long as possible, so as not to break existing +application. +

Usually we will increase the “build” +as a result of bug fixes or new compatible features. +

The “revision” will remain +unchanged, except for some urgent reasons. +

Although a version could change everytime an assembly was modified, +we will try to change the version only once between two official releases. +For example, say OOo2.0 will be shipped based on 680m130. In m131 a bug +will be fixed (compatibly). Then the version will be increased. Even +if other bugs will be fixed (compatibly) in the following milestones, +the version will remain unchanged. In the next official release, the +version will be the one from m131. If, however, the assembly will be +altered incompatibly, then the version must be increased again. But +the following compatible or incompatible changes, will not affect the +version of the forthcoming release. For example, in m132 an +incompatibility will be introduced and the version will be increased +again (major or minor). The next release will be based on m140. All +other changes between 132 and 140 will not cause the version to +change.

+ +Developers, please notice that you should build your CLI client applications +always with the final version, such as OOo2, OOo3, etc. If, for an example, the application +was build with assemblies from OOo2.0.1, then users with OOo2 cannot use it. + + +

Compatible Changes and Policy Assemblies

Compatible changes are often caused by +bug fixes. Because of the versioning rules of .NET (application runs +only with the assembly it has been build with), client applications +cannot benefit from the bug fixes without manual adaptations by the +user. Because many users do not have the necessary knowledge, +OpenOffice.org will provide publisher policy assemblies. By +installing the policy assemblies we will ensure, that applications +use the latest (compatible) assemblies of the CLI-UNO binding.

+ +

A policy assembly applies only for a +particular assembly with a determined major and minor version. For +example, policy.1.1.cli_types.dll only applies for version 1.1.x.x +of cli_types.dll. This has some implications because the .NET +framework does not support a chaining mechanism for policy +assemblies. For example, let us assume there is a cli_types.dll with +these versions:

1.1
+1.2
+1.3
+ +

Because the newer versions are +backwards compatible one could deploy these policy assemblies:
+policy.1.1.cli_types.dll: +oldVersion: 1.1.0.0 newVersion: 1.2.0.0
+policy.1.2.cli_types.dll: +oldVersion: 1.2.0.0 newVersion: 1.3.0.0

One could expect that an application +that was build with version 1.1 of cli_types.dll uses version 1.3. +But this is not the case. The application uses version 1.2. The +version part in the name of the policy assembly corresponds to the +macro.minor part of the assembly for which it provides the +redirection. If one wanted applications, which were build with v1.1 +to use v1.3, then one would have to provide a new policy assembly:

+ +

policy.1.1.cli_types.dll: +oldVersion: 1.1.0.0 newVersion: 1.3.0.0

+ +

If we would allow that the minor part +of the version could be used to indicate a compatible change, then +one would have to provide a policy assembly for every minor. For +example, let us again assume that the following versions of +cli_types.dll are compatible (they are backwards compatible to the +previous version):

1.1, 1.2, 1.3, 1.4

And we assume that there are +applications, which have been build with one of these versions. In +order to have them all use the latest version 1.4, one would have to +ship three policy assemblies:

policy.1.1.cli_types.dll: +oldVersion: 1.1.0.0 newVersion: 1.4.0.0
+policy.1.2.cli_types.dll: +oldVersion: 1.2.0.0 newVersion: 1.4.0.0
+policy.1.3.cli_types.dll: +oldVersion: 1.3.0.0 newVersion: 1.4.0.0
+ +

And this would have to be done for all +assemblies of CLI-UNO binding. Therefore, only the build and revision +part of the version are used for compatible changes. Then it is +sufficient to ship only one policy assembly for each assembly. Policy +assemblies have also a version. If there are several policy +assemblies installed, which all target the same assembly, then the +.NET runtime uses the policy with the latest version.

+ + +

Compatible Changes in cli_types.dll

+Changes to unpublished types (declared in unoidl WITHOUT the keyword "published") +are always regarded as compatible changes even +if they have been changed incompatibly. This is possible because client programs +must not use unpublished types. It is also necessary because changes to unpublished +types may occur in every new version or product update. To declare the change +to be incompatible would prevent client code to run with the respective version of the +office. + + +

Versioning of Policy Assemblies

Policy assemblies must have a version the same as ordinary +assemblies. By providing a version one can have different policy +assemblies for one assembly. The .NET runtime will use the policy +assembly with the latest version.

Policy assemblies are only used if there is a new version of an +assembly which is still backwards compatible. With our versioning +scheme this would apply to assemblies of the same name where the +major and minor part of the version are equal. For example, if there +are multiple versions of cli_types.dll: 1.1.0.0, 1.1.1.0, 1.1.2.0, +then there could be a policy.1.1.cli_types.dll +
+version 1.0.0.0, redirecting from 1.1.0.0 to 1.1.1.0
+version 2.0.0.0, redirecting from 1.1.0.0-1.1.1.0 to 1.1.2.0
+

+ +

We will simply increase the major part unless there are urgent +reasons to use the other parts of the version. Please notice that the +name of the policy assembly already contains the major.minor version +parts of the related assembly.

+ + +

+Last changed: $Date: 2008/05/07 13:22:48 $ + + Propchange: incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/assemblyversioning.html ------------------------------------------------------------------------------ svn:eol-style = native Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/assemblyversioninghistory.html URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/assemblyversioninghistory.html?rev=1206895&view=auto ============================================================================== --- incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/assemblyversioninghistory.html (added) +++ incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/assemblyversioninghistory.html Sun Nov 27 22:49:46 2011 @@ -0,0 +1,131 @@ + + + + + + + + +

Version History of Assemblies

+ ++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

OpenOffice2, StarOffice 8 (src680 m124)
	cli_basetypes.dll	1.0.0.0
	cli_cppuhelper.dll	1.0.0.0
	cli_types.dll	1.1.0.0
	cli_ure.dll	1.0.0.0

OOo 2.0.1, StarOffice 8 Product Update 1 (src680 m145)
	cli_basetypes.dll	1.0.0.0
	cli_cppuhelper.dll	1.0.1.0
	policy.1.0.cli_cppuhelper.dll	1.0.0.0
	cli_types.dll	1.1.1.0
	policy.1.1.cli_types.dll	1.0.0.0
	cli_ure.dll	1.0.1.0
	policy.1.0.cli_ure.dll	1.0.0.0

Current builds (as of SRC680m156)
	cli_basetypes.dll	1.0.0.0
	cli_cppuhelper.dll	1.0.2.0
	policy.1.0.cli_cppuhelper.dll	2.0.0.0
	cli_types.dll	1.1.2.0
	policy.1.1.cli_types.dll	2.0.0.0
	cli_ure.dll	1.0.2.0
	policy.1.0.cli_ure.dll	2.0.0.0

+Last changed: $Date: 2006/02/20 16:59:10 $ + + \ No newline at end of file Propchange: incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/assemblyversioninghistory.html ------------------------------------------------------------------------------ svn:eol-style = native Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/com_lang_spec.htm URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/com_lang_spec.htm?rev=1206895&view=auto ============================================================================== --- incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/com_lang_spec.htm (added) +++ incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/com_lang_spec.htm Sun Nov 27 22:49:46 2011 @@ -0,0 +1,12 @@ + + + + + + + + + + + Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/connection_services.html URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/connection_services.html?rev=1206895&view=auto ============================================================================== --- incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/connection_services.html (added) +++ incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/connection_services.html Sun Nov 27 22:49:46 2011 @@ -0,0 +1,115 @@ + + + + + Acceptor / Connector services + + + + + + + + + + + +

Acceptor / Connector services

+ +

+ +

+ Overview
+ Description
+ Adding connection types
+

+ +

Overview

+ +

The services com.sun.star.io.Acceptor + and com.sun.star.io.Connector + allow for establishing a bytestream connection between two processes. + After establishing the connection, there is no longer a difference between the + client and the server.

Connections may be used, for example, by a remote bridge.

+ +

Description

+ +

The acceptor-service (or server) allows listening on a resource + for clients to connect. The connector-service (or client) allows for + connecting to a "listening resource". Both services + support socket and pipe connections. Pipes work only on the same + computer, as they use shared memory for data transfer. Sockets work + in a tcp/ip network environment. The string, for the connect/accept + calls, has the following format:

     <kind of connection>,<parametername1>=<value1>,...
+

for example:

+ +

+       socket,host=localhost,port=2000
+

Supported are the following:
Kinds of connection:: + - socket : TCP/IP-sockets +; + - pipe : +
+ Parameters for socket-connection: +: + - host: networkname of the computer +; + - port : TCP/IP-Port to listen on; + - tcpNoDelay : socket-tcpNoDelay-flag
+ can be set to 1 or 0. Should be 1 for + a UNO connection, as it may otherwise come + two 200 ms delays under certain circumstances. + Defaults to the system default (in general 0).

Parameters for a pipe-connection:: + - name : the name of the pipe

The connector component may be reused to initiate connections + to multiple processes. The acceptor component may only be used to + listen on one resource. Subsequent calls to the accept method must + pass the same connection description string.

+ +

Adding connection types

+ +

You can add your own connection type by implementing a service with the +name com.sun.star.connection.Connector.<connection-type> and +com.sun.star.connection.Acceptor.<acceptor-type> , where connection-type +is the name to be used, instead of socket.

+ + + + + +

+ + Author: Jörg Budischewski ($Date: 2004/11/27 08:53:24 $)
+ Copyright 2001 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303 USA. +

+ + Propchange: incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/connection_services.html ------------------------------------------------------------------------------ svn:eol-style = native Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/javavendorextension.sxw URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/javavendorextension.sxw?rev=1206895&view=auto ============================================================================== Binary file - no diff available. Propchange: incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/javavendorextension.sxw ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/library_unloading.html URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/library_unloading.html?rev=1206895&view=auto ============================================================================== --- incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/library_unloading.html (added) +++ incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/library_unloading.html Sun Nov 27 22:49:46 2011 @@ -0,0 +1,641 @@ + + + + + +Library Unloading + + + + + + + + +

Library Unloading API

+ +

+ +

The API enables an effective way of unloading libraries in a centralized way. +The mechanism ensures that libraries, which are being used are not unloaded. This prevents +crashes, if someone tries to execute library code after the library has been +unloaded. The unloading +mechanism currently only works with libraries which contain UNO services. A +library cannot be unloaded if one of the following conditions apply:

+ +

An instance is still referenced
A module has been loaded without registering it
The library contains a one-instance-service which has been instantiated
A service instance has been added to an UNO context
A factory has been registered with the service manager ( XSet::insert)

+ + +

Risks

+ +

The API is not entirely thread safe. Therefore, using this API might cause an +application to crash. This problem originates in the implementation of +component_canUnload. The function returns sal_True if the module can be unloaded, +which suggests that all component instances have died. But that makes it +necessary to recognize when an instance is about to destroy itself. This can be +easily achieved by employing a module wide counter, whose value represents the +number of running instances. A C++ component would increment the counter in its +constructor and decrement it in its destructor. A thread which is running a +destructor might be suspended after decreasing the counter. If now, the counter's +value is null, the module will be unloaded by the unloading mechanism when +someone called rtl_unloadUnusedLibraries. Then, when the suspended thread is +being scheduled again, it tries to run code which does not exist any longer, and +the application crashes. This is obviously a synchronization problem. But +synchronizing every call that could destroy a component, that is, synchronizing +XInterface::release, would entail a big performance loss. To solve this problem +one needs a mechanism that notices when a thread is out of the component's +library. There are ways of achieving this, but they all require +additional code on the client's side. Since that complicates the use of UNO and +is error prone as well, it would be desirable to encapsulate that mechanism +within proxy instances. This way, a client would interact with a proxy rather than +with the actual component. The proxy solution, however, takes up a lot of +performance and memory.

+ +

Library Requirements

+A library which supports unloading has to implement and +export a function called component_canUnload.

+ +

+sal_Bool SAL_CALL * component_canUnload( TimeValue* pTime); +

+ + + + + + + + + + +

Parameter	pTime - time since the module has not been used
Return	sal_True - module can be + unloaded, sal_False otherwise

+ + +

If the function returns sal_True then the module can be safely unloaded. That +is the case when there are no external references to code within the library. In +case a module houses UNO components, then the function must return sal_False +after the first factory has been handed out. The function then continues to +return sal_False as long as there is at least one object (factory or service +instance) which originated from the module.
+Libraries which not only contain UNO components (or none at all), have to provide a means to control +whether they can be unloaded or not; however, there is no concept of this, as yet.

+ + +

The argument pTime is an optional out-parameter and can be NULL. If the return value is +sal_True then pTime reflects a point in time, since when the module could have +been unloaded. Since that time, the function would have continually returned +sal_True up to the present. The value of pTime is important for the decision as +to whether a module will be unloaded. When someone initiates the unloading of modules by +calling rtl_unloadUnusedModules, then the caller can specify a time span to the +effect that only those modules are unloaded which have not been used at least for that +amount of time. If component_canUnload does not fill in pTime +and returns sal_True, then the module is +unloaded immediately.

+ +

component_canUnload is implicitly called by rtl_unloadUnusedModules. There is +no need to call the function directly. +

+ +

Registering Modules

+ + +

By registering a module, one declares that a module supports the unloading +mechanism. One registers a module by calling

+ +

+sal_Bool SAL_CALL rtl_registerModuleForUnloading( oslModule module); +

+ + + + + + + + + + +

Parameter	module - a module handle as is obtained by osl_loadModule
Return	sal_True - the module could be registered for unloading, + sal_False otherwise

+ + +

A module can only be unloaded from memory when it has been registered as many +times as it has been loaded. The reason is that a library can be +"loaded" several times by osl_loadModule within the same process. The +function will then return the same module handle because the library will +effectively only be loaded once. To remove the library from memory it is +necessary to call osl_unloadModule as often as osl_loadModule was called. The +function rtl_unloadUnusedModules calls osl_unloadModule for a module as many +times as it was registered. If, for example, a module has been registered one +time less than osl_loadModule has been called and the module can be unloaded, +then it needs a call to rtl_unloadUnusedModules, and an explicit call to +osl_unloadModule to remove the module from memory.

+ + +

A module must be registered every time it has been loaded; otherwise, the +unloading mechanism is not effective.

+ + +

Before a module is registered, one has to make sure that the module is in a +state that prevents it from being unloaded. In other words, +component_canUnload must return sal_False. +Assuming that component_canUnload returns sal_True +and it is registered, regardless, then a call to rtl_unloadUnusedModules causes +the module to be unloaded. This unloading can be set off by a different thread, +and the thread which registered the module is "unaware" of this. Then, +when the first thread tries to obtain a factory or calls another function in the +module, the application will crash -- because the module has already been unloaded. +Therefore, one has to ensure that the module cannot be unloaded before it is +registered. This is done by simply obtaining a factory from the module. As long +as a factory or some other object, which has been created by the factory, is +alive, the component_canUnload function will return sal_False.

+ + +

Loading and registering have to be done in +this order:

+ + +

load a library (osl_loadModule)
get the component_getFactory function and get a factory
register the module (rtl_registerModuleForUnloading

Usually, the service manager is used to obtain an instance of a service. The +service manager registers all modules which support the unloading mechanism. +When the service manager is used to get service instances, then one does not have +to bother about registering. +

+ +

The function

+ +

+void SAL_CALL rtl_unregisterModuleForUnloading( oslModule module); +

+ + + + + + +

Parameter	module - a module handle as is obtained by osl_loadModule

+ + +

revokes the registration of a module. By calling the function for a +previously registered module, one prevents the module from being unloaded by this +unloading mechanism; however, in order to completely unregister the module it is still +necessary to call the function as often as the module has been registered.

+ + +

rtl_unloadUnusedModules unregisters the modules which it unloads; +therefore, there is no need to call this function unless one means to prevent the +unloading of a module.

+ +

Notification Mechanism

+ +

The notification mechanism is provided for clients which need to do clean up, +such as, releasing cached references in order to allow modules to be unloaded. +As long as someone holds a reference to an object whose housing module supports +unloading, the module cannot be unloaded. +

Because of the inherent danger of crashing the application by using this API, all +instances which control threads should be registered listeners. On notification, +they have to ensure that their threads assume a safe state, that is, they +run outside of modules which could be unloaded and do not jump back into module +code as a result of a finished function call. In other words, there must not be +an address of the module on the thread's stack. +

Since current operating systems lack APIs in respect to controlling the position +of threads within libraries, it would be a major effort to comply with that +recommendation. The best and most efficient way of handling the unloading +scenario is to let all threads, except for the main thread, die in case of a +notification.

Listeners ( the callback functions) must be unregistered before the listener +code becomes invalid. That is, if a module contains listener code, namely +callback functions of type rtl_unloadingListenerFunc, then those functions must +not be registered when component_canUnload returns sal_True.

Listeners are registered with the following function:

+ +

+sal_Int32 SAL_CALL rtl_addUnloadingListener( rtl_unloadingListenerFunc callback,
+                                             void* this);
+

+ + + + + + + + + + + + + +

Parameter	callback - a function that is + called to notify listeners.
Parameter	this - a value to + distinguish different listener instances +
Return	identifier which is used in + rtl_removeUnloadingListener +

+ + +

callback is a function which is called when the unloading procedure has +been initiated by a call to rtl_unloadUnusedLibraries. The second argument is +used to distinguish between different listener instances and may be NULL. It will +be passed as an argument when the callback function is being called. The return +value identifies the registered listener and will be used for removing the +listener later on. If the same listener is added more then once, then every +registration is treated as if made for a +different listener. That is, a different cookie is returned and the callback +function will be called as many times as it has been registered.

+ +

The callback function is defined as follows:

+ +

+typedef void (SAL_CALL *rtl_unloadingListenerFunc)( void* +id); +

+ + + + + + +

Parameter	id - The value that has been passed + as second argument to rtl_addUnloadingListener

+ +

To unregister a listener call

+ +

+void SAL_CALL rtl_removeUnloadingListener( sal_Int32 +cookie ); +

+ + + + + + +

Parameter	+cookie is an identifier as returned by rtl_addUnloadingListener function. +

+ + +

+The callback functions can reside in modules which support the unloading +mechanism; therefore, a listener must revoke itself as listener, before it becomes +invalid, and the module can be unloaded. + + +

The service manager as obtained by createRegistryServiceFactory +(cppuhelper/servicefactory.hxx), createServiceFactory +(cppuhelper/servicefactory.hxx), bootstrap_initialComponentContext +(cppuhelper/bootstrap.hxx), and defaultBootstrap_initialComponentContext +(cppuhelper/bootstrap.hxx), registers itself as unloading listener. On being +notified, it releases references to factories which + +

have not been registered with the manager by calling XSet::insert
do not implement XUnloadingPreference
implement XUnloadingPreference and + XUnloadingPreference::releaseOnNotification returns true

+ + +

Unloading

+ +

To trigger the unloading of modules call the function

+ +

+void SAL_CALL rtl_unloadUnusedModules( TimeValue* +libUnused); +

+ + + + + + +

Parameter	+libUnused - span of time that a module must be +unused to be unloaded. The argument is optional. +

+ + +

The function notifies the unloading listeners in order to give them a chance to do +cleanup and get their threads in a safe state. Then, all registered modules are asked if they can be unloaded. +That is, the function calls component_canUnload on every registered module. +If sal_True is returned then osl_unloadModule is called for +each module as often as it was registered. +

+ +

A call to osl_unloadModule does not +guarantee that the module is unloaded even if its component_canUnload function +returns sal_True. +

+ +

The optional in-parameter libUnused specifies a period of time, for which a +library must be unused, in order to qualify for being unloaded. By using this +argument, one can counter the multithreading problem as described above. +It is the responsibility of the user of this function to provide a timespan +long enough to ensure that all threads are out of modules ( see +component_canUnload). +

+ +

The service managers which have been created by functions such as createRegistryServiceFactory +(declared in cppuhelper/servicefactory.hxx) are registered listeners and +release the references to factories on notification. Some factories are treated +differently, see paragraph about one-instance-services. +

+ +

Default Factories

+ +

Default factories can be obtained by means of helper functions, such as +createSingleComponentFactory. They keep a pointer to a function within a module that +creates a service instance; therefore, a library must not be unloaded as long as +there are default factories around. This is achieved by the factories which +increase the module counter on instantiation. When a factory is about to destroy +itself, then it decreases the counter. In order to realize this new functionality, +the relevant creator functions now have another parameter. These are the +new signatures ( for complete declarations refer to cppuhelper/factory.hxx).

+ +

+Reference< XSingleComponentFactory > SAL_CALL createSingleComponentFactory(
+	ComponentFactoryFunc fptr,
+	OUString const & rImplementationName,
+	Sequence< OUString > const & rServiceNames,
+	rtl_ModuleCount * pModCount = 0 )
+	SAL_THROW( () );
+	
+Reference< XSingleServiceFactory> SAL_CALL createSingleFactory(
+	const Reference< XMultiServiceFactory > & rServiceManager,
+	const OUString & rImplementationName,
+	ComponentInstantiation pCreateFunction,
+	const Sequence< OUString > & rServiceNames,
+	rtl_ModuleCount * pModCount = 0  )
+	SAL_THROW( () );
+	
+Reference< XSingleServiceFactory > SAL_CALL createOneInstanceFactory(
+	const Reference< XMultiServiceFactory > & rServiceManager,
+	const OUString & rComponentName, 
+	ComponentInstantiation pCreateFunction,
+	const Sequence< OUString > & rServiceNames,
+	rtl_ModuleCount * pModCount = 0  )
+	SAL_THROW( () );
+

rtl_ModuleCount is declared in sal/rtl. See paragraph Implementation below for further +information. +

+ +

Custom Factories

+ +

Custom factories have to be implemented in such a way that the component_canUnload +function of the module containing the service returns sal_False, as long as a +factory exists. Because programmers have full control over the factory +implementation they can choose whatever mechanism they think fit.

+ +

One-Instance-Services

+ +

A factory of a one-instance-service (OIS) always returns the same instance. So far, +the service manager caches references to the factories with the effect that an +instance lives as least as long as the service manager; the service manager +keeps the factory alive, which in turn keeps the service instance alive. That +fact has been taken advantage of by some developers to implement services whose +instances must not die; otherwise, important data would be lost. Now with the +advent of the unloading mechanism, we face the problem that factories do not +tell what kind of service they provide. But that is important for the service +manager to decide whether it releases a factory when being notified during the +unloading process. The service manager must not release the OIS; otherwise, the +following could happen: + +

An OIS instance is being referenced by its factory and +other clients. +
The service manager gets a notification and releases the factories. +
Now, the factory could die and release the OIS, or the factory lives on +because it is kept by other clients or the OIS itself. +
Either way, when the service manager is asked to create the service again, + then it will create a new instance and there are in +fact two instances of an OIS around. +
Consider that the former instance may contain crucial data, but a client cannot get to +them via the service manager anymore. +

+ +

The service manager currently keeps hard references to factories. To relieve +this problem with OISs the manager could keep weak references, but then the OIS +instance must keep a reference to its factory so that the weak reference, as kept +by the service manager, remains valid. That was not necessary, so far, and +developers were negligent, in this regard, with the result that a lot of OISs +needed to be changed. There is also a design flaw with the default OIS +factory ( createOneInstanceFactory), namely, the factory keeps a hard reference +to the OIS instance. If the instance is properly implemented and keeps a +reference to the factory, then there is a ring reference which causes a memory +leak. That, actually, calls for a new type of default factory which keeps a weak +reference to the service OIS instance. +

+ +

But even then, there is a problem that some OISs rely on the fact that they +stay alive once they have been created. An that is not achieved with the +idea as outlined above. +

+ +

To prevent the factory of an OIS from being released by the +service manager, it implements a new interface. +

+ +

+module com { module sun { module star { module uno { 
+interface XUnloadingPreference: com::sun::star::uno::XInterface
+{ 
+    boolean releaseOnNotification();
+}; 
+};};};};
+

+ +

The interface contains a function +releaseOnNotification, whose return value indicates whether a +notification listener should release its references to the implementing object, +in case of a notification. A listener should always ask objects for this +interface, be it factories or other objects. If objects do not implement that +interface then the listener should release references to those objects as is the +case when XUnloadingPreference::releaseOnNotification returns true.

+ +

This interface will be implemented by the default +factories. releaseOnNotification will return false when called on the +default one-instance-factory. The table shows what the other implementations +return:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Function that + creates the factory	Return value of +XUnloadingPreference::releaseOnNotification
createSingleComponentFactory	+sal_True
createSingleFactory	+sal_True
createOneInstanceFactory	+sal_False
createFactoryProxy	+Delegates call to the wrapped factory if it implements +XUnloadingPreference; otherwise, sal_True is returned.
createSingleRegistryFactory	+sal_True as long as the actual factory has not been loaded; otherwise, the call is +delegated to the loaded factory. If that factory does not implement +XUnloadingPreference, then sal_True is returned.
createOneInstanceRegistryFactory	+sal_True as long as the actual factory has not been loaded. When +the factory has been loaded and has created an instance, then the return value is +sal_False; otherwise, sal_True.

+ +

The service manager releases references to factories, even if they do not +implement this interface. This makes it necessary that custom factories of +one-instance-services need to implement this interface in order to guarantee +proper behavior of the service.

+ +

Implementation

+ +

To facilitate the implementation of modules and default factories which +support the unloading mechanism, we will introduce new types. +

+ +

+// rtl/unload.h
+typedef struct _rtl_ModuleCount
+{
+    void ( SAL_CALL * acquire ) ( struct _rtl_ModuleCount * that );
+    void ( SAL_CALL * release ) ( struct _rtl_ModuleCount * that );
+} rtl_ModuleCount;
+

+ +

Currently, this type is only used with the creator functions of default +factories. If default factories are used, then the module should have one +instance of rtl_ModuleCount that is initialized, while the module is being +loaded. The UDK will provide helper types and default function +implementations. +

+ +

+// rtl/unload.h
+typedef struct _rtl_StandardModuleCount
+{
+    rtl_ModuleCount modCount;
+    sal_Bool ( *canUnload ) ( struct _rtl_StandardModuleCount* this, 
+                               TimeValue* libUnused);
+    oslInterlockedCount counter;
+    TimeValue unusedSince;
+} rtl_StandardModuleCount;
+

+#define MODULE_COUNT_INIT \
+         { {rtl_moduleCount_acquire,rtl_moduleCount_release}, \
+            rtl_moduleCount_canUnload, 0, {0, 0} };
+

+ +

+rtl_moduleCount_acquire, rtl_moduleCount_release, and +rtl_moduleCount_canUnload are default implementations. +

+ +

To support unloading, one has to provide this code in a module.

+ +

+//one global instance of rtl_StandardModuleCount
+rtl_StandardModuleCount g_moduleCount= MODULE_COUNT_INIT;
+
+sal_Bool SAL_CALL  component_canUnload( TimeValue* libUnused)
+{
+    return g_moduleCount.canUnload( &g_moduleCount, libUnused);
+}
+
+// Example class for a service implementation
+MyService::MyService()
+{
+    g_moduleCount.modCnt.acquire( &g_moduleCount.modCnt);
+    ...
+}
+
+MyService::~MyService()
+{
+    ...
+    g_moduleCount.modCnt.release( &g_moduleCount.modCnt);
+}
+
+...
+

+ + +

+ Author: + Joachim Lingner. ($Date: 2004/12/15 12:49:51 $)
+ Copyright 2001 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303 USA. +

+ + Propchange: incubator/ooo/ooo-site/trunk/content/udk/common/man/spec/library_unloading.html ------------------------------------------------------------------------------ svn:eol-style = native

Module Description

Contents

+ Overview

Description of + module-description.dtd

+ Integration of the module description in the module(component)

Example:

Important Change

Notes

Versioning for assemblies of CLI-UNO Binding

Versioning Scheme

Compatible Changes and Policy Assemblies

Compatible Changes in cli_types.dll

Versioning of Policy Assemblies

Version History of Assemblies

Acceptor / Connector services

Contents

Overview

Description

Adding connection types

Library Unloading API

Risks

Library Requirements

Registering Modules

Notification Mechanism

Unloading

Default Factories

Custom Factories

One-Instance-Services

Implementation