offapi/com/sun/star/ucb/XDynamicResultSet.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XDynamicResultSet.idl,v $
  10  * $Revision: 1.16 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_ucb_XDynamicResultSet_idl__
  31 #define __com_sun_star_ucb_XDynamicResultSet_idl__
  32
  33 #ifndef __com_sun_star_lang_XComponent_idl__
  34 #include <com/sun/star/lang/XComponent.idl>
  35 #endif
  36
  37 #ifndef __com_sun_star_ucb_XDynamicResultSetListener_idl__
  38 #include <com/sun/star/ucb/XDynamicResultSetListener.idl>
  39 #endif
  40
  41 #ifndef __com_sun_star_ucb_ListenerAlreadySetException_idl__
  42 #include <com/sun/star/ucb/ListenerAlreadySetException.idl>
  43 #endif
  44
  45 #ifndef __com_sun_star_sdbc_XResultSet_idl__
  46 #include <com/sun/star/sdbc/XResultSet.idl>
  47 #endif
  48
  49 #ifndef __com_sun_star_ucb_AlreadyInitializedException_idl__
  50 #include <com/sun/star/ucb/AlreadyInitializedException.idl>
  51 #endif
  52
  53 #ifndef __com_sun_star_ucb_ServiceNotFoundException_idl__
  54 #include <com/sun/star/ucb/ServiceNotFoundException.idl>
  55 #endif
  56
  57 //=============================================================================
  58
  59 module com { module sun { module star { module ucb {
  60
  61 //=============================================================================
  62 /** Provides read access to a <type>ContentResultSet</type>.
  63
  64     <p>
  65     You can either get a simple static <type>ContentResultSet</type> or you can
  66     listen to change-notifications and than swap from the old to a new
  67     <type>ContentResultSet</type>.
  68     </p>
  69
  70     <p>The following describes the dynamic use:</p>
  71
  72     <p>
  73     <type>XDynamicResultSet</type> provides the possibility to get notifications
  74     about changes on a <type>ContentResultSet</type> and have an
  75     listener-controlled update from one version to the next version. Two
  76     <type>ContentResultSet</type> implementations were given to the listener in
  77     the first notification as interface
  78     <type scope="com::sun::star::sdbc">XResultSet</type>.
  79     </p>
  80
  81     <p>
  82     To get notifications the listener has to be of type
  83     <type>XDynamicResultSetListener</type>.
  84     </p>
  85
  86     <p>
  87     After registration you will get notifications for events of type
  88     <type>ListEvent</type>.
  89     </p>
  90
  91     <p>
  92     The calling of <member>XDynamicResultSetListener::notify</member> has
  93     to happen in an own thread, because it could take a longer time and any
  94     actions     til the listener returns the call. So don't block the notify-causing
  95     action.
  96     </p>
  97
  98     <p>
  99     While one notify-call is going on:
 100     </p>
 101
 102     <ol>
 103       <li> The listener is allowed to access both <type>ContentResultSet</type>s,
 104          they must be both valid.</li>
 105       <li> It is not allowed to start a second notify-call.</li>
 106       <li> All addditional things we want to send as notification are to be
 107          queued.</li>
 108       <li> Any other calls are to be accepted and treated.</li>
 109     </ol>
 110
 111     <p>
 112     After the listener has returned the notify-call:
 113     </p>
 114
 115     <ol>
 116     <li> The listener is allowed to access the new
 117          <type>ContentResultSet</type>. The new one is first assigned in the
 118          WELCOME-event and than the ResultSets are always swapped.</li>
 119     <li> The listener is not allowed to access the old
 120          <type>ContentResultSet</type>.</li>
 121     </ol>
 122 */
 123
 124 published interface XDynamicResultSet: com::sun::star::lang::XComponent
 125 {
 126     //-------------------------------------------------------------------------
 127     /** Call this, if you don't care about any changes.
 128
 129         @returns
 130         an <type scope="com::sun::star::sdbc">XResultSet</type> that is
 131         implemented as <type>ContentResultSet</type>. Its content will never
 132         change.
 133
 134         @trows ListenerAlreadySetException
 135         if someone already has registered as listener via
 136         <member>XDynamicResultSet::setListener</member> or if someone has
 137         established a connection to a <type>CachedDynamicResultSet</type>
 138         via <member>XDynamicResultSet::connectToCache</member>.
 139     */
 140     com::sun::star::sdbc::XResultSet getStaticResultSet()
 141         raises( com::sun::star::ucb::ListenerAlreadySetException );
 142
 143     //-------------------------------------------------------------------------
 144     /** Call this, if you want to get notifications about changes.
 145
 146         <p>The implementor has to call
 147         <member scope="com::sun::star::lang">XComponent::addEventListener</member>
 148         in this method, so that we can call
 149         <member scope="com::sun::star::lang">XEventListener::disposing</member>
 150         at the listener
 151
 152         @param Listener
 153         a listener for resultset notifications
 154
 155         @throws ListenerAlreadySetException
 156         if this method is called more than once during the life of the
 157         implementation object or if this method is called if someone already
 158         has     fetched the <type>ContentResultSet</type> via
 159         <member>XDynamicResultSet::getStaticResultSet</member>.
 160
 161     */
 162     void setListener( [in] XDynamicResultSetListener Listener )
 163         raises( com::sun::star::ucb::ListenerAlreadySetException );
 164
 165     //-------------------------------------------------------------------------
 166     /** Connects this to a <type>CachedDynamicResultSet</type> for optimized
 167         remote data transport.
 168
 169         <p>This method creates a <type>CachedDynamicResultSetStub</type>
 170         and sets it as Source to the given cache.
 171
 172         <p>After this method has returned you can and have to use the given
 173         result set cache for further access.
 174
 175         @param Cache
 176         has to be an implementation of the service
 177         <type>CachedDynamicResultSet</type>. In particular it has to support
 178         the interface <type>XSourceInitialization</type>.
 179
 180         @throws ListenerAlreadySetException
 181         if if someone already has fetched the <type>ContentResultSet</type> via
 182         <member>XDynamicResultSet::getStaticResultSet</member>.
 183
 184         @throws AlreadyInitializedException
 185         if <var>Cache</var> was already initialized with another source.
 186
 187         @throws ServiceNotFoundException
 188     */
 189     void connectToCache( [in] XDynamicResultSet Cache )
 190         raises( com::sun::star::ucb::ListenerAlreadySetException
 191                 , com::sun::star::ucb::AlreadyInitializedException
 192                 , com::sun::star::ucb::ServiceNotFoundException );
 193
 194     //-------------------------------------------------------------------------
 195     /** Using this method you can get information, whether the offered
 196         <type>ContentResultSet</type>s are sorted or filtered etc correctly as
 197         demanded during the creation of the <type>XDynamicResultSet</type>.
 198
 199         @returns
 200         zero or more constants of the <type>ContentResultSetCapability</type>
 201         constants group.
 202     */
 203     short getCapabilities();
 204 };
 205
 206 //=============================================================================
 207
 208 }; }; }; };
 209
 210 #endif