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