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