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
  20
  21 module com { module sun { module star { module ucb {
  22
  23 /** Provides read access to a ContentResultSet.
  24
  25     <p>
  26     You can either get a simple static ContentResultSet or you can
  27     listen to change-notifications and then swap from the old to a new
  28     ContentResultSet.
  29     </p>
  30
  31     <p>The following describes the dynamic use:</p>
  32
  33     <p>
  34     XDynamicResultSet provides the possibility to get notifications
  35     about changes on a ContentResultSet and have an
  36     listener-controlled update from one version to the next version. Two
  37     ContentResultSet implementations were given to the listener in
  38     the first notification as interface
  39     com::sun::star::sdbc::XResultSet.
  40     </p>
  41
  42     <p>
  43     To get notifications the listener has to be of type
  44     XDynamicResultSetListener.
  45     </p>
  46
  47     <p>
  48     After registration you will get notifications for events of type
  49     ListEvent.
  50     </p>
  51
  52     <p>
  53     The calling of XDynamicResultSetListener::notify() has
  54     to happen in an own thread, because it could take a longer time and any
  55     actions ??? until the listener returns the call. So don't block the notify-causing
  56     action.
  57     </p>
  58
  59     <p>
  60     While one notify-call is going on:
  61     </p>
  62
  63     <ol>
  64       <li> The listener is allowed to access both ContentResultSets,
  65          they must be both valid.</li>
  66       <li> It is not allowed to start a second notify-call.</li>
  67       <li> All additional things we want to send as notification are to be
  68          queued.</li>
  69       <li> Any other calls are to be accepted and treated.</li>
  70     </ol>
  71
  72     <p>
  73     After the listener has returned the notify-call:
  74     </p>
  75
  76     <ol>
  77     <li> The listener is allowed to access the new
  78          ContentResultSet. The new one is first assigned in the
  79          WELCOME-event and then the ResultSets are always swapped.</li>
  80     <li> The listener is not allowed to access the old
  81          ContentResultSet.</li>
  82     </ol>
  83 */
  84
  85 published interface XDynamicResultSet: com::sun::star::lang::XComponent
  86 {
  87     /** Call this, if you don't care about any changes.
  88
  89         @returns
  90         a com::sun::star::sdbc::XResultSet that is
  91         implemented as ContentResultSet. Its content will never
  92         change.
  93
  94         @throws ListenerAlreadySetException
  95         if someone already has registered as listener via
  96         XDynamicResultSet::setListener() or if someone has
  97         established a connection to a CachedDynamicResultSet
  98         via XDynamicResultSet::connectToCache().
  99     */
 100     com::sun::star::sdbc::XResultSet getStaticResultSet()
 101         raises( com::sun::star::ucb::ListenerAlreadySetException );
 102
 103     /** Call this, if you want to get notifications about changes.
 104
 105         <p>The implementor has to call
 106         com::sun::star::lang::XComponent::addEventListener()
 107         in this method, so that we can call
 108         com::sun::star::lang::XEventListener::disposing()
 109         at the listener
 110
 111         @param Listener
 112         a listener for result set notifications
 113
 114         @throws ListenerAlreadySetException
 115         if this method is called more than once during the life of the
 116         implementation object or if this method is called if someone already
 117         has fetched the ContentResultSet via
 118         XDynamicResultSet::getStaticResultSet().
 119
 120     */
 121     void setListener( [in] XDynamicResultSetListener Listener )
 122         raises( com::sun::star::ucb::ListenerAlreadySetException );
 123
 124     /** Connects this to a CachedDynamicResultSet for optimized
 125         remote data transport.
 126
 127         <p>This method creates a CachedDynamicResultSetStub
 128         and sets it as Source to the given cache.
 129
 130         <p>After this method has returned you can and have to use the given
 131         result set cache for further access.
 132
 133         @param Cache
 134         has to be an implementation of the service
 135         CachedDynamicResultSet. In particular it has to support
 136         the interface XSourceInitialization.
 137
 138         @throws ListenerAlreadySetException
 139         if someone already has fetched the ContentResultSet via
 140         XDynamicResultSet::getStaticResultSet().
 141
 142         @throws AlreadyInitializedException
 143         if <var>Cache</var> was already initialized with another source.
 144
 145         @throws ServiceNotFoundException
 146     */
 147     void connectToCache( [in] XDynamicResultSet Cache )
 148         raises( com::sun::star::ucb::ListenerAlreadySetException
 149                 , com::sun::star::ucb::AlreadyInitializedException
 150                 , com::sun::star::ucb::ServiceNotFoundException );
 151
 152     /** Using this method you can get information, whether the offered
 153         ContentResultSets are sorted or filtered etc correctly as
 154         demanded during the creation of the XDynamicResultSet.
 155
 156         @returns
 157         zero or more constants of the ContentResultSetCapability
 158         constants group.
 159     */
 160     short getCapabilities();
 161 };
 162
 163
 164 }; }; }; };
 165
 166 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */