| /************************************************************** |
| * |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| * |
| *************************************************************/ |
| |
| |
| #ifndef __com_sun_star_ucb_XDynamicResultSet_idl__ |
| #define __com_sun_star_ucb_XDynamicResultSet_idl__ |
| |
| #ifndef __com_sun_star_lang_XComponent_idl__ |
| #include <com/sun/star/lang/XComponent.idl> |
| #endif |
| |
| #ifndef __com_sun_star_ucb_XDynamicResultSetListener_idl__ |
| #include <com/sun/star/ucb/XDynamicResultSetListener.idl> |
| #endif |
| |
| #ifndef __com_sun_star_ucb_ListenerAlreadySetException_idl__ |
| #include <com/sun/star/ucb/ListenerAlreadySetException.idl> |
| #endif |
| |
| #ifndef __com_sun_star_sdbc_XResultSet_idl__ |
| #include <com/sun/star/sdbc/XResultSet.idl> |
| #endif |
| |
| #ifndef __com_sun_star_ucb_AlreadyInitializedException_idl__ |
| #include <com/sun/star/ucb/AlreadyInitializedException.idl> |
| #endif |
| |
| #ifndef __com_sun_star_ucb_ServiceNotFoundException_idl__ |
| #include <com/sun/star/ucb/ServiceNotFoundException.idl> |
| #endif |
| |
| //============================================================================= |
| |
| module com { module sun { module star { module ucb { |
| |
| //============================================================================= |
| /** Provides read access to a <type>ContentResultSet</type>. |
| |
| <p> |
| You can either get a simple static <type>ContentResultSet</type> or you can |
| listen to change-notifications and than swap from the old to a new |
| <type>ContentResultSet</type>. |
| </p> |
| |
| <p>The following describes the dynamic use:</p> |
| |
| <p> |
| <type>XDynamicResultSet</type> provides the possibility to get notifications |
| about changes on a <type>ContentResultSet</type> and have an |
| listener-controlled update from one version to the next version. Two |
| <type>ContentResultSet</type> implementations were given to the listener in |
| the first notification as interface |
| <type scope="com::sun::star::sdbc">XResultSet</type>. |
| </p> |
| |
| <p> |
| To get notifications the listener has to be of type |
| <type>XDynamicResultSetListener</type>. |
| </p> |
| |
| <p> |
| After registration you will get notifications for events of type |
| <type>ListEvent</type>. |
| </p> |
| |
| <p> |
| The calling of <member>XDynamicResultSetListener::notify</member> has |
| to happen in an own thread, because it could take a longer time and any |
| actions til the listener returns the call. So don't block the notify-causing |
| action. |
| </p> |
| |
| <p> |
| While one notify-call is going on: |
| </p> |
| |
| <ol> |
| <li> The listener is allowed to access both <type>ContentResultSet</type>s, |
| they must be both valid.</li> |
| <li> It is not allowed to start a second notify-call.</li> |
| <li> All addditional things we want to send as notification are to be |
| queued.</li> |
| <li> Any other calls are to be accepted and treated.</li> |
| </ol> |
| |
| <p> |
| After the listener has returned the notify-call: |
| </p> |
| |
| <ol> |
| <li> The listener is allowed to access the new |
| <type>ContentResultSet</type>. The new one is first assigned in the |
| WELCOME-event and than the ResultSets are always swapped.</li> |
| <li> The listener is not allowed to access the old |
| <type>ContentResultSet</type>.</li> |
| </ol> |
| */ |
| |
| published interface XDynamicResultSet: com::sun::star::lang::XComponent |
| { |
| //------------------------------------------------------------------------- |
| /** Call this, if you don't care about any changes. |
| |
| @returns |
| an <type scope="com::sun::star::sdbc">XResultSet</type> that is |
| implemented as <type>ContentResultSet</type>. Its content will never |
| change. |
| |
| @trows ListenerAlreadySetException |
| if someone already has registered as listener via |
| <member>XDynamicResultSet::setListener</member> or if someone has |
| established a connection to a <type>CachedDynamicResultSet</type> |
| via <member>XDynamicResultSet::connectToCache</member>. |
| */ |
| com::sun::star::sdbc::XResultSet getStaticResultSet() |
| raises( com::sun::star::ucb::ListenerAlreadySetException ); |
| |
| //------------------------------------------------------------------------- |
| /** Call this, if you want to get notifications about changes. |
| |
| <p>The implementor has to call |
| <member scope="com::sun::star::lang">XComponent::addEventListener</member> |
| in this method, so that we can call |
| <member scope="com::sun::star::lang">XEventListener::disposing</member> |
| at the listener |
| |
| @param Listener |
| a listener for resultset notifications |
| |
| @throws ListenerAlreadySetException |
| if this method is called more than once during the life of the |
| implementation object or if this method is called if someone already |
| has fetched the <type>ContentResultSet</type> via |
| <member>XDynamicResultSet::getStaticResultSet</member>. |
| |
| */ |
| void setListener( [in] XDynamicResultSetListener Listener ) |
| raises( com::sun::star::ucb::ListenerAlreadySetException ); |
| |
| //------------------------------------------------------------------------- |
| /** Connects this to a <type>CachedDynamicResultSet</type> for optimized |
| remote data transport. |
| |
| <p>This method creates a <type>CachedDynamicResultSetStub</type> |
| and sets it as Source to the given cache. |
| |
| <p>After this method has returned you can and have to use the given |
| result set cache for further access. |
| |
| @param Cache |
| has to be an implementation of the service |
| <type>CachedDynamicResultSet</type>. In particular it has to support |
| the interface <type>XSourceInitialization</type>. |
| |
| @throws ListenerAlreadySetException |
| if if someone already has fetched the <type>ContentResultSet</type> via |
| <member>XDynamicResultSet::getStaticResultSet</member>. |
| |
| @throws AlreadyInitializedException |
| if <var>Cache</var> was already initialized with another source. |
| |
| @throws ServiceNotFoundException |
| */ |
| void connectToCache( [in] XDynamicResultSet Cache ) |
| raises( com::sun::star::ucb::ListenerAlreadySetException |
| , com::sun::star::ucb::AlreadyInitializedException |
| , com::sun::star::ucb::ServiceNotFoundException ); |
| |
| //------------------------------------------------------------------------- |
| /** Using this method you can get information, whether the offered |
| <type>ContentResultSet</type>s are sorted or filtered etc correctly as |
| demanded during the creation of the <type>XDynamicResultSet</type>. |
| |
| @returns |
| zero or more constants of the <type>ContentResultSetCapability</type> |
| constants group. |
| */ |
| short getCapabilities(); |
| }; |
| |
| //============================================================================= |
| |
| }; }; }; }; |
| |
| #endif |