/*************************************************************************
 *
 *  $RCSfile: XDynamicResultSet.idl,v $
 *
 *  $Revision: 1.13 $
 *
 *  last change: $Author: hr $ $Date: 2003/03/26 13:57:56 $
 *
 *  The Contents of this file are made available subject to the terms of
 *  either of the following licenses
 *
 *         - GNU Lesser General Public License Version 2.1
 *         - Sun Industry Standards Source License Version 1.1
 *
 *  Sun Microsystems Inc., October, 2000
 *
 *  GNU Lesser General Public License Version 2.1
 *  =============================================
 *  Copyright 2000 by Sun Microsystems, Inc.
 *  901 San Antonio Road, Palo Alto, CA 94303, USA
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License version 2.1, as published by the Free Software Foundation.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston,
 *  MA  02111-1307  USA
 *
 *
 *  Sun Industry Standards Source License Version 1.1
 *  =================================================
 *  The contents of this file are subject to the Sun Industry Standards
 *  Source License Version 1.1 (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.openoffice.org/license.html.
 *
 *  Software provided under this License is provided on an "AS IS" basis,
 *  WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
 *  WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS,
 *  MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING.
 *  See the License for the specific provisions governing your rights and
 *  obligations concerning the Software.
 *
 *  The Initial Developer of the Original Code is: Sun Microsystems, Inc.
 *
 *  Copyright: 2000 by Sun Microsystems, Inc.
 *
 *  All Rights Reserved.
 *
 *  Contributor(s): _______________________________________
 *
 *
 ************************************************************************/
#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>
*/

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
