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

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