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 [3/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/concept/uno_corba.html
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/concept/uno_corba.html?rev=1206895&view=auto
==============================================================================
--- incubator/ooo/ooo-site/trunk/content/udk/common/man/concept/uno_corba.html (added)
+++ incubator/ooo/ooo-site/trunk/content/udk/common/man/concept/uno_corba.html Sun Nov 27 22:49:46 2011
@@ -0,0 +1,1014 @@
+<!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"/>
+   <meta name="Author" content="Gast"/>
+   <title>The CORBA-UNO-Bridge</title>
+<style type="text/css">
+	<!--
+h1 { text-align:center; margin-top: 0.2cm; text-decoration: none; color: #ffffff; font-size: 6; margin-top: 0.2cm}
+h2 { margin-top: 0.2cm; margin-bottom=0.1cm; color: #ffffff;
+     background-color: #666699 }
+li {margin-bottom: 0.2cm;}
+dl {margin-bottom: 0.2cm;}
+dd {margin-bottom: 0.2cm;}
+dt {margin-bottom: 0.2cm;}
+-->
+</style>
+</head>
+<body>
+<table WIDTH="100%" BGCOLOR="#666699" summary="header">
+<tr> <td>
+<h1> The CORBA-UNO bridge </h1>
+</td><td>
+<a href="http://www.openoffice.org/">
+<img SRC="../../../images/open_office_org_logo.gif" NAME="Grafik1" ALT="OpenOffice.org" BORDER=0 height=54 width=114 align=right/>
+</a>
+</td</tr></table>
+
+<h2>Integrating into the GNOME desktop</h2>
+<blockquote>
+<a href="#introduction">Introduction</a><br/>
+- <a href="#design_concepts">Design concepts</a><br/>
+- <a href="#corba_access">Accessing UNO processes from CORBA and vice versa</a> <br/>
+- <a href="#oneway">Oneway calls</a><br/>
+- <a href="#object_lifetime">Object lifetime</a><br/>
+- <a href="#thread_identity">Thread identity</a><br/>
+- <a href="#object_identity">Object identity</a><br/>
+- <a href="#unknown_xinterface_mapping">Mapping of XInterface and GNOME::Unknown</a><br/>
+- <a href="#multiple_inheritance">Multiple inheritance</a><br/>
+- <a href="#type_information">Type information</a><br/>
+
+<a href="#implementation_concepts">Implementation concepts</a><br/>
+- <a href="#object_identifier">Object identifier</a><br/>
+- <a href="#corba_bridge_service">Corba bridge service</a><br/>
+- <a href="#connection_management">Connection management</a><br/>
+- <a href="#iiop_version">IIOP versions</a><br/>
+- <a href="#deployment_problem">Deployment for the GNOME orbit</a>
+</blockquote>
+
+
+<h2 id="introduction"> Introduction </h2>
+
+<!-- ************************ I N T R O D U C T I O N  *************************    -->
+<p>OpenOffice.org is a fully featured office productivity suite available for
+the most popular platforms. One aim of OpenOffice.org is to seamlessly
+integrate into each platform's most popular desktops.</p>
+
+<p>
+One major desktop on Linux and Solaris is developed by the open source GNOME project.
+The component model of the GNOME desktop is BONOBO, which is built on top of
+ORBIT, an open source CORBA ORB (Object Request Broker).
+</p>
+
+<p>
+To be able to communicate with the GNOME desktop, we want to develop a CORBA-UNO bridge
+using IIOP (<em>Internet inter orb protocol</em>). 
+
+<h4> Goals for the bridge </h4>
+The <strong>main goal</strong> is to get a CORBA-bridge that supports all features
+necessary to communicate with
+the GNOME desktop. This would e.g. allow to script OpenOffice.org from a GNOME scripting language.
+As a <strong>secondary goal</strong> an arbitrary CORBA-ORB should be able to directly access
+OpenOffice.org using the same bridge (for example on windows). This would allow to integrate
+OpenOffice.org seamlessly into any CORBA environment.
+
+<p> However, bridging UNO and CORBA is a non trivial task, as both component
+models
+are based on <a href="../comparison_uno_corba.html">different fundamental concepts</a>.
+This document should provide concepts about how to cope with most of these
+fundamental differences. It is supposed to grow within the next weeks as
+documentation either during and after development of the bridge. It should be a kind of an
+<em>open document</em>, as that important points brought up by the community will be
+inserted here.
+</p>
+
+<h4>What exactly can be done with a CORBA-UNO bridge?</h4>
+
+<p>
+An UNO-CORBA bridge allows to e.g. call methods at an UNO object (let's say a writer document)
+from the BONOBO object model. The caller does not need to know he is calling an UNO object,
+the only thing he does is invoking a method on a CORBA interface. It is not needed for the
+caller to have any UNO libraries in process nor is it needed for the callee to have any
+orbit libraries in process.
+</p>
+
+<p>
+The other way round, the bridge allows an UNO programmer to call CORBA objects from UNO. The
+UNO programmer does not have to have any special CORBA knowledge, he simply calls on
+UNO interfaces.
+</p>
+
+<p> To support callback interfaces, it should be possible to implement CORBA-interfaces in
+UNO and vice versa.
+
+<h2 id="design_concepts"> Design concepts </h2>
+<!-- ************************ C O N C E P T S  *************************    -->
+
+<h4><a name="corba_access">Accessing UNO processes from CORBA and vice versa</a></h4>
+
+<p>The main problem of accessing an object in a different process is that you
+   need the IOR (Interoperable Object Reference) of this object in the other
+   process. The most common way is to have a daemon like process (typically a
+   namingservice or a implementation repository) that administrates IORs.
+   Every CORBA application can access this daemon to retrieve an IOR of the
+   desired object.</p>
+
+<p>The root IOR of this daemon process must somehow be brought to every single
+   application. How this is done, is orb dependent (possible solutions are a
+   certain file on the filesystem, configuration files, environment variables,
+   command line parameters, etc).</p>
+
+<p>The mechanism how to access this IOR should be made abstract to allow to
+   implement a different mechanism for different orbs. A simple interface as
+   following one should be sufficient.</p>
+
+<table BORDER=0 CELLSPACING=0 CELLPADDING=4 WIDTH="100%"  >
+<tr>
+<td COLSPAN="3" WIDTH="100%" BGCOLOR="#FFFFC0">
+<pre>
+      interface XRootIORProvider
+      {
+        /** tries to locate a corba root object using a specified method.
+
+		Note : In general, no CORBA bridge needs to be instantiated.
+		       This IOR can be retrieved by some other mechanism.
+		       
+	   @param howToFindObject
+	          format: kind of service to find, comma separated attribute 
+		      list e.g. "GnomeResolverFromX,display=jbu-11096:1" or 
+			  similar.
+			  
+	   @return stringified IOR, if a namingservice could be found, 
+		      otherwise an empty string.
+	 */	   
+	 string findRootIOR( string howToFindObject );
+      };
+</pre>
+</td>
+</tr>
+</table>
+<p>returned stringified IOR can later be used to create an UNO interface
+   reference to the object. Therefor will exist an CORBA bridge interface with
+   a method</p>
+
+<table BORDER=0 CELLSPACING=0 CELLPADDING=4 WIDTH="100%"  >
+<tr>
+<td COLSPAN="3" WIDTH="100%" BGCOLOR="#FFFFC0">
+<pre>     
+     interface XCorbaBridge
+     {
+	[...]
+	Any resolveByStringifiedIOR( string sIOR );
+	[...]
+     };
+</pre>
+</td>
+</tr>
+</table>
+<p>The returned Any contains an UNO interface reference. This can be used to
+   directly make calls.</p>
+     
+     <ul>
+     <li><p>The gnome case (ORBIT)</p>
+       <p>Up to version 1.3, GNOME uses the gnorba framework. From version 1.4 (yet to come)
+	  on, the oaf (object activation framework) is used. However, as this bridge is
+	  also in a early development cycle, we will focus on the more powerful oaf-framework.
+
+	  <p> Oaf is a mix of an implementation repository and the CORBA trading service.
+	  Certain services can be advertised using properties (name-value pairs). Services
+	  can be accessed by doing queries on properties. Accessing a service can either
+	  result in starting a new process or simply returning the object reference
+	  of an existing instance. Services can either be described within ini-files
+	  or can be inserted at runtime (e.g. when a service starts up, it inserts itself
+	  in the oaf). 
+	  	  
+	  <p>
+	  The suggested way to use the oaf is to link against the oaf C-library and use
+	  C-API functions. However the oaf offers most of its functionality via
+	  idl-interfaces (e.g. in process shared library services can not be instantiated 
+	  via the idl-interface).
+
+	  <p>
+	  IMHO the best way to access oaf would be to implement an RootIORProvider service,
+	  that implements the XRootIORProvider interface. The service may be started in
+	  a separate process, if needed.
+	  The implementation is linked linked against liboaf.so and uses the C-API to retrieve
+	  the stringified IOR of the root object. The original process then instantiates
+	  a CORBA bridge and tries to access it using the resolveByStringifiedIOR() method (without
+	  using the interface intermediate process anymore).
+
+	  <p> The service may later become simpler, if the IOR can be retrieved via a command
+	  line tool or a environment variable.
+	   
+     <li> other CORBA orbs
+          [...]
+     </ul>
+    <p>
+     So far the problem, how OpenOffice.org can access CORBA services, is solved. But what is
+     the other way round? How can we get the OpenOffice.org servicemanager into the oaf? There
+     are multiple possible solutions.
+
+     </p>
+     <ol>
+     <li><p>Insert the UNO servicemanager IOR into oaf at Office startup.
+          This works fine as long as the office is running.
+		  </p></li>
+
+     <li><p>
+     Add oafinfo-files to the oaf, so that the oaf itself can start the office, if
+     needed. The office must then behave like an arbitrary GNOME service, interpret
+     command-line parameters and use the  oaf-library to do some non-corba-communication
+     with the oaf. It still needs to be investigated, if this has any problems.
+	 </p></li>
+
+     <li><p>
+     (and in my eyes the CORBA way to do it) Have our own UNO daemon,
+     that itself works as implementation repository for UNO services (such as the office).
+     The office servicemanager is configured in the oaf simply by a persistent
+     stringified IOR, but uses the host/port entries of the UNO daemon. When someone
+     tries to make a call on the object, the UNO daemon starts up the office
+     and replies a LOCATION_FORWARD iiop-message with the appropriate host/port entries. To allow
+     this , ORBIT must support LOCATION_FORWARD messages (does it?).
+	 </p></li>
+
+     <li><p>
+     Have a UNO daemon, that runs continuously. It implements
+     the oaf OAF::ObjectDirectory interface and inserts it into the running oaf.
+     It starts the office on demand using the office-specific command line parameters.
+	 </p></li>
+     </ol>
+
+          <p>
+     Which solution will be used is not yet determined.
+
+<h4><a name="oneway">Oneway calls</a></h4>
+<p>
+CORBA does not guarantee the sequence of calls for oneways. However,
+a lot of UNO interfaces and implementations rely on that (think of the sequence
+<code> acquire(),acquire(),release()</code> gets mixed up to
+<code> acquire(),release(),acquire()</code>, this would be fatal).
+So I think, it is inevitable to
+export all UNO-oneway-methods as synchronous to CORBA.
+
+<p> Oneway with CORBA interfaces however should be supported, as there it must have been
+decided during design, that the series of calls is not important.
+
+<p> Is a special solution for
+    GNOME possible (maybe the implementation guarantees the sequence of calls)?
+    
+     
+<h4><a name="object_lifetime">Object lifetime</a></h4>
+<p>
+Several use cases must be taken into account when talking about object lifetime.
+</p>
+
+<table align=center border=5>
+<tr>
+<td align=center >
+use case
+</td>
+<th colspan=2 align=center>
+object used by
+</th>
+<th colspan=2 align=center>
+object implemented in
+</th>
+<th colspan=2 align=center>
+interface originally defined in
+</th>
+</tr>
+
+<tr>
+<td align=center>
+#
+</td>
+<td align=center>
+CORBA
+</td>
+<td  align=center>
+UNO
+</td>
+<td align=center>
+CORBA
+</td>
+<td align=center>
+UNO
+</td>
+<td align=center>
+CORBA
+</td>
+<td align=center>
+UNO
+</td>
+</tr>
+
+<tr>
+<td align=center>1.</td>
+<td></td>
+<td align=center>x</td>
+<td align=center>x</td>
+<td></td>
+<td align=center>x</td>
+<td></td>
+</tr>
+
+<tr>
+<td align=center>2.</td>
+<td></td>
+<td align=center>x</td>
+<td align=center>x</td>
+<td></td>
+<td></td>
+<td align=center>x</td>
+</tr>
+
+<tr>
+<td align=center>3.</td>
+<td align=center>x</td>
+<td></td>
+<td></td>
+<td align=center>x</td>
+<td align=center>x</td>
+<td></td>
+</tr>
+
+<tr>
+<td align=center>4.</td>
+<td align=center>x</td>
+<td></td>
+<td></td>
+<td align=center>x</td>
+<td></td>
+<td align=center>x</td>
+</tr>
+
+</table>      
+<ol>
+<li> CORBA object implementing an CORBA-interface used from UNO <br/>
+The interface-definition
+is imported from CORBA to be accessible for the UNO runtime. The interface is flagged as
+being a CORBA interface. For the UNO runtime, the interface is derived from
+<code>XInterface</code>.
+
+<p>
+The UNO-CORBA bridge must create a proxy within the UNO process, it must implement
+<code>acquire()</code>, <code>release()</code> and <code>queryInterface()</code>. As the
+interface does not support a queryInterface method, it must be dummy-implemented, so that it
+supports a query for the interface and all its superclasses.
+
+<p> The lifetime of the proxy bears no problem, it is simply refcounted. If the refcount drops
+to zero, the proxy dies silently, no message is transported to the original object.
+
+<li> CORBA object implementing a UNO-interface used from UNO <br/>
+The UNO interface-definition must be imported into the CORBA typelibrary and stub/proxy-code
+must be generated for the CORBA-process.
+The object must implement itself <code>acquire()</code>, <code>release()</code>
+and <code>queryInterface()</code> and maybe <code>getCorbaID()</code>
+(see <a href="#object_identity">below</a>).
+
+<p> Here the lifetime problem becomes a little difficult. Let us first have a look at
+lifetime handling in a UNO-UNO interprocess-bridge.</p>
+<img src="../images/passing_interface_reference_uno_uno.jpg" alt="Uno interface" />
+
+<p>
+The <code>pass()</code> call shall pass an interface reference as its first argument. The
+UNO-UNO bridge acquires the object on caller side, the bridge on callee side knows, that
+it gets an acquired interface.
+
+<p>
+This cannot be done with a general CORBA orb, because the orb runtime doesn't know,
+that it should call acquire implicitly. How can this be solved? In general,
+the callee must acquire the interface, when it wants to keep it.
+The UNO-CORBA bridge would acquire it in advance and release it again when
+the newly created proxy is destroyed. Thus the UNO-developer wouldn't need to do
+anything by hand.
+
+<p>
+<img src="../images/passing_interface_reference_corba_uno.jpg" alt="Corba uno interface"/>
+<p>
+This does  NOT WORK FOR ONEWAY CALLS. This technique
+may also be inefficient, because every mapped interface requires a (maybe synchronous)
+<code>acquire()</code> call. However, as GNOME does refcounting this way, the UNO-CORBA
+bridge will also do it this way thus ignoring the problem.
+
+<p>
+<b> Acquire in advance</b><br/>
+Another possibility would be to make the CORBA developer responsible for this, if
+he passes a object-reference, he must call <code>acquire</code> in advance. This is 
+very error prone (think about any, structs and sequences, that all would need to be
+parsed for object references), however this is the only way how oneway requests
+can pass object references. This could be introduced only for oneway calls, but as
+in general it cannot be seen from the method signature, whether a call is oneway or
+synchronous, this would be very confusing.
+<p>
+<img src="../images/passing_interface_reference_acquire_in_advance.jpg" alt="reference interface"/>
+
+<p>
+Another solution would be to simply ignore <code>acquire()</code> and <code>release()</code>,
+but how shall the CORBA side then get to know, when an instance can be discarded, as the
+OpenOffice.org API is not designed for telling the objects something like this?
+
+<li> UNO object implementing a CORBA-interface used from CORBA <br/>
+The CORBA-interface is derived from <code>XInterface</code> in the UNO process. So for the
+object itself, the lifetime must be controlled via <code>acquire()</code> and
+<code>release()</code> calls.
+
+<p>
+The problem is, that when the UNO-object is once mapped out to a CORBA process, the
+UNO-CORBA-bridge must hold a reference to the object and does not know, when to release it.
+(The CORBA developer does not see the <code>acquire()</code> and <code>release()</code>
+methods).
+
+<p>
+Often, CORBA interfaces are somehow designed to control lifetime of objects. For example,
+an object has an explicit <code>destroy()</code> method, on which the documentation states
+that the instance is destroyed and the object becomes unreachable. However the bridge
+can't read documentation ( :o) ), so there must be mechanism, that the implementation
+can tell the bridge, that it does not need to be held anymore.
+
+<p> As the implementation naturally does not know the bridge instance, there
+should be implemented
+a broadcast/listener mechanism to broadcast this message to all CORBA bridge instances.
+There could be a singleton service, that knows all CORBA bridges (maybe a factory,
+that creates all CORBA bridges.)</p>
+
+<table BORDER=0 CELLSPACING=0 CELLPADDING=4 WIDTH="100%"  >
+<tr>
+<td COLSPAN="3" WIDTH="100%" BGCOLOR="#FFFFC0">
+<pre>
+interface XCorbaBridgeFactory : XInterface
+{
+   XCorbaBridge createBridge( ... );
+
+   void fireDisposeObject( [in] XInterface disposedObject ); 
+}
+</pre>
+</td>
+</tr>
+</table>
+<br/>
+<li> UNO object implementing a UNO interface used from CORBA
+   Here the CORBA developer sees the <code>acquire()</code>, <code>release()</code>,
+   <code>queryInterface()</code> and <code>getCorbaID()</code> method. Because the
+   CORBA runtime does not support <code>acquire()</code> directly, the CORBA developer
+   must call <code>acquire()</code> and <code>release()</code> by hand.
+
+   <p>
+   Interface references returned by a method (as return value or out-parameter) are
+   supposed to be acquired, thus if the references must be
+   released by the CORBA programmer, if not needed anymore.
+   This means, that a CORBA programmer who implements
+   a UNO-interface methods, that returns an interface reference (via return value or
+   out-parameter) must acquire the interface beforehand. 
+
+
+</ol>
+
+<h4><a name="thread_identity">Thread identity</a></h4>
+   UNO interprocess bridges preserve thread identity, that means when process A calls
+   process B and in the same request process B calls again process A, the same thread
+   waiting in process A will take over the new request. This ensures that thread
+   local resources (locked mutexes, thread local storage, etc.) are preserved.
+
+<p>
+   An arbitrary CORBA orb may not support thread identity. The id can be inserted into
+   the service context list. If the CORBA process supports it, it is fine, if not
+   thread identity cannot be preserved, this could result in deadlocks.
+
+<p>
+   The service context id <em>LogicalThreadId</em> can be reused, that was original
+   designed for DCOM interoperability. An appropriate ID for this should be applied at
+   the omg.
+</p>
+
+<h4><a name="object_identity">Object identity</a></h4>
+<p>CORBA does not guarantee object identity , but several UNO interfaces
+   (especially container and broadcaster/listener interfaces) rely on that.  I
+   would like to introduce a typical example, where such a problem occurs.</p>
+
+<table BORDER=0 CELLSPACING=0 CELLPADDING=4 WIDTH="100%"  >
+<tr>
+<td COLSPAN="3" WIDTH="100%" BGCOLOR="#FFFFC0">
+<pre>
+interface XListener :  XInterface
+{
+...
+};
+
+interface XBroadcaster : XInterface
+{
+   void addListener( [in] XListener listener );
+   void removeListener( [in] XListener listener );
+}
+</pre>
+</td>
+</tr>
+</table>
+
+<p>The XBroadcaster interface is implemented by the UNO object U (in the UNO
+   process), the XListener interface is implemented by the CORBA object C  in
+   the CORBA process.  Now there is an actor, that wants to add C into U and
+   later remove C from U.</p>
+
+     <p>
+     Adding is no problem, but removing is. The CORBA bridge in the UNO process must know,
+     that the reference passed with the removeListener() method, is the same, that was
+     passed with the addListener() method. However, it can't know for sure just by seeing
+     the object reference, because in CORBA it is possible, that two object references
+     denote one object.
+
+     <p> The problem is even worse, because the removal may work most of the time
+     (object references passed by add/remove are identical),
+     but sometimes not.
+
+     <p> Note, that the check for object identity in UNO is done by comparing the
+         pointer of the XInterface proxy. So a UNO-CORBA bridge must ensure,
+	 that interfaces belonging to the same object get the same proxy. This must be
+	 done for every interface reference, because the bridge does not know in advance,
+	 if there will be a check for object identity.
+
+     <p>
+     Possible solutions for this problem are :
+
+     <ol>
+	 <li><p>Leave the problem of the object identity to the CORBA developer.
+	      The UNO-base interface XInterface gets a new method in CORBA :</p>
+<table BORDER=0 CELLSPACING=0 CELLPADDING=4 WIDTH="100%">
+<tr>
+<td COLSPAN="3" WIDTH="100%" BGCOLOR="#FFFFC0">
+<pre>
+interface XInterface
+{
+      any queryInterface( [in] Type type );
+      [oneway] void acquire();
+      [oneway] void release();
+      /**
+        returns an ID, that uniquely identifies this object.
+
+	The ID must be globally unique, e.g. a GUID.
+      */
+      sequence< byte > getCorbaID();
+};
+</pre>
+</td>
+</tr>
+</table>
+	<p>Every time, an object is mapped from CORBA to UNO, the UNO-CORBA bridge
+	checks, if it knows
+	the reference already. If it is new, it calls getCorbaID() at the object.
+	In case, the bridge knows the object already, the existing proxy is
+	used, so that object identity is guaranteed.
+	</p>
+
+	<p>This works (as long as a unique id is provided), but it may be
+	   excruciatingly slow for some applications (for every newly mapped
+	   interface, 1 remote call is necessary, think of a sequence&lt;
+	   XInterface &gt; with 100 elements, and you know what I mean :o) ).  This
+	   is also a burden for the CORBA developer.</p>
+
+	<p> There are three solutions, to avoid the performance problem 
+
+	<ol>
+	<li><p>
+	The UNO-CORBA bridge
+	itself exports the interface XRemoteCorbaBridge interface (how can it be offered
+	to the client?).
+	</p>
+
+<table BORDER=0 CELLSPACING=0 CELLPADDING=4 WIDTH="100%"  >
+<tr>
+<td COLSPAN="3" WIDTH="100%" BGCOLOR="#FFFFC0">
+<pre>
+interface XRemoteCorbaBridge
+{
+    [oneway] void associateInstanceWithId(
+                  [in] any instance, [in] sequence< byte > corbaID );
+}
+</pre>
+</td>
+</tr>
+</table>
+	<p>In the any, the object reference is inserted, that is going to be mapped
+	in near future.
+	The sequence&lt; byte &gt; contains the id, that would be returned by the
+	getCorbaID()-method.
+	This would lead to the following code (I use UNO C++ notation, because I don't know
+	a CORBA C++ mapping very good):</p>
+<table BORDER=0 CELLSPACING=0 CELLPADDING=4 WIDTH="100%"  >
+<tr>
+<td COLSPAN="3" WIDTH="100%" BGCOLOR="#FFFFC0">
+<pre>
+  Reference&lt; XRemoteCorbaBridge &gt; rRemoteCorbaBridge =
+                                        ... (got from somewhere);
+  Reference&lt; XBroadcaster &gt; rBroadcaster = ...(got from somewhere);
+  Reference&lt; XListener &gt; rListener = ... ( got from somewhere);
+
+  Any myAny;
+  myAny &lt;&lt;= rListener;
+  rRemoteCorbaBridge-&gt;associateInstanceWithId(
+    	                myAny, rListener-&gt;getCorbaID() );
+  rBroadcaster-&gt;addListener( rListener );
+
+  // and later
+  ...
+
+  rRemoteCorbaBridge-&gt;associateInstanceWithId(
+	                    myAny, rListener-&gt;getCorbaID() );
+  rBroadcaster-&gt;removeListener( rListener );
+</pre>
+</td>
+</tr>
+</table>
+	<p>(The second associateInstanceWithId call is not necessary, when the same
+	reference is used).</p>
+
+	<p>One advantage of this solution is, that the CORBA developer must only
+	care for the problem, where performance is needed, but it looks quite
+	ugly.</p>
+
+	<p>Because CORBA does not guarantee the series of oneway calls, it is not certain
+	, that this will work as expected (but quite likely for most ORB implementations).
+	However as this is only an optimization, the code will still works.
+	</p></li>
+
+	<li><p>The orb could be modified, that it inserts into the IOR a special
+	profile
+	which includes the object identifier. Such a profile must be specified and a
+	tag must be applied at the omg.</p></li>
+
+	<li><p>For every UNO interface, a struct is generated, for example:</p>
+<table BORDER=0 CELLSPACING=0 CELLPADDING=4 WIDTH="100%"  >
+<tr>
+<td COLSPAN="3" WIDTH="100%" BGCOLOR="#FFFFC0">
+<pre>
+      struct container_XListener
+      {
+          XListener reference;
+	  sequence&lt; byte &gt; corbaId;
+      };
+</pre>
+</td>
+</tr>
+</table>
+	<p>This struct replaces every occurrence of an interface reference such a way,
+	that e.g. the XBroadcaster interface looks like</p>
+<table BORDER=0 CELLSPACING=0 CELLPADDING=4 WIDTH="100%"  >
+<tr>
+<td COLSPAN="3" WIDTH="100%" BGCOLOR="#FFFFC0">
+<pre>
+interface XBroadcaster : XInterface
+{
+   void addListener( [in] struct container_XListener listener );
+   void removeListener( [in] struct container_XListener listener );
+}
+</pre>
+</td>
+</tr>
+</table>
+	<p>The CORBA developer must then fill the struct with the correct id before
+	passing it to a UNO. Using no id might signal, that the caller does not care
+	about object identity for this object.</p></li>
+     </ol>	
+	 <li><p>Remove all API in UNO, that relies on object identity and erase
+		  those interfaces.  There is currently a lot of code relying on this.
+		  It does not seem to be possible in near future.</p></li>
+
+	 <li><p>For every mapped interface, a new proxy is generated, object
+		  identity would never work. Thus, the above API is not useable for the
+		  CORBA programmer.</p></li>
+
+	 <li><p>A clever proxy for such a container interface is used in the UNO
+	      process.</p>
+
+<table BORDER=0 CELLSPACING=0 CELLPADDING=4 WIDTH="100%"  >
+<tr>
+<td COLSPAN="3" WIDTH="100%" BGCOLOR="#FFFFC0">
+<pre>
+interface XBroadcasterProxy : XInterface
+{
+    long addListener( [in] XListener listener );
+    void removeListener( [in] long id );
+}
+</pre>
+</td>
+</tr>
+</table>
+		<p>The XBroadcasterProxy implementation is connected to the
+		XBroadcaster implementation somehow before (it may be a separate
+		service). The XBroadcasterProxy.addListener implementation adds
+		XListener-Proxies to the XBroadcaster implementation and stores a hash
+		id, which is returned to the original actor. This actor can later
+		remove the interface at the XBroadcasterProxy implementation using the
+		returned id.</p>
+
+	<p>
+	The broadcaster proxy must certainly be implemented generically, so that it
+	can be reused as often as possible.
+	
+	<p>
+	This works in the concrete example, but does not solve all problems.
+	If the interface reference of C is passed to an object in the UNO process,
+	and this object inserts it into a container, the same problem may occur.</p>
+
+    <p>We are currently looking for a better solution. Any suggestions?</p>
+
+
+<h4><a name="unknown_xinterface_mapping">     
+Mapping <code>GNOME::Unknown</code> and <code>com::sun::star::uno::XInterface</code>
+</a></h4>
+<p>As a result of the above discussion on object identity and object lifetime,
+the following rules can be obtained :</p>
+
+<ul>
+<li><p>All CORBA interfaces seem to be derived from XInterface in the UNO
+process. The typelibrary needs to be extended, so that the CORBA-UNO bridge can
+identify, whether a given interface has its origin in CORBA or in UNO.</p></li>
+<li><p>All UNO interfaces appear in CORBA as derived from XInterface, but
+XInterface gets the additional getCorbaId() method.</p></li>
+
+<li><p>All CORBA interfaces derived from <code>GNOME::Unknown</code> appear in
+UNO only as derived from <code>com::sun::star::uno::XInterface</code>, the
+<code>GNOME::Unknown</code> interface does not appear. The typelibrary needs to
+be extended, so that the CORBA-UNO bridge can identify, that the GNOME::Unknown
+interface is the real base interface.</p></li>
+</ul>
+
+<h4><a name="multiple_inheritance">Multiple inheritance</a></h4>
+Multiple inheritance will not be supported in the first version of the UNO-CORBA bridge.
+
+<h4><a name="type_information">Type information</a></h4>
+<p>Both processes (UNO and CORBA) must have the same type information
+available.  In UNO, these types must be accessible via the typelibary. The
+CORBA-UNO bridge will generically marshal these calls without the need of
+generated code. On CORBA side, there must be (in general) libraries of
+generated stub/proxy code available.</p>
+</ol>
+
+<h2 id="implementation_concepts"> Implementation concepts </h2>
+
+<!-- ************************ C O N C E P T S  *************************    -->
+
+<h4><a name="object_identifier">Object identifier</a></h4>
+     What object identifiers get incoming CORBA objects within UNO and what
+     object ids get outgoing UNO objects?
+     <p>
+     As there is currently no better proposal for the
+     <a href="#object_identity">object identity problem</a>, we assume that
+     solution 1. is chosen.
+
+     <p>
+     First the mapping of UNO objects to CORBA is discussed. Below you find a typical example of
+     an UNO object implementing multiple interfaces.
+     <p>
+    
+     <img src="../images/pipe_inheritance.gif" alt="Pipe inheritance"/>
+
+     <p>
+     The Pipe object is instantiated in the UNO process and is passed
+     as an XInterface reference to the CORBA-process. 
+
+     <p>
+     In CORBA, object references contain the most derived type and (beside other things)
+     an unique object identifier. 
+     A request can be invoked by sending the unique
+     object identifier (and thus leaving out the type information). As there is no
+     most derived type in UNO, the UNO-CORBA
+     bridge must be able to extract solely from the object identifier, which object and
+     which interface the request is meant for.
+
+     <p>
+     The bridge could use the UNO object identifier and try to find out by the
+     method name, which interface shall be called on.
+     But this would mean that it is not possible to have two methods with the same
+     name in two different interfaces.
+
+     <p>
+     So the UNO-CORBA bridge should use the UNO object identifier as an prefix and adds a type
+     identifier. The type identifier may either be the complete type name or a single byte
+     (the bridge ensures the byte's uniqueness for every single object ).
+     <p>
+
+     So in the above example, if the UNO object identifier is &quot;leo&quot;, the CORBA
+     object identifier could be
+
+     <table>
+     <tr><th>Object ID</th><th>type name</th></tr>
+     <tr><td>leo0</td><td><code>XInterface</code></td></tr>
+     <tr><td>leo1</td><td><code>XInputStream</code></td></tr>
+     <tr><td>leo2</td><td><code>XOutputStream</code></td></tr>
+     </table>
+
+	<p>For persistent object references, the name given to the object when
+	 inserting it into the bridge is used (Note that this will only be done for
+	 the exact type, other interfaces of the persistent object will have
+	 transient ids), so for persistent references, there is no type suffix.</p>
+
+<p>
+     Now the mapping of CORBA objects to UNO is discussed. If an CORBA object implements UNO
+     interfaces, the object must implement a <code>getCorbaId()</code> method.
+     The bridge calls this method and uses the return value as unique object identifier.
+
+     <p>
+     For CORBA objects implementing CORBA interfaces, the bridge itself must generate an object
+     identifier. It may happen that the same object gets different object identifiers, because
+     the CORBA-UNO bridge has no possibility get the id of the object. So object identity for
+     these objects will not work in UNO. However, the bridge must ensure, that an identifier
+     is unique, therefor it is not sufficient to use the CORBA object identifier (two
+     different CORBA processes  may use the same identifier). Therefor an connection dependent
+     prefix is added to the object identifier (maybe a GUID generated for every connection).
+
+     
+<h4><a name="corba_bridge_service"> CorbaBridge service</a></h4>
+     The CorbaBridge service is the interface between the UNO developer and the
+     core bridge. In general, this service is used at startup and shutdown
+     of the bridge.
+
+     <p>
+     What does the bridge need?
+  
+     <ul>
+     <li><p>Port and host, that shall be inserted in outgoing TRANSIENT
+          object references.</p></li>
+     <li><p>Port and host, that shall be inserted in outgoing PERSISTENT
+          object references. Here the host/port number of an implementation
+          repository may be entered.</p></li>
+     <li><p>Port and host, that the shall be listened to. There may be multiple
+		  host/port combinations. Note that in outgoing object references only
+		  one host/port can be inserted ! If you want two different hosts/ports
+		  on two different transient object references, you need two instances
+		  of a CORBA bridge.</p></li>
+	 <li><p>Access to acceptor and connector services, that allow the bridge to
+		  accept incoming connections and to establish outgoing connections, if
+		  needed.</p></li>
+	 <li><p>Objects, that shall be mapped persistently.  It should be possible
+		  to make object references persistent. Persistent object references
+		  stay the same even if the server process is restarted. To achieve
+		  this, the bridge must know the objects before accepting calls. This
+		  is for two reasons : If an incoming request to such an object comes
+		  in, the bridge must know, where to delegate it. If the persistent
+		  object is mapped, it must marshal the persistent reference instead of
+		  the transient one.</p></li>
+     </ul>
+
+	 <p>Below you can find a first possible draft of the interface. No error
+	 handling yet specified.</p>
+    
+<table BORDER=0 CELLSPACING=0 CELLPADDING=4 WIDTH="100%" >
+<tr>
+<td COLSPAN="3" WIDTH="100%" BGCOLOR="#FFFFC0">
+<pre>
+struct PersistentInstance
+{
+   string Name;
+   any    instance;
+};
+
+interface XCorbaBridge : XInterface
+{
+    /** allows the bridge to listen on multiple ports
+    */
+    void addAcceptor( [in] XAcceptor acceptor, [in] string acceptString );
+    void removeAcceptor( [in] XAcceptor acceptor );
+    
+    /** the bridge calls uses this connector, to
+         establish interprocess connections.
+    */
+    void setConnector( [in] XConnector connector );
+
+    /** the reply address is inserted in transient object references.
+    */
+    void setTransientReplyAddress( [in] string connectionString );
+    void addTransientObject( [in] any instance );
+
+    void setPersistentReplyAddress( [in] string connectionString );
+
+    void addPersistentObject( [in] string objectName, [in] any instance );
+    void removePersistentObjectByName( [in] string objectName );
+    sequence &lt; struct PersistentInstance &gt; getPersistentObjects();
+
+    /**
+       Removes either transient or persistent objects. 
+
+      The object must have been added before either by addTransientObject or addPersistentObject.
+    */
+    void removeObject( [in] any instance );
+
+    /**
+      returns a stringified IOR, that an arbitrary orb may use to connect to this object.
+
+      The object must have been added before either by addTransientObject or addPersistentObject or
+      has been mapped before from a CORBA process.
+    */
+    string getIORForObject( [in] any instance );
+
+    /** allows retrieval of an object from a arbitrary CORBA process using a stringified IOR.
+    */
+    any resolveByIOR( [in] string sName );
+
+    
+    /**
+      Sets corba bridge into an inactive state. All calls are suspended, no connections
+      are accepted.
+
+      After instantiation, the bridge is in a suspended mode. One may mush to switch to
+      suspended mode again, when multiple changes shall be applied to the bridge
+      parameters consistently.
+    */
+    void suspend();
+
+    /**
+      Sets corba bridge into an active state. Connections can be accepted, calls
+      are processed.
+
+      After instantiation, the bridge is in a suspended mode.
+    */
+    void resume();
+
+    /** Shutdown the bridge. All connections are interrupted, all instances are released.
+
+       @param waitForCompletion if true, the method waits until all threads have gone.
+                                if false, the method returns immediately. ( This may be
+				necessary, if the method is called from a remote process ).
+                                
+    */
+    void shutdown( [in] boolean waitForCompletion);
+};
+
+service CorbaBridge
+{
+    interface XCorbaBridge;
+};
+</pre>
+
+</td>
+</tr>
+</table>
+
+<h4><a name="connection_management">Interprocess connection management</a></h4>
+   A normal UNO-UNO interprocess bridge just owns one interprocess connection. This
+   is not appropriate for the UNO-CORBA bridge, because interface references handed out
+   over one connection can come in again over a different connection and must still be
+   valid, so all connections must end in one bridge.
+<p>
+   The UNO-CORBA bridge needs to distinct between connections initiated from
+   the UNO process or from an arbitrary CORBA process. If a request shall be invoked
+   on a object, that has not been invoked before, the IOR must be parsed for a
+   host/port combination. The bridge has a hashmap for actively initiated
+   connections. The key is host/port and the connection is the value.
+<p>
+   If there is no match, the bridge tries to initiate a connection. On success,
+   the connection is added to the hashmap. The proxy should store that it got
+   the object last time over this connection for performance reasons.
+
+<p>
+   Actively initiated connections can be closed at any time. This should
+   be done, when the last proxy, that uses this connection, dies.
+
+<p>
+   Passively initiated connections should be closed by the remote process. Another
+   possibility would be to close it when the last stub for this connection dies, however
+   then a CloseConnection message must be sent.
+   
+<p>   
+   Bidirectional communication (as specified by GIOP 1.2) should be ignored in the
+   first run, because it complicates things a lot.
+   
+<h4><a name="iiop_version">IIOP versions</a></h4>
+   I think IIOP versions 1.0 is sufficient for the first running ORB. The following features
+   are added in the following versions :
+
+   <ul>
+   <li> Version 1.1
+    <ul>
+      <li><p>Fragmentation messages</p></li>
+	</ul>
+   </li>
+   <li> Version 1.2
+    <ul>
+       <li><p>Bidirectional communication over one connection</p></li>
+	</ul>
+   </li>
+   </ul>
+   
+In the first run, only version 1.0 should be supported. Keeping the versions
+1.1 and 1.2 in mind during implementation, it should be quite easy to implement
+them later if needed.
+
+      
+<h4><a name="deployment_problem">
+How can the CORBA-UNO bridge be deployed for the GNOME orbit?
+</a></h4>
+<p>(prebuilding stub/proxy code?, which compiler to use?, where to put the
+libraries?, how do we get the UNO types into the typelibrary?)</p>
+<table summary="footer" width=100% bgcolor=#666699>
+<tr><td>
+<font color="#FFFFFF">
+Author:
+<a href="mailto:joerg.budischewski@germany.sun.com">Joerg Budischewski</a>,
+<a href="mailto:juergen.schmidt@germany.sun.com">J&uuml;rgen Schmidt</a>
+($Date: 2004/11/27 08:10:06 $)
+<br/><I>Copyright 2001 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303 USA.</I></font>
+</td></tr>
+</table>
+</body>

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

Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/concept/uno_default_bootstrapping.html
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/concept/uno_default_bootstrapping.html?rev=1206895&view=auto
==============================================================================
--- incubator/ooo/ooo-site/trunk/content/udk/common/man/concept/uno_default_bootstrapping.html (added)
+++ incubator/ooo/ooo-site/trunk/content/udk/common/man/concept/uno_default_bootstrapping.html 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=http://wiki.services.openoffice.org/wiki/Uno/Binary/Spec/Bootstrapping" />
+<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/concept/uno_default_bootstrapping.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/concept/uno_langbind.html
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/concept/uno_langbind.html?rev=1206895&view=auto
==============================================================================
--- incubator/ooo/ooo-site/trunk/content/udk/common/man/concept/uno_langbind.html (added)
+++ incubator/ooo/ooo-site/trunk/content/udk/common/man/concept/uno_langbind.html Sun Nov 27 22:49:46 2011
@@ -0,0 +1,181 @@
+<!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> UNO Language Binding : What is it about? </title>
+<style type="text/css">
+	<!--
+h1 { text-align:center; margin-top: 0.2cm; text-decoration: none; color: #ffffff; font-size: 6; margin-top: 0.2cm}
+h2 { margin-top: 0.2cm; margin-bottom=0.1cm; color: #ffffff;
+     background-color: #666699 }
+ul {margin-bottom: 0cm;}
+li {margin-bottom: 0cm;}
+dl {margin-bottom: 0.2cm;}
+dd {margin-bottom: 0.2cm;}
+dt {margin-bottom: 0.2cm;}
+-->
+</style>
+</HEAD>
+
+<body>
+<table width=100% border=0 cellpadding=4 cellspacing=0 bgcolor="#666699"
+   summary="Header">
+<TR><TD>
+      <h1> UNO Language Binding : What is it about? </h1>
+	  </td><td>
+	  <A HREF="http://www.openoffice.org/"> 
+        <img src="../../../images/open_office_org_logo.gif" name="Grafik1" alt="OpenOffice.org" align=right width=109 height=54 border=0/></A>
+    </TD></TR>
+</TABLE>
+
+<h2 id=contents> Contents </h2>
+<blockquote>
+   <a href="#intro">Introduction</a><br/>
+   <a href="#def">Definitions:</a>
+   <ul>
+     <li><a href="#env">UNO Runtime Environment (URE)</a></li>
+     <li><a href="#langspec">Language Specification and Glue Code</a></li>
+     <li><a href="#codegen">Code Generator</a></li>
+     <li><a href="#bridge">UNO Bridge</a>
+	 <ul>
+	    <li><a href="#mapping">Mapping</a></li>
+		<li><a href="#engine">Environment/ Engine Access</a></li>
+	</ul>
+	</li>
+    <li><a href="#loader">UNO Component Loader</a></li>
+    <li><a href="#bootstrap">Bootstrapping</a></li>
+    <li><a href="#initobject">Initial Object</a></li>
+   </ul>
+</blockquote>
+
+<h2 id="intro"> Introduction </h2>
+
+<p>
+The objective of this document is to get a general notion of a UNO language
+binding and
+define terminology of the parts that language binding consists.
+For <a href="http://wiki.services.openoffice.org/wiki/Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno">general UNO programming</a> or details
+ about <a href="../../../cpp/man/cpp_bridges.html">building up a C++ bridge</a>,
+for example for a specific C++ compiler please read the specific documents.</p>
+
+<p>A UNO language binding is simply said the infrastructure enabling communication between
+UNO components from different language or runtime environments.
+More over a language binding not only let components, for example written with different
+programming languages, to interoperate, it also provides the UNO programming environment
+for a specific language/ environment.
+Despite the fact that a language binding may not only connect different programming languages
+(for example when connecting to object models like COM), we use the term of a "language
+binding" for simplicity. Though, the term "Environment binding" would have been more general.</p>
+
+<p>The following section presents several definitions of what parts a UNO
+language binding consists. Some parts are optional, though.
+
+<h2 id="def"> Definitions </h2>
+
+<p><i><b><a name="env"></a>UNO Runtime Environment (URE).</b></i>
+A UNO component runs in an environment which serves as the platform to run
+components (UNO Runtime Environment).
+A language binding connects two environments for interoperation.
+<p>
+The runtime prerequisites for components in an environment may be different,
+for example a java component needs a java virtual machine, a COM component the COM libraries.
+An environment need not denote a specific programming language to interoperate with,
+it can even be a language independent object model like COM.
+</p>
+
+<p><b><i><a name="langspec"></a>Language Specification and Glue Code.</i></b>
+The language specification defines the mapping of any UNO type (for example IDL long)
+to its corresponding environment specific type (for example java int).
+More over, the handling of complex types (for example structs, sequences, any, interfaces)
+is defined with respective support by a runtime API.
+If a programming language does not support a specific UNO feature (for example no
+"direct"/ convenient exception support), additional glue code (part of the runtime API)
+has to be defined balancing out these weaknesses.
+</p>
+
+<p><i><b><a name="codegen"></a>Code Generator.</b></i>
+The language specification defines the representation of UNO IDL types.
+
+<p>A code generator produces the appropriate programming language constructs as
+defined in the language specification.
+It commonly reads from a binary type library and writes out files for each type.
+</p>
+
+<p><i><b><a name="bridge"></a>UNO Bridge.</b></i>
+A bridge is the core instance connecting two environments.
+
+<p>A bridge is bidirectional in the way that it can map interfaces from one
+environment
+to another and vice versa, thus providing two unidirectional mappings.</p>
+
+<blockquote>
+<p><i><b><a name="mapping"></a>Mapping.</b></i>
+Mapping an interface involves in depth knowledge of both environments
+to emulate arbitrary interfaces.
+
+<p>Calls on an emulated interface are delegated (including marshalling) via the
+bridge and lead to a method invocation on the target interface.
+Any return values, out parameters or exceptions have to be converted to the calling environment.
+For this task the complementary mapping is needed,
+thus both mappings of a bridge are tied closely together.
+</p>
+
+<p><i><b><a name="engine"></a>Environment/ Engine Access.</b></i>
+The bridge needs runtime environment access, for interpreting environments
+also access to the executing engine (for example java, javascript).
+<p>The bridge connecting to the environment commonly needs engine access, too.
+</p>
+</blockquote>
+
+<p><i><b><a name="loader"></a>UNO Component Loader.</b></i>
+The UNO component loader loads a UNO component implemented for a specific UNO runtime environment.
+<p>Besides loading the component and preparing the runtime environment (like scripting engine access),
+this process eventually includes raising an appropriate bridge to connect to the environment.
+
+<p>When loading a component, the component may define own types it needs to execute.
+These types may be introduced to the runtime by the component dynamically at startup
+or those types have been merged to a central binary typelib file prior to application execution
+(which has been most commonly used for now).
+</p>
+
+<p><i><b><a name="bootstrap"></a>Bootstrapping.</b></i>
+The bootstrapping process starts up the UNO core system up to the point that components
+can be loaded and executed.
+
+<p>Components are dependent on each other. For loading components you most commonly need to have
+a component loader component from scratch. This is the first problem: You need to load
+it manually.
+Among other things it is necessary to have a type system providing type information used
+in components. The latter issue may includes typelib files to be known.
+So this process requires inside implementation knowledge of the initial components,
+despite the fact that you normally need not know how a service is implemented.
+As a result of the bootstrapping process, it is possible to raise further components
+without knowing any implementation details.
+
+<p>
+It is not intended to define a <i>general</i> bootstrap process here, if this is possible at all.
+Although, we will present a default scheme applications using
+the C++ implementations of base services from code module <code>stoc</code>.
+It is part of the UNO language binding to provide a mechanism to bootstrap an initial
+UNO system in a specific UNO runtime environment.
+</p>
+
+<p><i><b><a name="initobject"></a>Initial Object.</b></i>
+First object provided by a UNO runtime environment.
+
+<p>This may be necessary in inter-process communication, if the component
+loader needs to
+have a "special" initial object like a service manager.
+The language binding has to define the initial communication protocol to get the initial object.
+</p>
+
+<table summary=Footer bgcolor=#666699 width=100%>
+<TR><TD><P><FONT COLOR="#ffffff">
+Author: <A HREF="mailto:Daniel.Boelzle@germany.sun.com">
+<FONT COLOR="#ffffff">Daniel B&ouml;lzle</font></A>. ($Date: 2007/05/25 14:38:49 $)<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/concept/uno_langbind.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/concept/uno_security.html
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/concept/uno_security.html?rev=1206895&view=auto
==============================================================================
--- incubator/ooo/ooo-site/trunk/content/udk/common/man/concept/uno_security.html (added)
+++ incubator/ooo/ooo-site/trunk/content/udk/common/man/concept/uno_security.html Sun Nov 27 22:49:46 2011
@@ -0,0 +1,675 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<HTML>
+<HEAD>
+<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
+<TITLE>
+UNO Security
+</TITLE>
+</HEAD>
+<BODY LINK="#444488" VLINK="#444488" BGCOLOR="#ffffff"><A NAME="__Top__"></A>
+<TABLE WIDTH=100% BORDER=0 CELLPADDING=4 CELLSPACING=0>
+<COL WIDTH=75>
+<TR><TD BGCOLOR="#666699">
+      <H1 ALIGN=CENTER><A HREF="http://www.openoffice.org/">
+        <IMG SRC="../../../images/open_office_org_logo.gif" NAME="Grafik1" ALT="OpenOffice.org" ALIGN=RIGHT WIDTH=109 HEIGHT=54 BORDER=0>
+        </A><FONT COLOR="#ffffff">UNO Security</FONT></H1>
+    </TD></TR>
+
+</TABLE>
+<br>
+
+<TABLE BORDER=0 CELLPADDING=4 CELLSPACING=0>
+<TR><TD BGCOLOR="#666699">
+      <H3><FONT COLOR="#ffffff" SIZE=4>
+        Contents</FONT></H3>
+</TD></TR>
+
+  <TR>
+    <TD>
+      <p><a href="#intro">Introduction</a></p>
+      <p><a href="#api">Concept and API</a>
+      <ul>
+      <li><a href="#api_access">API access</a></li>
+      <li><a href="#checking_permissions">Checking Permissions</a>
+       <ul>
+       <li><a href="#filepermission">FilePermission</a></li>
+       <li><a href="#socketpermission">SocketPermission</a></li>
+       <li><a href="#runtimepermission">RuntimePermission</a></li>
+       <li><a href="#allpermission">AllPermission</a></li>
+       </ul>
+      </li>
+      <li><a href="#static_restrictions">Static Restrictions</a></li>
+      <li><a href="#dynamic_restrictions">Dynamic Restrictions</a></li>
+      <li><a href="#ac_switches">AccessController Switches</a></li>
+      </ul>
+      <p><a href="#overview">Overview</a></p>
+      <p><a href="#untrusted">Dealing with Untrusted Code</a></p>
+       <ul>
+       <li><a href="#untrusted_native">Untrusted Native Code</a></li>
+       <li><a href="#untrusted_scripted">Untrusted Scripted Code</a></li>
+       <li><a href="#untrusted_java">Untrusted Java Code</a></li>
+       <li><a href="#untrusted_remote">Untrusted Inter Process Code</a></li>
+       </ul>
+      <p><a href="#current_implementation">Current Implementation Details</a></p>
+       <ul>
+       <li><a href="#recurring_calls">Recurring Calls</a></li>
+       <li><a href="#performance_considerations">Performance Considerations</a></li>
+       <li><a href="#file_policy">File Policy Implementations</a></li>
+       </ul>
+      <p><a href="#todos">Things left to do...</a></p>
+    </TD>
+  </TR>
+
+<TR><TD BGCOLOR="#666699">
+  <H3><FONT COLOR="#ffffff" SIZE=4>
+  <a name="intro">Introduction</a></FONT></H3>
+</TD></TR>
+<TR><TD>
+   <p>
+In general, security concerns the following four topics [CORBA Security Specification]:
+<ul>
+   <li><p><b>Confidentiality:</b> Information is disclosed only to users authorized to
+       access it.</p></li>
+   <li><p><b>Integrity:</b> Information is modified only by users who have the
+	   right, only in authorized ways, and is transferred only between intended
+	   users in intended ways.</p></li>
+   <li><p><b>Accountability:</b> Users are accountable for their
+       security-relevant actions.</p></li>
+   <li><p><b>Availability:</b> Use of the system cannot be randomly or
+       maliciously denied to authorized users.</p></li>
+</ul>
+Among this very common understanding of security, there are two distinct topics when users want to access or modify resources, or execute a program:
+<p>
+<b>Authentification:</b> The process of validating a subject to ensure that the subject (for example John Doe) is who or what it claims to be.</p>
+<p><b>Authorization:</b> The process of granting permission to access data or execute functionality.
+</p>
+<p>
+A subject (for example the user who started an application or demands access on
+resources accessible via a WWW front end) has to be authenticated to an
+information system. Often, this first step associates the subject with a set of
+credentials, such as, user attributes, permissions, or different principals.
+A subject may be any entity, for example, a person or service. Once
+authenticated, a subject is populated with associated identities or principals.
+A subject may have many principals. For example, a person may have a name
+principal ("John Doe") and a social security number principal ("123-45-6789"),
+which distinguish it from other subjects.</p>
+<p>Authorization has to be done any time the user demands access to sensitive
+data or wants to execute sensitive code. Authorization is hence of a
+programmatic nature and is implemented by the specific service that is handling
+the demand (explicitly checked by base service, but implicitly checked from
+service users' perspective).  A common approach of authorization is handled by
+access control lists (ACL), that is, sets of permissions (positive) or denials
+(negative).
+</p>
+<img src="../images/sec_resource.jpg">
+<p>
+The next sections are about the UNO security API, covering authorization exclusively.  Authorization is a primary goal because it affects most of the client code, such as, doing permission checks.
+It is assumed that users have been authenticated previously using some
+mechanism.</p>
+<p>There was no new API defined that abstracted from a specific authentication mechanism, such as the Java Authentication and Authorization framework (JAAS).
+Although there is no defined API, you can find some draft interfaces and services in the udkapi cvs tree of the <code>com.sun.star.security.auth</code> package.
+
+</p>
+</td></tr>
+
+<TR><TD BGCOLOR="#666699">
+  <H3><FONT COLOR="#ffffff" SIZE=4>
+  <a name="api">Concept and API</a></FONT></H3>
+</TD></TR>
+<TR><TD>
+<p>The UNO API is closely related to the Java authorization API.  Permission
+semantics have been adopted.
+For details about java permissions, have a look at <a href="http://java.sun.com/j2se/1.4.2/docs/guide/security/permissions.html">
+Permissions in the Java 2 SDK</a>.</p>
+<p>There is only a difference when coming to dynamic restrictions which are
+implicitly handled by the Java AccessController (ac).  The Java ac implicitly
+checks permissions related to a PermissionDomain.  A PermissionsDomain includes
+a set of permissions related to a set of classes.  Java can manage this, but
+this feature is not practically  adaptable for compiled machine code.</p>
+<p>As a solution, these dynamic restrictions can be set explicitly using the
+UNO ac interface.  This will install thread/task local restrictions to be used
+upon permission checks.</p>
+
+<p><a name="api_access"><b>API Access</b></a></p>
+<p>Implementing programmatic security (client code), there is an ac singleton object in the component context given to every component.  The name of the object is</p>
+<table width="100%" bgcolor="#ffffaa"><tr><td><pre>
+/singletons/com.sun.star.security.theAccessController
+</pre></td></tr></table>
+<p>This object mainly exports the <code>com.sun.star.security.XAccessController</code> interface which has the following <a href="../../common/ref/com/sun/star/security/XAccessController.html">IDL definition</a>:</p>
+<table width="100%" bgcolor="#ffffaa"><tr><td><pre>
+module com {  module sun {  module star {  module security {
+
+interface XAccessController : com::sun::star::uno::XInterface
+{
+    void checkPermission(
+        [in] any perm )
+        raises (AccessControlException);
+
+    any doRestricted(
+        [in] XAction action,
+        [in] XAccessControlContext restriction )
+        raises (com::sun::star::uno::Exception);
+
+    any doPrivileged(
+        [in] XAction action,
+        [in] XAccessControlContext restriction )
+        raises (com::sun::star::uno::Exception);
+
+    XAccessControlContext getContext();
+};
+
+}; }; }; };
+</pre></td></tr></table>
+
+<p><a name="checking_permissions"><b>Checking Permissions</b></a></p>
+<p>The first method is commonly called by security-related services which need to check if an action is permitted.
+The actual permission takes the security policy, currently in effect, into account.
+In general, the <em>security policy in effect</em> has a dynamic and static part.
+The dynamic part uses restrictions modified by <code>doRestricted()</code> and <code>doPrivileged()</code> calls, while the static part takes user credentials into account (commonly persistent data).
+Currently, four different permission types are defined in IDL and implemented in the UDK ac (module <code>stoc/source/security</code>):
+<ul>
+
+<li><p><b><a name="filepermission" href="../../common/ref/com/sun/star/io/FilePermission.html">com.sun.star.io.FilePermission</a></b>:</p>
+<table width="100%" bgcolor="#ffffaa"><tr><td><pre>
+module com {  module sun {  module star {  module io {
+
+struct FilePermission
+{
+    string URL;
+    string Actions;
+};
+
+}; }; }; };
+</pre></td></tr></table>
+<p>This permission represents access to a file or directory.
+A FilePermission consists of a file url and a set of actions valid for that url.
+<p>
+    The path of the file url that ends in <code>"/*"</code> indicates all the files and
+    directories contained in that directory.  A path that ends with <code>"/-"</code>
+    indicates (recursively) all files and subdirectories contained in that
+    directory.  A file url string consisting of the special token <code>"&lt;&lt;ALL FILES&gt;&gt;"</code>
+    matches any file.
+    </p>
+    <p>Note: A file url string consisting of a single <code>"*"</code> indicates all the files
+    in the current directory, while a string consisting of a single <code>"-"</code> indicates
+    all the files in the current directory and (recursively) all files and
+    subdirectories contained in the current directory.
+    </p>
+    <p>The actions to be granted are a list of one or more comma-separated keywords.
+    The possible keywords are <code>"read"</code>, <code>"write"</code>,
+    <code>"execute"</code>, and <code>"delete"</code>.
+    Their meaning is defined as follows:</p>
+    <ul>
+    <li><code>read</code> -- read permission</li>
+    <li><code>write</code> -- write permission</li>
+    <li><code>execute</code> -- execute permission</li>
+    <li><code>delete</code> -- delete permission</li>
+    </ul>
+    <p>The actions string is processed case-insensitive.
+    </p>
+    
+    <p><em><b>Attention</b></em>:
+    Be careful when granting FilePermissions.  Think about the implications of
+    granting read and especially write access to various files and directories.
+    The <code>"&lt;&lt;ALL FILES&gt;&gt;"</code> permission with write action is especially dangerous.
+    This grants permission to write to the entire file system.
+    </p>
+</li>
+
+<li><p><b><a name="socketpermission" href="../../common/ref/com/sun/star/connection/SocketPermission.html">com.sun.star.connection.SocketPermission</a></b>:</p>
+<table width="100%" bgcolor="#ffffaa"><tr><td><pre>
+module com {  module sun {  module star {  module connection {
+
+struct SocketPermission
+{
+    string Host;
+    string Actions;
+};
+
+}; }; }; };
+</pre></td></tr></table>
+<p>This permission represents access to a network via sockets.
+    A SocketPermission consists of a host specification and a set of actions
+    specifying ways to connect to that host.  The host is specified as</p>
+    <pre>
+    host = (hostname | IPaddress)[:portrange]
+    portrange = portnumber | -portnumber | portnumber-[portnumber]
+    </pre>
+    <p>The host is expressed as a DNS name, as a numerical IP address, or as a
+    <code>"localhost"</code> (for the local machine).  The wildcard <code>"*"</code>
+     may be included once
+    in a DNS name host specification.  If it is included, it must be in the
+    leftmost position, as in <code>"*.sun.com"</code>.
+    </p>
+    <p>The port or portrange is optional.  A port specification of the form <code>"N-"</code>,
+    where <code>N</code> is a port number, signifies all ports numbered <code>N</code> and above,
+    while a specification of the form <code>"-N"</code> indicates all ports numbered
+    <code>N</code> and below.
+    
+    <p>
+    The possible ways to connect to the host are
+    <ul>
+    <li><code>accept</code></li>
+    <li><code>connect</code></li>
+    <li><code>listen</code></li>
+    <li><code>resolve</code></li>
+    </ul>
+    <p>The <code>"listen"</code> action is only meaningful when used with <code>"localhost"</code>.
+    The <code>"resolve"</code> (resolve host/ip name service lookups) action is implied when any of the other actions are present.
+    </p>
+    <p>As an example of the creation and meaning of SocketPermissions, note that if
+    the following permission:
+<pre>
+SocketPermission("foo.bar.com:7777", "connect,accept");
+</pre>
+    <p>is granted, it allows to connect to port 7777 on foo.bar.com, and to
+    accept connections on that port.
+    </p>
+    <p>Similarly, if the following permission:</p>
+<pre>
+SocketPermission("localhost:1024-", "accept,connect,listen");
+</pre>
+    <p>is granted, it allows that code to accept connections on, connect to, or listen
+    on any port between 1024 and 65535 on the local host.
+    </p>
+    
+    <p><em><b>Attention</b></em>:
+    Granting code permission to accept or make connections to remote hosts may be
+    dangerous because malevolent code can then more easily transfer and share
+    confidential data among parties who may not, otherwise, have access to the data.
+    </p>
+</li>
+
+<li><p><b><a name="runtimepermission" href="../../common/ref/com/sun/star/security/RuntimePermission.html">com.sun.star.security.RuntimePermission</a></b>:</p>
+<table width="100%" bgcolor="#ffffaa"><tr><td><pre>
+module com {  module sun {  module star {  module security {
+
+struct RuntimePermission
+{
+    string Name;
+};
+
+}; }; }; };
+</pre></td></tr></table>
+<p>This permission grants runtime access to some named functionality.  A RuntimePermission contains
+    a name (also referred to as a <em>target name</em>) but no actions list;
+    you either have the named permission or you don't.
+</p></li>
+
+<li><p><b><a name="allpermission" href="../../common/ref/com/sun/star/security/AllPermission.html">com.sun.star.security.AllPermission</a></b>:</p>
+<table width="100%" bgcolor="#ffffaa"><tr><td><pre>
+module com {  module sun {  module star {  module security {
+
+struct AllPermission
+{
+};
+
+}; }; }; };
+</pre></td></tr></table>
+<p>The AllPermission is a permission that implies all other permissions.</p>
+
+    <p><em><b>Attention</b></em>:
+    Granting AllPermission should be done with extreme care, as it implies all
+    other permissions.  Thus, it grants code the ability to run with security
+    disabled.  Extreme caution should be taken before granting such a
+    permission to code.  This permission should be used only during testing,
+    or in extremely rare cases where an application is completely trusted and
+    adding the necessary permissions to the policy is prohibitively cumbersome.
+    </p>
+</li>
+
+</ul>
+
+<p>When access is denied upon calling <code>checkPermission()</code>, an
+<code>AccessControlException</code> is thrown.  An
+<code>AccessControlException</code> signals a security violation.
+The <code>AccessControlException</code> is derived from
+<code>SecurityException</code> which is derived from
+<code>RuntimeException</code> and thus can be thrown upon any call on UNO
+interfaces, except for calls on <code>XInterface::acquire()</code> and
+<code>XInterface::release()</code>.</p>
+
+<table width="100%" bgcolor="#ffffaa"><tr><td><pre>
+module com {  module sun {  module star {  module uno {
+
+exception SecurityException : com::sun::star::uno::RuntimeException
+{
+};
+
+}; }; }; };
+
+module com {  module sun {  module star {  module security {  
+
+exception AccessControlException : com::sun::star::uno::SecurityException
+{
+    any LackingPermission;
+};
+
+}; }; }; };
+</pre></td></tr></table>
+
+<p><a name="static_restrictions"><b>Static Restrictions</b></a><br>
+A restriction is defined by a set of permissions.  It has to be assured that a demanded permission is implied by this set of permissions.
+Static restrictions are defined by a (commonly persistent) set of permissions granted to a user.  This has been done by some admin frontend in advance.  The effective set of permissions is provided by the
+<a href="../../common/ref/com/sun/star/security/Policy.html">Policy</a> service.
+There is a singleton object installed into the initial component context from which an ac implementation reads:</p>
+<table width="100%" bgcolor="#ffffaa"><tr><td><pre>
+/singletons/com.sun.star.security.thePolicy
+</pre></td></tr></table>
+<p>The service supports the interface
+<a href="../../common/ref/com/sun/star/security/XPolicy.html"><code>XPolicy</code></a>
+and reads out of some storage:</p>
+
+<table width="100%" bgcolor="#ffffaa"><tr><td><pre>
+module com {  module sun {  module star {  module security {
+
+interface XPolicy : com::sun::star::uno::XInterface
+{
+    sequence< any > getPermissions(
+        [in] string userId );
+    sequence< any > getDefaultPermissions();
+    void refresh();
+};
+
+service Policy
+{
+    interface XPolicy;
+};
+
+}; }; }; };
+</pre></td></tr></table>
+
+<p>Implementing the <code>XPolicy</code> interface, it is important to separate
+default permissions from user permissions.  That is, the ac implementation has
+to combine both to get the effective set of permissions.  Providing these
+permissions separately, the ac implementation has the opportunity to optimize
+permission sets, that is, it only needs to read (and convert) the default
+permissions once, for every user.</p>
+<!-- When refreshing the user policy, e.g. when some storage contexts were modified, the ac has to be notified.  Therefore, it is recommended that the policy supports the
+<a href="../../common/ref/com/sun/star/container/XContainer.html"><code>XContainer</code></a>
+interface.  The current ac implementation will support this soon (xxx todo).
+-->
+
+<p><a name="dynamic_restrictions"><b>Dynamic Restrictions</b></a><br>
+Dynamic restrictions apply to the <code>doPrivileged()</code> and <code>doRestricted()</code> calls of the <code>XAccessController</code> interface.
+These calls will directly modify a property of the
+<a href="uno_contexts.html#current_context">current context</a> which is called</p>
+<table width="100%" bgcolor="#ffffaa"><tr><td><pre>
+access-control.restriction
+</pre></td></tr></table>
+
+<p>This property is of type <code>XAccessControlContext</code> and taken into
+account additionally to the static permissions granted to the calling user.</p>
+<p>The <code>XAccessControlContext</code> has only one method:</p>
+
+<table width="100%" bgcolor="#ffffaa"><tr><td><pre>
+module com {  module sun {  module star {  module security {  
+
+interface XAccessControlContext : com::sun::star::uno::XInterface
+{
+    void checkPermission(
+        [in] any perm )
+        raises (AccessControlException);
+};
+
+}; }; }; };
+</pre></td></tr></table>
+
+<p>Users may implement this interface themselves to restrict or to get a snapshot of the currently effective security by calling <code>XAccessController::getContext()</code>.  This has to be done when raising new threads.  A child thread has to inherit an initial restriction context from its parent at the time of creation.</p>
+
+<p>When calling <code>XAccessController::doRestricted()</code> the ac
+implementation combines a previous restriction with the given one, thus the
+intersection of permissions of both contexts becomes effective.  It then
+installs this new restriction into the current context and calls the specified
+action.  In essence, when doing subsequent <code>doRestricted()</code> calls,
+you chain up several restrictions over several stack layers.</p>
+
+<p>When calling <code>XAccessController::doPrivileged()</code>, the ac
+implementation adds the given set of permission (defined by the ac context),
+installing an extended restriction.  If you pass a null-ref to
+<code>doPrivileged()</code>, then all permissions are implied (no dynamic
+restriction).  This feature may be sensible for basic service implementations
+which need privileges in a well-defined manner, a.k.a., <em>they know what they
+do</em>.</p>
+<img src="../images/sec_dynamic.jpg">
+
+<p><a name="ac_switches"><b>AccessController Switches</b></a><br>
+The ac can be run in several modes, thus influencing its runtime behavior.  When instantiating the ac service, it uses the component context' property</p>
+<table width="100%" bgcolor="#ffffaa"><tr><td><pre>
+/services/com.sun.star.security.AccessController/mode
+</pre></td></tr></table>
+<p>Currently, there are five modes:</p>
+<ul>
+   <li><code>"on"</code><br>
+       This (default) mode turns dynamic and static permission checks on.
+	   Dynamic restrictions are performed evaluating the current context's
+	   <code>access-control.restriction</code> property.  Static
+	   permissions are checked against the calling user's permissions
+	   provided by the policy service.  The current user id is determined
+	   using the current context's property
+	   <code>access-control.user-credentials.id</code>.  If neither the
+	   dynamic restriction nor the effective user's permissions grant a
+	   demanded permission, then an <code>AccessControlException</code> is
+	   thrown.</p></li>
+   <li><p><code>"single-user"</code><br>
+	   This mode turns dynamic and static permission checks on.  Dynamic
+	   restrictions are performed evaluating the current context's
+	   <code>access-control.restriction</code> property.  Static
+	   permissions are checked against the user's permissions provided by
+	   the policy service.  The user id is determined using the component
+	   context's property
+	   <code>/services/com.sun.star.security.AccessController/single-user-id</code>.
+	   If neither the dynamic restriction nor the effective user's
+	   permissions grant a demanded permission, then an
+	   <code>AccessControlException</code> is thrown.</p></li>
+   <li><p><code>"single-default-user"</code><br>
+       This mode turns dynamic and static permission checks on.  Dynamic
+	   restrictions are performed evaluating the current context's
+	   <code>access-control.restriction</code> property.  Static
+	   permissions are checked against the default permissions provided by
+	   the policy service.  If neither the dynamic restriction nor the
+	   default permission grant a demanded permission, then an
+	   <code>AccessControlException</code> is thrown.</p></li>
+   <li><p><code>"dynamic-only"</code><br>
+       This mode turns dynamic permission checks on, exclusively.  This is
+	   useful, if you cannot determine any specific user and don't want to
+	   build up a dummy policy granting default permissions.</p></li>
+</ul>
+
+</td></tr>
+
+<TR><TD BGCOLOR="#666699">
+  <H3><FONT COLOR="#ffffff" SIZE=4>
+  <a name="overview">Overview</a></FONT></H3>
+</TD></TR>
+<TR><TD>
+<p>
+<img src="../images/sec_overview.jpg">
+</p>
+</td></tr>
+
+<TR><TD BGCOLOR="#666699">
+  <H3><FONT COLOR="#ffffff" SIZE=4>
+  <a name="untrusted">Dealing with Untrusted Code</a></FONT></H3>
+</TD></TR>
+<TR><TD>
+Untrusted code should, in general, run in a sandbox, that is, a restricted environment.
+
+<p><a name="untrusted_native"><b>Untrusted Native Code</b></a><br>
+One cannot restrict native code modifying the current context, poke memory, thus influencing the security policy.  I think this is not a goal.
+
+<p><a name="untrusted_scripted"><b>Untrusted Scripted Code</b></a><br>
+Sandboxed script code, for example, a basic script, has to be restricted in the
+way that the underlying engine disallows modifying the following current
+context's access-control properties, i.e., all of:</p>
+
+<table width="100%" bgcolor="#ffffaa"><tr><td><pre>
+access-control.*
+</pre></td></tr></table>
+
+<p>as well as disallowing a call on the ac's <code>doPrivileged()</code>.
+These actions are security violations and have to be signalled via a
+<code>SecurityException</code>.</p>
+
+<p>In addition, it has to be ensured that the script cannot raise components
+exchanging the ac of the component context.  Therefore, the script engine has
+to proxy the service manager ensuring the ac property</p>
+
+<table width="100%" bgcolor="#ffffaa"><tr><td><pre>
+/singletons/com.sun.star.security.theAccessController
+</pre></td></tr></table>
+
+<p>is original, by doing security checks when
+<code>XSingleComponentFactory::createInstanceWithContext()</code> or
+<code> XSingleComponentFactory::createInstanceWithArgumentsAndContext()</code>
+is called.
+
+<p><a name="untrusted_java"><b>Untrusted Java Code</b></a><br>
+In general, the same applies for Java as for scripts.  In addition, the UNO policy has to be plugged under the Java AccessController restricting calls to the Java API.
+For example, imagine that the untrusted Java code opens a file using the Java core API.
+The Java AccessController has to control this access relying on its Java policy in effect.</p>
+<p>Another problem with integrating the Java and C++/UNO access controllers are
+dynamic restrictions, which is not yet solved.</p>
+
+<p><a name="untrusted_remote"><b>Untrusted Inter-Process Code</b></a><br>
+
+A remote user (inter-process user) is assumed to be authenticated when connected.
+The server code must ensure separating different users; it is not necessary that the client code needs to be trusted in terms of dynamic restrictions as demanded for untrusted scripted code.
+But it has to be ensured that the server-side ac implementation is always used when restricting server-side access, such as when permission checks have to be performed process-locally.
+<p>
+<img src="../images/sec_interprocess.jpg">
+</p>
+</td></tr>
+
+<TR><TD BGCOLOR="#666699">
+  <H3><FONT COLOR="#ffffff" SIZE=4>
+  <a name="current_implementation">Current Implementation Details</a></FONT></H3>
+</TD></TR>
+<TR><TD>
+<p>
+Upon bootstrapping the UNO core system getting an initial
+<a href="uno_contexts.html#component_context">component context</a>, the ac implementation of <code>stoc/source/security</code> (<code>sec.dll</code>/ <code>libsec.so</code>) is installed as a singleton.  This is most commonly done using some of cppuhelper's bootstrapping function, for example:
+<a href="../../cppuhelper/defaultBootstrap_InitialComponentContext.html"><code>defaultBootstrap_InitialComponentContext()</code></a>.
+You can specify some <a href="micro_deployment.html#Bootstrap_Arguments">bootstrap variables</a> mapping directly to the above mentioned AccessController mode:
+<ul>
+   <li><p><code>UNO_AC=("on" | "off" | "dynamic-only" | "single-user" |
+        "single-default-user")</code><br>
+        The general ac mode</p></li>
+	<li></p><code>UNO_AC_SERVICE=</code><em>service-name</em>
+	    <code>[optional]</code><br>
+        This overrides ac singleton service name to be used</p></li>
+	<li><p><code>UNO_AC_SINGLEUSER=(<em>UserId</em>|<em>&lt;nothing&gt;</em>)
+	    [optional]</code><br>
+        The initial context runs with this user id or with default policy.
+		In this case, the <code>UNO_AC</code> has to be set to
+		<code>"single-user"</code> or <code>"single-default-user"</code>.
+		</p></li>
+   <li><p><code>UNO_AC_USERCACHE_SIZE=<em>n</em></code><br>
+	   This value maps to the component context entry
+	   <code>/implementations/com.sun.star.security.comp.stoc.AccessController/user-cache-size</code>,
+	   denoting the number of user permission sets to be cached before
+	   calling the policy (lru cache).</p></li>
+   <li><p><code>UNO_AC_FILEPOLICY=<em>file-url</em></code><br>
+	   This value maps to the component context entry
+	   <code>/implementations/com.sun.star.security.comp.stoc.FilePolicy/file-name</code>
+	   denoting the file URL to read the user permission sets from.  The
+	   file policy service implementation of
+	   <code>stoc/source/security</code> is installed.</p></li>
+</ul>
+<p><a name="recurring_calls"><b>Recurring Calls</b></a></p>
+<p>When implementing an ac, there  is a specific issue concerning
+bootstrapping of the ac singleton.
+The ac is (to be) used in every service implementation code and has to cope with the situation that it is called recursively.
+This can occur when the ac implementation initially raises the policy singleton object which checks permissions.</p>
+<p>A (possible) solution for this is to let recurring
+<code>checkPermission()</code> pass unchecked.
+This assumes that one knows implementation details of the underlying policy,
+but one generally don't feel well allowing unchecked permission grants, even
+for a short time.</p>
+<p>A better (safer) solution for this problem is that you shift the time a
+permission is checked.
+Any recurring <code>checkPermission()</code> call will be passed unchecked, but the permission and user context is saved for later execution (when everything is initialized).
+For a clearer distinction that an access violation occurred during bootstrapping of the ac, this violation should not be notified using an <code>AccessControlException</code>, but a different <code>RuntimeException</code>, such as,  <code>DeploymentException</code> (yet to be specified) <!-- xxx todo -->.
+The only drawback of this solution is that an error notification is not sent as
+soon as possible.</p>
+<p>Marking a stack, one commonly uses thread-local storage (tls).
+When calling an unknown implementation (e.g., the policy singleton) a tls slot has to be marked, thus one can recognize a recursive call.
+When recognizing a recursive call, the demanded permission and calling user have to be queued, performing the check later and the call is passed.
+</p>
+<p><a name="performance_considerations"><b>Performance Considerations</b></a></p>
+<p>The ac implementation uses caching of user permission sets
+(<code>/services/com.sun.star.security.AccessController/cache-size</code>)
+for the reason that a permission description has to be parsed (e.g.,
+extracting port numbers).
+Parsing a permission is performed only once, so any ongoing permission check (when the chain of granted permissions is read) can be done once, then using the parsed permission description for checking. <!-- rh: Check that sense of last sentence is OK. -->
+</p>
+<p><a name="file_policy"><b>File Policy Implementation</b></a></p>
+<p>The file policy implementation of <code>stoc/source/security</code>
+(implementation name <code>com.sun.star.comp.stoc.FilePolicy</code> is a
+simple policy reading from policy files.</p>
+<p>The structure of those files is <!-- structure is -->very similar to those of
+<a href="http://java.sun.com/j2se/1.4/docs/guide/security/permissions.html">Java policy files</a>, e.g.:</p>
+
+<table width="100%" bgcolor="#ffffaa"><tr><td><pre>
+grant user "dbo" {
+permission com.sun.star.io.FilePermission
+    "file:///home/dbo/-", "read,write,execute,delete";
+};
+
+grant user "jbu" {
+permission com.sun.star.io.FilePermission
+    "file:///home/jbu/-", "read,write,execute,delete";
+};
+
+// permission granted to everyone
+grant {
+permission com.sun.star.io.FilePermission
+    "file:///tmp/-", "read,write,execute,delete";
+};
+</pre></td></tr></table>
+</td></tr>
+
+<TR><TD BGCOLOR="#666699">
+  <H3><FONT COLOR="#ffffff" SIZE=4>
+  <a name="todos">Things left to do...</a></FONT></H3>
+</TD></TR>
+<TR><TD>
+The following items are still on the to-do list:
+<ul>
+<li><p><b>[high priority]: </b><br>
+The main work left is reviewing all ac relevant code and inserting permission checks.
+In general, this concerns resource access, for example, file io and sockets.
+Memory and CPU resources cannot be limited effectively.
+More than the above described permission types may come, entering the API,
+ac, and policy implementation.</p>
+<p>It is commonly agreed that security checks are implemented on the component level (UNO available) rather than in the base libraries, such as, <code>sal</code>.
+Checking on component level is much more flexible, which may be needed to improve performance, but this may also lead to more forgotten checks.</p>
+<p>A list of all client code that has to be reviewed will be published
+<a href="../tasks/access_control_review.html">here</a>.
+If you find any ac relevant code that which needs be revisited, but you don't have cvs rights to do it, <a href="mailto:Daniel.Boelzle@sun.com">eMail me</a> so I can append it to the list and contact the module owners.
+</p></li>
+<li><p><b>[mid priority]: </b><br>
+At present, the current context is not inherited by child threads being raised, so the user credentials are not accessible by the ac.  This has to be solved by introducing new thread C++/UNO thread classes doing this implicitly by copying the following properties:
+<ul>
+<li>access-control.user-credentials.*</li>
+<li>access-control.restriction (initially the parent thread's context)</li>
+</ul>
+</li>
+<li><p><b>[low priority]: </b><br>
+The current context is not transferred via the URP-UNO interprocess bridge.  It has to be transferred by transferring the above properties with little lack of performance (i.e., configurable).
+</p></li>
+<li><p><b>[low priority]: </b><br>
+The Java ac has to be integrated with the C++/UNO ac to run <a href="#untrusted_java">untrusted Java code</a> using the core Java API.
+</p>
+</li>
+</ul>
+</td></tr>
+
+<tr><td bgcolor="#666699">
+<p align=left><font color="#ffffff"> Author: <a href="mailto:Daniel.Boelzle@sun.com">
+<font color="#ffffff">Daniel B&ouml;lzle</font></a><br>
+<i>Copyright 2002 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303 USA.</i></font></p></td>
+</tr>
+</table>
+</body>
+</html>

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

Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/concept/unointro.html
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/concept/unointro.html?rev=1206895&view=auto
==============================================================================
--- incubator/ooo/ooo-site/trunk/content/udk/common/man/concept/unointro.html (added)
+++ incubator/ooo/ooo-site/trunk/content/udk/common/man/concept/unointro.html 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=http://wiki.services.openoffice.org/wiki/Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno" />
+  <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/concept/unointro.html
------------------------------------------------------------------------------
    svn:eol-style = native

Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/library_unloading.html
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/library_unloading.html?rev=1206895&view=auto
==============================================================================
--- incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/library_unloading.html (added)
+++ incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/library_unloading.html Sun Nov 27 22:49:46 2011
@@ -0,0 +1,14 @@
+<html>
+<head>
+<meta http-equiv="refresh" content="5; URL=http://udk.openoffice.org/common/man/spec/library_unloading.html">
+
+<meta HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8">
+</head>
+<body>
+<h2>The page has moved to</h2>
+<p><a 
+href="http://udk.openoffice.org/common/man/spec/library_unloading.html">http://udk.openoffice.org/common/man/spec/library_unloading.html</a></p>
+<p>&nbsp;</p>
+<p>&nbsp;</p>
+</body>
+</html>

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

Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/ArchDoc.20020618.sxw
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/ArchDoc.20020618.sxw?rev=1206895&view=auto
==============================================================================
Binary file - no diff available.

Propchange: incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/ArchDoc.20020618.sxw
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream

Added: incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/BindException.idl
URL: http://svn.apache.org/viewvc/incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/BindException.idl?rev=1206895&view=auto
==============================================================================
--- incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/BindException.idl (added)
+++ incubator/ooo/ooo-site/trunk/content/udk/common/man/draft/scripting/BindException.idl Sun Nov 27 22:49:46 2011
@@ -0,0 +1,26 @@
+#ifndef __com_sun_star_scripting_BindException_idl__
+#define __com_sun_star_scripting_BindException_idl__
+
+#ifndef __com_sun_star_uno_Exception_idl__
+#include <com/sun/star/uno/Exception.idl>
+#endif
+
+module com {
+  module sun {
+    module star {
+      module scripting {
+      
+        /** Indicates that there is a problem in binding the method
+         */
+        exception BindException: com::sun::star::uno::Exception
+        {
+          /** The method that tried to be bound
+          */
+          string Method;
+        };
+      };
+    };
+  };
+};
+        
+#endif



Mime
View raw message