INTEGRATION: CWS dba203a (1.4.76); FILE MERGED

2006/03/16 10:27:55 fs 1.4.76.1: #i63162# added comment on ownership of the document

1 files changed, 13 insertions, 2 deletions

diff --git a/offapi/com/sun/star/sdb/XDocumentDataSource.idl b/offapi/com/sun/star/sdb/XDocumentDataSource.idl
index 6fed101d17a1..65d700975af4 100644
--- a/offapi/com/sun/star/sdb/XDocumentDataSource.idl
+++ b/offapi/com/sun/star/sdb/XDocumentDataSource.idl
@@ -4,9 +4,9 @@
  *
  *  $RCSfile: XDocumentDataSource.idl,v $
  *
- *  $Revision: 1.4 $
+ *  $Revision: 1.5 $
  *
- *  last change: $Author: hr $ $Date: 2005-09-23 11:54:26 $
+ *  last change: $Author: obo $ $Date: 2006-03-29 12:27:36 $
  *
  *  The Contents of this file are made available subject to
  *  the terms of GNU Lesser General Public License Version 2.1.
@@ -57,6 +57,17 @@ interface XDocumentDataSource
         which the data source is based on.
 
         <p>The component returned by this attribute is an <type>OfficeDatabaseDocument</type>.</p>
+
+        <p>Though there is a 1-to-1 relationship between database documents and data sources,
+        each of the two can exist without its counterpart, but create this counterpart on request
+        only. As a consequence, the document obtained via this attribute might be newly created,
+        which implies that the caller is now responsible for it. In particular, the caller is
+        responsible for calling <member scope="com::sun::star::util">XCloseable::close</member>
+        on the document as soon as it's not needed anymore.</p>
+
+        <p>Additionally, if the caller does long-lasting processing on the document, it's advised
+        to add itself as <type scope="com::sun::star::util">XCloseListener</type> to the document,
+        to prevent closing as long as the processing lasts.</p>
     */
     [readonly, attribute] XOfficeDatabaseDocument DatabaseDocument;
 };