incubator-ooo-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ksch...@apache.org
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 GMT
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 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<HTML>
+<HEAD>
+	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
+	<TITLE>Module Description</TITLE>
+	<META NAME="GENERATOR" CONTENT="StarOffice/5.2 (Win32)">
+	<META NAME="CLASSIFICATION" CONTENT="Module Description">
+	<META NAME="KEYWORDS" CONTENT="UNO,Module,Component,Description">
+</HEAD>
+<BODY LINK="#444488" VLINK="#444488" BGCOLOR="#eeeeff">
+<TABLE WIDTH=100% BORDER=0 CELLPADDING=4 CELLSPACING=0 STYLE="page-break-before: always">
+	<COL WIDTH=75>
+	<TR>
+		<TD BGCOLOR="#666699">
+			<H1 ALIGN=CENTER STYLE="margin-top: 0cm; text-decoration: none"><A HREF="http://www.openoffice.org/"><IMG SRC="../../images/open_office_org_logo.gif" NAME="Grafik1" ALT="OpenOffice" ALIGN=RIGHT WIDTH=109 HEIGHT=54 BORDER=0></A><FONT COLOR="#ffffff"><FONT SIZE=6>Module Description</FONT></FONT></H1>
+		</TD>
+	</TR>
+</TABLE>
+<HR SIZE=3 noshade>
+<TABLE WIDTH=100% BORDER=0 CELLPADDING=4 CELLSPACING=0 STYLE="page-break-before: always">
+	<COL WIDTH=75*>
+	<COL WIDTH=130*>
+	<COL WIDTH=51*>
+	<TR>
+		<TD COLSPAN=3 WIDTH=100% BGCOLOR="#666699">
+			<H3 ALIGN=LEFT STYLE="margin-top: 0cm; text-decoration: none"><FONT COLOR="#ffffff"><FONT SIZE=4>Contents</FONT></FONT></H3>
+		</TD>
+	</TR>
+	<TR>
+		<TD COLSPAN=3 WIDTH=100%>
+			<A HREF="#Overview">Overview</A><BR>
+			<A HREF="#Description">Description of module-description.dtd</A><BR>
+			<A HREF="#Integration_of_the_component_description_in_the_component">Integration 
+			of the module description in the component</A><BR>
+			<A HREF="#Example">Example</A><BR>
+		</TD>
+	</TR>
+	<TR>
+		<TD COLSPAN=3 WIDTH=100% BGCOLOR="#666699">
+			<H3 ALIGN=LEFT STYLE="margin-top: 0cm; text-decoration: none"><A NAME="Overview"></A>
+			<FONT COLOR="#ffffff"><FONT SIZE=4>Overview</FONT></FONT></H3>
+		</TD>
+	</TR>
+	<TR>
+		<TD COLSPAN=3 WIDTH=100%>
+			
+      <P>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. </P>
+		</TD>
+	</TR>
+	<TR>
+		<TD COLSPAN=3 WIDTH=100% BGCOLOR="#666699">
+			<H3><A NAME="Description"></A><FONT COLOR="#ffffff">Description of
+			module-description.dtd</FONT></H3>
+		</TD>
+	</TR>
+	<TR>
+		<TD COLSPAN=3 WIDTH=100%>
+			<P><CODE>module-description.dtd</CODE></P>
+			
+      <P><CODE>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;<BR>
+        &lt;!-- ... --&gt;<BR>
+        </CODE></P>
+      <P><CODE>&lt;!ENTITY % component-description-optional &quot;reference-docu|service-dependency|type&quot;&gt;<br>
+        &lt;!ENTITY % module-description-optional &quot;project-build-dependency|runtime-module-dependency|(%component-description-optional;)&quot;&gt;<br>
+        &lt;!ELEMENT module-description (module-name,component-description+,(%module-description-optional;)*)&gt; 
+        <BR>
+        &lt;!ELEMENT component-description (author,name,description,loader-name,supported-service+,(%component-description-optional;)*) 
+        &gt;<BR>
+        <BR>
+        &lt;!ELEMENT author (#PCDATA)&gt;<br>
+        &lt;!ELEMENT name (#PCDATA)&gt;<BR>
+        &lt;!ELEMENT description (#PCDATA)&gt;<br>
+        <BR>
+        &lt;!ELEMENT reference-docu EMPTY&gt;<br>
+        &lt;!ATTLIST reference-doc<br>
+        xmlns:xlink CDATA #FIXED &quot;http://www.w3.org/1999/xlink/Namespace&quot;<br>
+        xlink:type (simple) #FIXED &quot;simple&quot;<br>
+        xlink:href CDATA #REQUIRED<br>
+        xlink:role NMTOKEN #IMPLIED<br>
+        xlink:title CDATA #IMPLIED &gt;<br>
+        <br>
+        &lt;!ELEMENT module-name (#PCDATA)&gt;<BR>
+        &lt;!ELEMENT loader-name (#PCDATA)&gt;<BR>
+        &lt;!ELEMENT supported-service (#PCDATA)&gt;<BR>
+        &lt;!ELEMENT service-dependency (#PCDATA)&gt;<BR>
+        &lt;!ELEMENT project-build-dependency (#PCDATA)&gt;<BR>
+        &lt;!ELEMENT runtime-module-dependency (#PCDATA)&gt;<BR>
+        &lt;!ELEMENT language (#PCDATA)&gt;<BR>
+        &lt;!ELEMENT status EMPTY &gt;<BR>
+        &lt;!ATTLIST status value (under_construction | alpha | beta | final) 
+        #REQUIRED&gt;<BR>
+        &lt;!ELEMENT type (#PCDATA)&gt;</CODE></P>
+		<br>
+      <table width=95% border=1 cellpadding=5 cellspacing=3>
+        <tr valign=TOP> 
+          <td width=23%>author</td>
+          <td width=77%>The name of the person who has implemented the component</td>
+        </tr>
+        <tr valign=TOP> 
+          <td width=23%>name</td>
+          <td width=77%> 
+            <p>The implementation name of a component. <br>
+              (e.g., com.sun.star.comp.stoc.ORegistryServiceManager)</p>
+          </td>
+        </tr>
+        <tr valign=TOP> 
+          <td width=23%>description</td>
+          <td width=77%> 
+            <p>A short description which should be understandable to all people in 
+              the development process.</p>
+          </td>
+        </tr>
+        <tr valign=TOP> 
+          <td width=23%>reference-docu</td>
+          <td width=77%>specify an xlink to further documentation.</td>
+        </tr>
+        <tr valign=TOP> 
+          <td width=23%>module-name</td>
+          <td width=77%> 
+            <p>The name of a shared library without the system prefix (lib) or 
+              postfix (.so, .dll, ...)<br>
+              (e.g., smgr). An executable name. A Java class file name or the 
+              JAR name.</p>
+          </td>
+        </tr>
+        <tr valign=TOP> 
+          <td width=23%>loader-name</td>
+          <td width=77%> 
+            <p>The service name of the loader, which should be used to load the component.<br>
+              (e.g., com.sun.star.loader.SharedLibrary)</p>
+          </td>
+        </tr>
+        <tr valign=TOP> 
+          <td width=23%>supported-service</td>
+          <td width=77%> 
+            <p>All services supported by this component.<br>
+              (e.g., com.sun.star.registry.SimpleRegistry)</p>
+          </td>
+        </tr>
+        <tr valign=TOP> 
+          <td width=23%>service-dependency</td>
+          <td width=77%> 
+            <p>All services need this implementation.<br>
+              (e.g., com.sun.star.lang.RegistryServiceManager (very often the 
+              service manager component is used) )</p>
+          </td>
+        </tr>
+        <tr valign=TOP> 
+          <td width=23%>project-build-dependency</td>
+          <td width=77%> 
+            <p>All projects which are necessary.<br>
+              (e.g., cppuhelper, cppu, vos, sal, stl)</p>
+          </td>
+        </tr>
+        <tr valign=TOP> 
+          <td width=23%>runtime-module-dependency</td>
+          <td width=77%> 
+            <p>All projects which are used at runtime <br>
+              (e.g., cppu1, vos1$(COM), sal1)</p>
+          </td>
+        </tr>
+        <tr valign=TOP> 
+          <td width=23%>language</td>
+          <td width=77%> 
+            <p>The language in which the component is implemented.<br>
+              (e.g., C++)</p>
+          </td>
+        </tr>
+        <tr valign=TOP> 
+          <td width=23%>status</td>
+          <td width=77%> 
+            <p>The implementation state of the component.<br>
+              (under construction, alpha, beta, or final)</p>
+          </td>
+        </tr>
+        <tr valign=TOP> 
+          <td width=23%>type</td>
+          <td width=77%> 
+            <p>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.<br>
+              The special term "comprehensive" means that all type descriptions 
+              are built into the component.<br>
+              The type descriptions must be installed in the type repository (applicat.rdb).</p>
+          </td>
+        </tr>
+      </table>
+      <P><i>*$(COM) is the extension of the C++ compiler.</i><br>
+        <i>*$(SUPDCP) is the extension of a module which depends on an SUPD and the 
+        platform.</i></P>
+      <p>All components written in C++ need the bridge library from uno to C++ for 
+        scripting or remote communication. These are the <i>msci_uno.dll</i> with 
+        the MSC4.2 and the MSC6.0; and the <i>libsunpro5_uno.so</i> library with the 
+        SunPro 5.0 compiler.</p>
+      </TD>
+	</TR>
+	<TR>
+		<TD COLSPAN=3 WIDTH=100% BGCOLOR="#666699">
+			
+      <H3><A NAME="Integration_of_the_component_description_in_the_component"></A> 
+        <FONT COLOR="#ffffff">Integration of the module description in the module(component)</FONT></H3>
+		</TD>
+	</TR>
+	<TR>
+		<TD COLSPAN=3 WIDTH=100%>
+			
+      <P>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 <I>sal_Char*</I>. This function could be generated 
+        from the xml description by using the tool <A HREF="tools.html#xml2cmp">xml2cmp</A>. 
+        The generated source file must be built with the component and the C-function 
+        <CODE>component_getDescriptionFunc</CODE> must be exported.</P>
+			<P>Example for a simple registry component:</P>
+			<P><CODE><A HREF="tools.html#xml2cmp">xml2cmp</A>
+			-func simreg_desc.cxx simreg.xml</CODE>
+			</P>
+			<br>
+		</TD>
+	</TR>
+	<TR>
+		<TD COLSPAN=3 WIDTH=100% BGCOLOR="#666699">
+			<H3><A NAME="Example"></A><FONT COLOR="#ffffff">Example:</FONT></H3>
+		</TD>
+	</TR>
+	<TR>
+		<TD COLSPAN=3 WIDTH=100%>
+			<P>Description for the simple registry component, simreg.xml:
+			</P>
+			
+      <P><CODE>&lt;?xml version='1.0' encoding=&quot;UTF-8&quot;?&gt;<BR>
+        &lt;!DOCTYPE module-description PUBLIC &quot;-//W3C//DTD HTML 3.2//EN&quot; 
+        &quot;module-description.dtd&quot;&gt;<BR>
+        <BR>
+        &lt;module-description xmlns:xlink=&quot;&quot;http://www.w3.org/1999/xlink&quot;&gt;<br>
+        &lt;module-name&gt; simreg &lt;/module-name&gt;<br>
+        &lt;component-description&gt;<br>
+        <br>
+        &lt;author&gt; Juergen Schmidt &lt;/author&gt;<BR>
+        &lt;name&gt; com.sun.star.comp.stoc.SimpleRegistry &lt;/name&gt;<BR>
+        <BR>
+        &lt;description&gt;<BR>
+        This component provides access to a simple hierarchical registry. The registry 
+        based on one registry file.<BR>
+        &lt;/description&gt;<BR>
+        <BR>
+        &lt;loader-name&gt; com.sun.star.loader.SharedLibrary &lt;/loader-name&gt;<BR>
+        &lt;language&gt; c++ &lt;/language&gt;<br>
+        &lt;status value=&quot;final&quot;/&gt;<br>
+        </CODE></P>
+      <P><CODE>&lt;supported-service&gt; com.sun.star.registry.SimpleRegistry 
+        &lt;/supported-service&gt;<BR>
+        </CODE></P>
+      <P><CODE>&lt;type&gt; com.sun.star.lang.XTypeProvider &lt;/type&gt;<br>
+        &lt;type&gt; com.sun.star.lang.XServiceInfo &lt;/type&gt;<br>
+        &lt;type&gt; com.sun.star.lang.XSingleServiceFactory &lt;/type&gt;<br>
+        &lt;type&gt; com.sun.star.lang.XMultiServiceFactory &lt;/type&gt;<br>
+        &lt;type&gt; com.sun.star.registry.XSimpleRegistry &lt;/type&gt;<br>
+        &lt;type&gt; com.sun.star.registry.XRegistryKey &lt;/type&gt;<br>
+        &lt;type&gt; com.sun.star.uno.XAggregation &lt;/type&gt;<br>
+        &lt;type&gt; com.sun.star.uno.XWeak &lt;/type&gt;<br>
+        &lt;type&gt; com.sun.star.uno.TypeClass &lt;/type&gt;<br>
+        </CODE></P>
+      <P><CODE>&lt;/component-description&gt;</CODE></P>
+      <P><CODE> &lt;project-build-dependency&gt; cppuhelper &lt;/project-build-dependency&gt;<BR>
+        &lt;project-build-dependency&gt; cppu &lt;/project-build-dependency&gt;<BR>
+        &lt;project-build-dependency&gt; registry &lt;/project-build-dependency&gt;<BR>
+        &lt;project-build-dependency&gt; store &lt;/project-build-dependency&gt;<BR>
+        &lt;project-build-dependency&gt; vos &lt;/project-build-dependency&gt;<BR>
+        &lt;project-build-dependency&gt; sal &lt;/project-build-dependency&gt;<BR>
+        <BR>
+        &lt;runtime-module-dependency&gt; cppuhelper &lt;/runtime-module-dependency&gt;<BR>
+        &lt;runtime-module-dependency&gt; cppu1 &lt;/runtime-module-dependency&gt;<BR>
+        &lt;runtime-module-dependency&gt; reg1 &lt;/runtime-module-dependency&gt;<BR>
+        &lt;runtime-module-dependency&gt; store1 &lt;/runtime-module-dependency&gt;<BR>
+        &lt;runtime-module-dependency&gt; vos1$(COM) &lt;/runtime-module-dependency&gt;<BR>
+        &lt;runtime-module-dependency&gt; sal1 &lt;/runtime-module-dependency&gt;<BR>
+        <BR>
+        &lt;/module-description&gt; </CODE> </P>
+		</TD>
+	</TR>
+	<TR>
+		<TD COLSPAN=3 WIDTH=100%>
+			<HR SIZE=1 noshade>
+		</TD>
+	</TR>
+	<TR>
+		<TD WIDTH=50% BGCOLOR="#666699">
+			
+      <P ALIGN=LEFT><FONT COLOR="#ffffff"> Author: <A HREF="mailto:juergen.schmidt@germany.sun.com"><FONT COLOR="#ffffff">J&uuml;rgen 
+        Schmidt</FONT></A> ($Date: 2004/10/29 07:25:34 $)<BR>
+			<I>Copyright 2001 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303 USA.</I></FONT>
+			</P>
+		</TD>
+	</TR>
+	<TR>
+		<TD COLSPAN=3 WIDTH=100%>
+			<HR SIZE=1 noshade>
+		</TD>
+	</TR>
+</TABLE>
+</BODY>
+</HTML>

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 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+"http://www.w3.org/TR/2000/REC-xhtml1-20000126/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="refresh" content="3; URL=http://wiki.services.openoffice.org/wiki/Uno/Specifications/Type_Names"/>
+    <meta HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8">
+  </head>
+  <body>
+    <p class="Header">Redirecting....</p>
+  </body>
+</html>

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 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<HTML>
+<HEAD>
+	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1252">
+	<TITLE></TITLE>
+</HEAD>
+<BODY LANG="en-US" DIR="LTR">
+Author: Joachim Lingner<br>
+
+<H1>Important Change</H1>
+Because of the problem mentioned in Microsoft's knowledge base article 
+<a href="http://support.microsoft.com/kb/905238/en-us">905238 </a>
+we will increase the assembly versions for every new major and minor 
+version of OOo. 
+
+<H1>Notes</H1>
+<p>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. 
+</p>
+<p>
+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:
+</p>
+<pre>
+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		
+</pre>
+<p>
+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.
+</p>
+<p>
+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:
+</p>
+<pre>
+&lt;configuration&gt;
+ &lt;startup&gt;
+   &lt;supportedRuntime version="v2.0.50727" /&gt;
+ &lt;/startup&gt;
+&lt;/configuration&gt;
+</pre>
+
+<p>
+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.
+</p>
+<p>
+As of StarOffice 9 (OOo 3.0) this problem will not exist anymore, since that office
+requires at least a .NET Framework 2.0.
+</p>
+
+<H1>Versioning for assemblies of CLI-UNO Binding</H1>
+<P>This documents gives some background
+about the versioning applied to the assemblies which are part of the
+CLI-UNO binding. 
+</P>
+<P>
+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.</P>
+
+<P>
+For this document we assume that the
+reader has good knowledge of shared assemblies and policy assemblies.</P>
+
+<H1>Versioning Scheme</H1>
+<P>The version of an assembly consists of
+four parts:</P>
+<P>major.minor.build.revision</P>
+
+<P>The meaning of every part can be freely
+interpreted by developers. There is no need to use the parts exactly
+as their names indicate.</P>
+<P>For our assemblies we will use this
+convention:</P>
+
+<UL>
+	<LI>major:  expresses a major change</LI>
+	<LI>minor: expresses a minor incompatible change</LI>
+	<LI>build: expresses a compatible change.</LI>
+	<LI>revision: expresses a compatible change.</LI>
+</UL>
+
+<P>For incompatible changes we will
+increase the major part of the assembly.  The minor will remain
+unchanged, except for some urgent reasons. 
+</P>
+<P>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. 
+</P>
+<P>Usually we will increase the &ldquo;build&rdquo;
+as a result of bug fixes or new compatible features. 
+</P>
+<P>The &ldquo;revision&rdquo; will remain
+unchanged, except for some urgent reasons. 
+</P>
+<P>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.</P>
+
+<strong>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.</strong>
+
+
+<H1>Compatible Changes and Policy Assemblies</H1>
+<P>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.</P>
+
+<P>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:</P>
+<P>1.1 <br>
+1.2<br>
+1.3<br>
+
+<P>Because the newer versions are
+backwards compatible one could deploy these policy assemblies:<br>
+policy.1.1.cli_types.dll:   
+oldVersion: 1.1.0.0   newVersion: 1.2.0.0<br>
+policy.1.2.cli_types.dll:   
+oldVersion: 1.2.0.0   newVersion: 1.3.0.0</P>
+</P>
+<P>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:</P>
+
+<P>policy.1.1.cli_types.dll:   
+oldVersion: 1.1.0.0   newVersion: 1.3.0.0</P>
+
+<P>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):</P>
+<P>1.1, 1.2, 1.3, 1.4</P>
+<P>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:</P>
+<P>policy.1.1.cli_types.dll:   
+oldVersion: 1.1.0.0   newVersion: 1.4.0.0<br>
+policy.1.2.cli_types.dll:   
+oldVersion: 1.2.0.0   newVersion: 1.4.0.0<br>
+policy.1.3.cli_types.dll:   
+oldVersion: 1.3.0.0   newVersion: 1.4.0.0<br>
+
+<P>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.</P>
+
+
+<H2>Compatible Changes in cli_types.dll </H2>
+Changes to unpublished types (declared in unoidl WITHOUT the keyword &quot;published&quot;) 
+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.
+
+
+<H1>Versioning of Policy Assemblies</H1>
+<P>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.</P>
+<P>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 
+<br>
+version 1.0.0.0, redirecting from 1.1.0.0 to 1.1.1.0<br>
+version 2.0.0.0, redirecting from 1.1.0.0-1.1.1.0 to 1.1.2.0<br>
+</P>
+
+<P>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.</P>
+
+
+<hr>
+Last changed: $Date: 2008/05/07 13:22:48 $
+</BODY>
+</HTML>

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 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<HTML>
+<HEAD>
+	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1252">
+	<TITLE></TITLE>
+</HEAD>
+<BODY LANG="en-US" DIR="LTR">
+
+<H1>Version History of Assemblies</H1>
+<table border="0" cellspacing="0" cellpadding="0">
+<colgroup>
+  <col width="20">
+  <col width="*">
+  <col width="*">
+</colgroup>
+<tr>
+<th colspan="3" align="left">OpenOffice2, StarOffice 8 (src680 m124)</th>
+</tr>
+<tr>
+ <td></td>
+ <td>cli_basetypes.dll</td>
+ <td>1.0.0.0</td>
+</tr>
+<tr>
+ <td></td>
+ <td>cli_cppuhelper.dll</td>
+ <td>1.0.0.0</td>
+</tr>
+<tr>
+ <td></td>
+ <td>cli_types.dll</td>
+ <td>1.1.0.0</td>
+</tr>
+<tr>
+ <td></td>
+ <td>cli_ure.dll</td>
+ <td>1.0.0.0</td>
+</tr>
+<tr>
+ <td colspan="3"><br/></td>
+</tr>
+
+
+<th colspan="3" align="left">OOo 2.0.1, StarOffice 8 Product Update 1 (src680 m145)</th>
+</tr>
+<tr>
+ <td></td>
+ <td>cli_basetypes.dll</td>
+ <td>1.0.0.0</td>
+</tr>
+<tr>
+ <td></td>
+ <td>cli_cppuhelper.dll</td>
+ <td>1.0.1.0</td>
+</tr>
+<tr>
+ <td></td>
+ <td>policy.1.0.cli_cppuhelper.dll</td>
+ <td>1.0.0.0</td>
+</tr>
+<tr>
+ <td></td>
+ <td>cli_types.dll</td>
+ <td>1.1.1.0</td>
+</tr>
+<tr>
+ <td></td>
+ <td>policy.1.1.cli_types.dll</td>
+ <td>1.0.0.0</td>
+</tr>
+<tr>
+ <td></td>
+ <td>cli_ure.dll</td>
+ <td>1.0.1.0</td>
+</tr>
+<tr>
+ <td></td>
+ <td>policy.1.0.cli_ure.dll</td>
+ <td>1.0.0.0</td>
+</tr>
+<tr>
+ <td colspan="3"><br/></td>
+</tr>
+
+<th colspan="3" align="left">Current builds (as of SRC680m156)</th>
+</tr>
+<tr>
+ <td></td>
+ <td>cli_basetypes.dll</td>
+ <td>1.0.0.0</td>
+</tr>
+<tr>
+ <td></td>
+ <td>cli_cppuhelper.dll</td>
+ <td><strong>1.0.2.0<strong></td>
+</tr>
+<tr>
+ <td></td>
+ <td>policy.1.0.cli_cppuhelper.dll</td>
+ <td><strong>2.0.0.0</strong></td>
+</tr>
+<tr>
+ <td></td>
+ <td>cli_types.dll</td>
+ <td><strong>1.1.2.0</strong></td>
+</tr>
+<tr>
+ <td></td>
+ <td>policy.1.1.cli_types.dll</td>
+ <td><strong>2.0.0.0</strong></td>
+</tr>
+<tr>
+ <td></td>
+ <td>cli_ure.dll</td>
+ <td><strong>1.0.2.0</strong></td>
+</tr>
+<tr>
+ <td></td>
+ <td>policy.1.0.cli_ure.dll</td>
+ <td><strong>2.0.0.0</strong></td>
+</tr>
+
+
+
+</table>
+<P><BR><BR>
+</P>
+<hr>
+Last changed: $Date: 2006/02/20 16:59:10 $
+</BODY>
+</HTML>
\ 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 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+"http://www.w3.org/TR/2000/REC-xhtml1-20000126/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+        <meta http-equiv="refresh" content="3; URL=../draft/com_lang_spec.html" />
+<meta HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8">
+</head>
+<body>
+<p class="Header">Redirecting....</p>
+
+</body>
+</html>

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 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<HTML>
+<HEAD>
+	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1" />
+	<TITLE>Acceptor / Connector services</TITLE>
+	<META NAME="CLASSIFICATION" CONTENT="Acceptor / Connector services" />
+	<META NAME="KEYWORDS" CONTENT="UNO,Acceptor,Connector services" />
+	<style type="text/css">
+<!--
+h1 { text-align:center; margin-top: 0cm; text-decoration: none; color: #ffffff; font-size: 6; margin-top: 0.2cm}
+h2 { margin-top: 0.2cm; margin-bottom: 0.2cm; color: #ffffff; font-size: 4;
+    background-color: #666699 }
+dl {margin-bottom: 0.2cm;}
+dd {margin-bottom: 0.2cm;}
+dt {margin-bottom: 0.2cm;}
+-->
+</style>
+
+</HEAD>
+<body>
+<TABLE BORDER=0 CELLPADDING=4 CELLSPACING=0 bgcolor="#666699" width=100%>
+	<TR>
+	     <td>
+			<h1> Acceptor / Connector services </h1>
+		</td>
+		<td>
+			<A HREF="http://www.openoffice.org/">
+			<IMG SRC="../../../images/open_office_org_logo.gif" NAME="Grafik1"
+			ALT="OpenOffice.org" ALIGN=right BORDER=0 /></A>
+		</TD>
+	</TR>
+</TABLE>
+
+<h2>Contents</h2>
+<blockquote>
+			<A HREF="#Overview">Overview </A><br/>
+			<A HREF="#Description">Description</A><br/>
+			<A href="#Connection">Adding connection types</a></p>
+</blockquote>
+
+<h2><A NAME="Overview "></A> Overview </h2>
+
+<P>The services <CODE>com.sun.star.io.Acceptor</CODE>
+			and <CODE>com.sun.star.io.Connector</CODE>
+			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.</P>
+			<P>Connections may be used, for example, by a remote bridge.</P>
+
+<h2><A NAME="Description"></A> Description </h2>
+
+			<P>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:</P>
+			<pre>     <CODE>&lt;kind of connection&gt;,&lt;parametername1&gt;=&lt;value1&gt;,...</CODE>
+			</pre>
+			<P>for example:</P>
+
+<pre>
+       socket,host=localhost,port=2000
+</pre>
+			<DL>
+				<DT>Supported are the following:</DT>
+				<DT>Kinds of connection:</DT>
+				<DD>
+				- socket : TCP/IP-sockets
+				</DD><DD>
+				- pipe :
+				</DD>
+				<DT>
+				Parameters for <I>socket-connection</I>:
+				</DT>
+				<DD>
+				- host: networkname of the computer
+				</DD><DD>
+				- port : TCP/IP-Port to listen on</DD>
+				<DD>
+				- tcpNoDelay : socket-tcpNoDelay-flag<br/>
+				           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).</DD>
+			</DL>
+			<DL>
+				<DT>Parameters for a <I>pipe-connection</I>:</DT>
+				<DD>
+				- name : the name of the pipe</DD>
+			</DL>
+			<P>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.</P>
+
+<h2><A NAME="Connection"></A> Adding connection types </h2>
+
+<p>You can add your own connection type by implementing a service with the
+name com.sun.star.connection.Connector.&lt;connection-type&gt; and
+com.sun.star.connection.Acceptor.&lt;acceptor-type&gt; , where connection-type
+is the name to be used, instead of socket.</p>
+
+<table width=100% bgcolor=#666699>	
+	<TR>
+		<TD>
+			<FONT COLOR="#ffffff">
+			Author: <A HREF="mailto:joerg.budischewski@germany.sun.com"><FONT COLOR="#ffffff">J&ouml;rg Budischewski</FONT></A> ($Date: 2004/11/27 08:53:24 $)<br/>
+			<I>Copyright 2001 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303 USA.</I></FONT>
+		</TD>
+	</TR>
+</TABLE>
+</BODY>
+</HTML>

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 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html>
+<head>
+<meta http-equiv="Content-Language" content="en" />
+<meta http-equiv="Content-Type" content="text/html; charset=windows-1252" />
+<title>Library Unloading</title>
+<style type="text/css">
+<!--
+body,p,li,td {font-family:Arial,sans-serif;}
+h1 {text-align:center;color:#ffffff;font-size:20pt;font-weight:bold;font-family:Arial,sans-serif;}
+h2 {color:#ffffff;font-size:16pt;font-family:Arial,sans-serif;}
+h3 {color:#000000;font-size:14pt;font-family:Arial,sans-serif;}
+
+.sample_code { font-family:"Courier New",monospace;
+        font-size:10pt;
+	white-space:nowrap;}
+.code_key {font-family:"Courier New",monospace; font-style:normal;color:blue;}
+
+.code_deftype {font-family:"Courier New",monospace; font-style:normal;color:black;}
+.code_type {font-family:"Courier New",monospace; font-style:normal;color:black;}
+.code_defparam {font-family:"Courier New",monospace; font-style:italic; color:black;}
+.code_param {font-family:"Courier New",monospace; font-style:normal; color:black;}
+.code_comment {font-family:"Courier New",monospace; font-style:normal;color:green;}
+.code_defid {font-family:"Courier New",monospace; font-style:normal;color:black;}
+
+.code_var {font-family:"Courier New",monospace; font-style:normal;color:black;}
+th.func {font-family:"Courier New",monospace; text-align:left;color:blue;}
+th.normal {font-weight:bold:font-family:Arial,sans-serif;}
+-->
+</style>
+</head>
+
+<body>
+
+<TABLE WIDTH=100% BORDER=0 CELLPADDING=4 CELLSPACING=0>
+<TR><TD BGCOLOR="#666699">
+		<h1>Library Unloading API</h1>
+	</td><td bgcolor="#666699" width=200>
+      <A HREF="http://www.openoffice.org/"> 
+        <IMG SRC="../../../images/open_office_org_logo.gif" NAME="Grafik1" ALT="OpenOffice" ALIGN=right BORDER=0 /> 
+        </A>
+    </TD></TR>
+
+</TABLE>
+
+<p>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:</p>
+
+<ul>
+  <li>An instance is still referenced</li>
+  <li>A module has been loaded without registering it</li>
+  <li>The library contains a one-instance-service which has been instantiated</li>
+  <li>A service instance has been added to an UNO context</li>
+  <li>A factory has been registered with the service manager ( XSet::insert)</li>
+</ul>
+
+
+<h3>Risks</h3>
+
+<p>The API is not entirely thread safe. Therefore, using this API might cause an
+application to crash. This problem originates in the implementation of
+<code>component_canUnload</code>. The function returns <code>sal_True</code> 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 <code>rtl_unloadUnusedLibraries</code>. 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
+<code>XInterface::release</code>, 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.</p>
+
+<h3>Library Requirements</h3>
+<p>
+A library which supports unloading has to implement and 
+export a function called <code>component_canUnload</code>.</p>
+
+<div class="sample_code">
+<span class="code_type">sal_Bool</span> SAL_CALL * component_canUnload( <span class="code_type">TimeValue</span>* <span class="code_defparam">pTime</span>);
+</div>
+
+<table border="1" width="100%" cellspacing="0" cellpadding="3">
+  <tr>
+    <th class="func" width="9%" valign="top">Parameter</th>
+    <td width="91%">pTime - time since the module has not been used</td>
+  </tr>
+  <tr>
+    <th class="func" width="9%" valign="top">Return</th>
+    <td width="91%">sal_True - module can be
+      unloaded, sal_False otherwise</td>
+  </tr>
+</table>
+
+
+<p>If the function returns <code>sal_True</code> 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 <code>sal_False</code>
+after the first factory has been handed out. The function then continues to
+return <code>sal_False</code> as long as there is at least one object (factory or service
+instance) which originated from the module.<br/>
+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.</p>
+
+
+<p>The argument <code>pTime</code> is an optional out-parameter and can be NULL. If the return value is
+<code>sal_True</code> then <code>pTime</code> reflects a point in time, since when the module could have
+been unloaded. Since that time, the function would have continually returned
+<code>sal_True</code> up to the present. The value of <code>pTime</code> is important for the decision as
+to whether a module will be unloaded. When someone initiates the unloading of modules by
+calling <code>rtl_unloadUnusedModules</code>, 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 <code>component_canUnload</code> does not fill in <code>pTime</code> 
+and returns <code>sal_True</code>, then the module is
+unloaded immediately.</p>
+
+<p><code>component_canUnload</code> is implicitly called by <code>rtl_unloadUnusedModules</code>. There is
+no need to call the function directly.
+</p>
+
+<h3>Registering Modules </h3>
+
+
+<p>By registering a module, one declares that a module supports the unloading
+mechanism. One registers a module by calling</p>
+
+<div class="sample_code">
+<span class="code_type">sal_Bool</span> SAL_CALL rtl_registerModuleForUnloading( <span class="code_type">oslModule</span> <span class="code_defparam">module</span>);
+</div>
+
+<table border="1" width="100%" cellspacing="0" cellpadding="3">
+  <tr>
+    <th class="func" width="9%" valign="top">Parameter</th>
+    <td width="91%">module - a module handle as is obtained by osl_loadModule</td>
+  </tr>
+  <tr>
+    <th class="func" width="9%" valign="top">Return</th>
+    <td width="91%">sal_True - the module could be registered for unloading,
+      sal_False otherwise</td>
+  </tr>
+</table>
+
+
+<p>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
+&quot;loaded&quot; several times by <code>osl_loadModule</code> 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 <code>osl_unloadModule</code> as often as <code>osl_loadModule</code> was called. The
+function <code>rtl_unloadUnusedModules</code> calls <code>osl_unloadModule</code> for a module as many
+times as it was registered. If, for example, a module has been registered one
+time less than <code>osl_loadModule</code> has been called and the module can be unloaded,
+then it needs a call to <code>rtl_unloadUnusedModules</code>, and an explicit call to
+<code>osl_unloadModule</code> to remove the module from memory.</p>
+
+
+<p><b><i>A module must be registered every time it has been loaded; otherwise, the
+unloading mechanism is not effective.</i></b></p>
+
+
+<p>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,
+<code>component_canUnload</code>  must return <code>sal_False.</code>
+Assuming that <code>component_canUnload</code> returns <code>sal_True</code>
+and it is registered, regardless, then a call to <code>rtl_unloadUnusedModules</code> causes
+the module to be unloaded. This unloading can be set off by a different thread,
+and the thread which registered the module is &quot;unaware&quot; 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 <code>component_canUnload</code> function will return <code>sal_False</code>.</p>
+
+
+<p> Loading and registering have to be done in
+this order:</p>
+
+
+<ol>
+  <li>load a library (<code>osl_loadModule</code>)</li>
+  <li>get the <code>component_getFactory</code> function and get a factory</li>
+  <li>register the module (<code>rtl_registerModuleForUnloading</code></li>
+</ol>
+<p>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.
+</p>
+
+<p>The function</p>
+
+<div class="sample_code">
+<span class="code_key">void</span> SAL_CALL rtl_unregisterModuleForUnloading( <span class="code_type">oslModule</span> <span class="code_defparam">module</span>);
+</div>
+
+<table border="1" width="100%" cellspacing="0" cellpadding="3">
+  <tr>
+    <th class="func" width="9%" valign="top">Parameter</th>
+    <td width="91%">module - a module handle as is obtained by osl_loadModule</td>
+  </tr>
+</table>
+
+
+<p>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.</p>
+
+
+<p><code>rtl_unloadUnusedModules</code> 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.</p>
+
+<h3>Notification Mechanism </h3>
+
+<p>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.
+<p>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.
+<p>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.</p>
+<p>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 <code>rtl_unloadingListenerFunc</code>, then those functions must
+not be registered when <code>component_canUnload</code> returns <code>sal_True</code>.</p>
+<p>Listeners are registered with the following function:</p>
+
+<div class="sample_code">
+<pre>
+<span class="code_type">sal_Int32</span> SAL_CALL rtl_addUnloadingListener( <span class="code_type">rtl_unloadingListenerFunc</span> <span class="code_defparam">callback</span>,
+                                             <span class="code_key">void</span>* <span class="code_defparam">this</span>);
+</pre>					     
+</div>
+
+<table border="1" width="100%" cellspacing="0" cellpadding="3">
+  <tr>
+    <th class="func" width="9%" valign="top" rowspan="2">Parameter</th>
+    <td width="91%">callback - a function that is
+      called to notify listeners.</td>
+  </tr>
+  <tr>
+    <td width="91%">this - a value to
+      distinguish different listener instances
+    </td>
+  </tr>
+  <tr>
+    <th class="func" width="9%" valign="top">Return</th>
+    <td width="91%">identifier which is used in
+      rtl_removeUnloadingListener
+    </td>
+  </tr>
+</table>
+
+
+<p>callback is a function which is called when the unloading procedure has
+been initiated by a call to <code>rtl_unloadUnusedLibraries</code>. 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.</p>
+
+<p>The callback function is defined as follows:</p>
+
+<div class="sample_code">
+<span class="code_key">typedef void</span> (SAL_CALL *rtl_unloadingListenerFunc)( <span class="code_key">void</span>*
+<span class="code_defparam">id</span>);
+</div>
+
+<table border="1" width="100%" cellspacing="0" cellpadding="3">
+  <tr>
+    <th class="func" width="9%" valign="top">Parameter</th>
+    <td width="91%">id - The value that has been passed
+      as second argument to rtl_addUnloadingListener</td>
+  </tr>
+</table>
+
+<p>To unregister a listener call</p>
+
+<div class="sample_code">
+<span class="code_key">void</span> SAL_CALL rtl_removeUnloadingListener( <span class="code_type">sal_Int32</span>
+<span class="code_defparam">cookie</span> );
+</div>
+
+<table border="1" width="100%" cellspacing="0" cellpadding="3">
+  <tr>
+    <th class="func" width="9%" valign="top">Parameter</th>
+    <td width="91%">
+cookie is an identifier as returned by rtl_addUnloadingListener function.
+</td>
+  </tr>
+</table>
+
+
+<p>
+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.
+
+
+<p>The service manager as obtained by <code>createRegistryServiceFactory</code>
+(cppuhelper/servicefactory.hxx), <code>createServiceFactory</code>
+(cppuhelper/servicefactory.hxx), <code>bootstrap_initialComponentContext</code>
+(cppuhelper/bootstrap.hxx), and <code>defaultBootstrap_initialComponentContext</code>
+(cppuhelper/bootstrap.hxx), registers itself as unloading listener. On being
+notified, it releases references to factories which
+
+<ul>
+  <li>have not been registered with the manager by calling <code>XSet::insert</code></li>
+  <li>do not implement <code>XUnloadingPreference</code></li>
+  <li>implement <code>XUnloadingPreference</code> and
+    <code>XUnloadingPreference::releaseOnNotification</code> returns <code>true</code></li>
+</ul>
+
+
+<h3> Unloading </h3>
+
+<p>To trigger the unloading of modules call the function</p>
+
+<div class="sample_code">
+<span class="code_key">void</span> SAL_CALL rtl_unloadUnusedModules( <span class="code_type">TimeValue</span>*
+<span class="code_defparam">libUnused</span>);
+</div>
+
+<table border="1" width="100%" cellspacing="0" cellpadding="3">
+  <tr>
+    <th class="func" width="9%" valign="top">Parameter</th>
+    <td width="91%">
+libUnused - span of time that a module must be
+unused to be unloaded. The argument is optional.
+</td>
+  </tr>
+</table>
+
+
+<p>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 <code>component_canUnload</code> on every registered module. 
+If <code>sal_True</code> is returned then <code>osl_unloadModule</code> is called for 
+each module as often as it was registered.
+</p>
+
+<p><i><b> A call to <code>osl_unloadModule</code> does not
+guarantee that the module is unloaded even if its <code>component_canUnload</code> function
+returns <code>sal_True</code>.</b></i>
+</p>
+
+<p>The optional in-parameter <code>libUnused</code> 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
+<code>component_canUnload</code>).
+</p>
+
+<p>The service managers which have been created by functions such as <code>createRegistryServiceFactory</code>
+(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.
+</p>
+
+<h3> Default Factories </h3>
+
+<p>Default factories can be obtained by means of helper functions, such as
+<code>createSingleComponentFactory</code>. 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). </p>
+
+<div class="sample_code">
+<pre>
+<span class="code_type">Reference</span>&lt; <span class="code_type">XSingleComponentFactory</span> &gt; SAL_CALL createSingleComponentFactory(
+	<span class="code_type">ComponentFactoryFunc</span> <span class="code_param">fptr</span>,
+	<span class="code_type">OUString</span> <span class="code_key">const</span> &amp; <span class="code_param">rImplementationName</span>,
+	<span class="code_type">Sequence</span>&lt; <span class="code_type">OUString</span> &gt; <span class="code_key">const</span> &amp; <span class="code_param">rServiceNames</span>,
+	<b><span class="code_type">rtl_ModuleCount</span> * <span class="code_param">pModCount</span> = 0</b> )
+	SAL_THROW( () );
+	
+<span class="code_type">Reference</span>&lt; <span class="code_type">XSingleServiceFactory</span>&gt; SAL_CALL createSingleFactory(
+	<span class="code_key">const</span> <span class="code_type">Reference</span>&lt; <span class="code_type">XMultiServiceFactory</span> &gt; &amp; <span class="code_param">rServiceManager</span>,
+	<span class="code_key">const</span> <span class="code_type">OUString</span> &amp; <span class="code_param">rImplementationName</span>,
+	<span class="code_type">ComponentInstantiation</span> <span class="code_param">pCreateFunction</span>,
+	<span class="code_key">const</span> <span class="code_type">Sequence</span>&lt; <span class="code_type">OUString</span> &gt; &amp; <span class="code_param">rServiceNames</span>,
+	<b><span class="code_type">rtl_ModuleCount</span> * <span class="code_param">pModCount</span> = 0 </b> )
+	SAL_THROW( () );
+	
+<span class="code_type">Reference</span>&lt; <span class="code_type">XSingleServiceFactory</span> &gt; SAL_CALL createOneInstanceFactory(
+	<span class="code_key">const</span> <span class="code_type">Reference</span>&lt; <span class="code_type">XMultiServiceFactory</span> &gt; &amp; <span class="code_param">rServiceManager</span>,
+	<span class="code_key">const</span> <span class="code_type">OUString</span> &amp; <span class="code_param">rComponentName</span>, 
+	<span class="code_type">ComponentInstantiation</span> <span class="code_param">pCreateFunction</span>,
+	<span class="code_key">const</span> <span class="code_type">Sequence</span>&lt; <span class="code_type">OUString</span> &gt; &amp; <span class="code_param">rServiceNames</span>,
+	<b><span class="code_type">rtl_ModuleCount</span> * <span class="code_param">pModCount</span> = 0 </b> )
+	SAL_THROW( () );
+</pre>
+</div>
+<p> <code>rtl_ModuleCount</code> is declared in sal/rtl. See paragraph Implementation below for further
+information.
+</p>
+
+<h3>Custom Factories</h3>
+
+<p>Custom factories have to be implemented in such a way that the <code>component_canUnload</code>
+function of the module containing the service returns <code>sal_False</code>, as long as a
+factory exists. Because programmers have full control over the factory
+implementation they can choose whatever mechanism they think fit.</p>
+
+<h3> One-Instance-Services </h3>
+
+<p>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:
+
+<ul>
+<li>An OIS instance is being referenced by its factory and
+other clients.
+<li>The service manager gets a notification and releases the factories.
+<li> 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.
+<li>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.
+<li>Consider that the former instance may contain crucial data, but a client cannot get to
+them via the service manager anymore.
+</ul>
+
+<p>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 ( <code>createOneInstanceFactory</code>), 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.
+</p>
+
+<p>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.
+</p>
+
+<p>To prevent the factory of an OIS from being released by the
+service manager, it implements a new interface.
+</p>
+
+<div class="sample_code">
+<pre>
+<span class="code_key">module</span> com { <span class="code_key">module</span> sun { <span class="code_key">module</span> star { <span class="code_key">module</span> uno { 
+<span class="code_key">interface</span> XUnloadingPreference: com::sun::star::uno::XInterface
+{ 
+    <span class="code_type">boolean</span> releaseOnNotification();
+}; 
+};};};};
+</pre>
+</div>
+
+<p>The interface contains a function
+<code>releaseOnNotification</code>, 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 <code>XUnloadingPreference::releaseOnNotification</code> returns true.</p>
+
+<p> 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:</p>
+
+<table border="1" width="100%" cellspacing="0" cellpadding="3">
+  <tr>
+    <th class="normal" width="9%" valign="top">Function that
+      creates the factory</th>
+    <th class="normal"width="91%">Return value of
+XUnloadingPreference::releaseOnNotification</th>
+  </tr>
+  <tr>
+    <td width="9%" valign="top"><font size="-1">createSingleComponentFactory</font></td>
+    <td width="91%">
+<font size="-1">sal_True</font></td>
+  </tr>
+  <tr>
+    <td width="9%" valign="top"><font size="-1">createSingleFactory</font></td>
+    <td width="91%">
+<font size="-1">sal_True</font></td>
+  </tr>
+  <tr>
+    <td width="9%" valign="top"><font size="-1">createOneInstanceFactory</font></td>
+    <td width="91%"><font size="-1">
+sal_False</font></td>
+  </tr>
+  <tr>
+    <td width="9%" valign="top"><font size="-1">createFactoryProxy</font></td>
+    <td width="91%">
+<font size="-1">Delegates call to the wrapped factory if it implements
+XUnloadingPreference; otherwise, sal_True is returned.</font></td>
+  </tr>
+  <tr>
+    <td width="9%" valign="top"><font size="-1">createSingleRegistryFactory</font></td>
+    <td width="91%">
+<font size="-1">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.</font></td>
+  </tr>
+  <tr>
+    <td width="9%" valign="top"><font size="-1">createOneInstanceRegistryFactory</font></td>
+    <td width="91%">
+<font size="-1">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.</font></td>
+  </tr>
+</table>
+
+<p>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.</p>
+
+<h3> Implementation </h3>
+
+<p>To facilitate the implementation of modules and default factories which
+support the unloading mechanism, we will introduce new types.
+</p>
+
+<div class="sample_code">
+<pre>
+<span class="code_comment">// rtl/unload.h</span>
+<span class="code_key">typedef struct</span> _rtl_ModuleCount
+{
+    <span class="code_key">void</span> ( SAL_CALL * acquire ) ( <span class="code_key">struct</span> <span class="code_type">_rtl_ModuleCount</span> * <span class="code_param">that</span> );
+    <span class="code_key">void</span> ( SAL_CALL * release ) ( <span class="code_key">struct</span> <span class="code_type">_rtl_ModuleCount</span> * <span class="code_param">that</span> );
+} rtl_ModuleCount;
+</pre>
+</div>
+
+<p>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 <code>rtl_ModuleCount</code> that is initialized, while the module is being
+loaded. The UDK will provide helper types and default function
+implementations.
+</p>
+
+<div class="sample_code">
+<pre>
+<span class="code_comment">// rtl/unload.h</span>
+<span class="code_key">typedef struct</span> _rtl_StandardModuleCount
+{
+    <span class="code_type">rtl_ModuleCount</span> <span class="code_defid">modCount</span>;
+    <span class="code_type">sal_Bool</span> ( *canUnload ) ( <span class="code_key">struct</span> <span class="code_type">_rtl_StandardModuleCount</span>* <span class="code_param">this</span>, 
+                               <span class="code_type">TimeValue</span>* <span class="code_param">libUnused</span>);
+    <span class="code_type">oslInterlockedCount</span> <span class="code_defid">counter</span>;
+    <span class="code_type">TimeValue</span> <span class="code_defid">unusedSince</span>;
+} <span class="code_var">rtl_StandardModuleCount</span>;
+</pre>
+<pre>
+<span class="code_key">#define</span> MODULE_COUNT_INIT \
+         { {rtl_moduleCount_acquire,rtl_moduleCount_release}, \
+            rtl_moduleCount_canUnload, 0, {0, 0} };
+</pre>
+</div>
+
+<p>
+<code>rtl_moduleCount_acquire</code>, <code>rtl_moduleCount_release</code>, and
+<code>rtl_moduleCount_canUnload</code> are default implementations.
+</p>
+
+<p>To support unloading, one has to provide this code in a module.</p>
+
+<div class="sample_code">
+<pre>
+<span class="code_comment">//one global instance of rtl_StandardModuleCount</span>
+<span class="code_type">rtl_StandardModuleCount</span> <span class="code_var">g_moduleCount</span>= MODULE_COUNT_INIT;
+
+sal_Bool SAL_CALL  component_canUnload( <span class="code_type">TimeValue</span>* <span class="code_param">libUnused</span>)
+{
+    <span class="code_key">return</span> g_moduleCount.canUnload( &amp;g_moduleCount, libUnused);
+}
+
+<span class="code_comment">// Example class for a service implementation</span>
+MyService::MyService()
+{
+    g_moduleCount.modCnt.acquire( &amp;g_moduleCount.modCnt);
+    ...
+}
+
+MyService::~MyService()
+{
+    ...
+    g_moduleCount.modCnt.release( &amp;g_moduleCount.modCnt);
+}
+
+...
+</pre>
+</div>
+
+<table cellpadding="4" width="100%"><TR><TD WIDTH=100% BGCOLOR="#666699">
+      <FONT COLOR="#ffffff"> Author: <A HREF="mailto:Joachim.Lingner@germany.sun.com"> 
+        <FONT COLOR="#ffffff">Joachim Lingner</font></A>. ($Date: 2004/12/15 12:49:51 $)<br/>
+	<I>Copyright 2001 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303 USA.</I> </FONT> 
+    </TD></tr>
+</TABLE>
+</body>
+</html>

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



Mime
View raw message