configmgr/source/inc/mergeddataprovider.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: mergeddataprovider.hxx,v $
  10  * $Revision: 1.7 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef CONFIGMGR_BACKEND_MERGEDDATAPROVIDER_HXX
  32 #define CONFIGMGR_BACKEND_MERGEDDATAPROVIDER_HXX
  33
  34 #include "sal/config.h"
  35
  36 #include "salhelper/simplereferenceobject.hxx"
  37
  38 #include "request.hxx"
  39 #include "requesttypes.hxx"
  40 #include "utility.hxx"
  41
  42 namespace configmgr
  43 {
  44 // ---------------------------------------------------------------------------
  45     namespace backend
  46     {
  47 // ---------------------------------------------------------------------------
  48     /** Listener interface for receiving notifications
  49         about changes to previously requested data
  50     */
  51     struct SAL_NO_VTABLE INodeDataListener
  52     {
  53         /** is called to indicate changes within the data being observed.
  54
  55             @param _aOriginalRequest
  56                 identifies the data that changed
  57         */
  58         virtual void dataChanged(ComponentRequest const & _aOriginalRequest) SAL_THROW(()) = 0;
  59     };
  60 // ---------------------------------------------------------------------------
  61
  62     /// Interface providing access to template (schema) data
  63     struct SAL_NO_VTABLE ITemplateDataProvider
  64     {
  65         /** loads a given template and returns it as return value
  66
  67             @param _aRequest
  68                 identifies the template to be loaded
  69
  70             @returns
  71                 A valid instance of the given template.
  72
  73                 <p> Currently a request with empty template name
  74                     will retrieve a group node holding all templates
  75                     of a component.
  76                 </p>
  77
  78             @throws com::sun::star::uno::Exception
  79                 if the template cannot be retrieved.
  80                 The exact exception being thrown may depend on the underlying backend.
  81         */
  82         virtual ResultHolder< TemplateInstance > getTemplateData(TemplateRequest const & _aRequest)
  83             SAL_THROW((com::sun::star::uno::Exception)) = 0;
  84     };
  85 // ---------------------------------------------------------------------------
  86
  87     /** Composite interface providing full access to merged configuration data
  88         from some data store.
  89
  90         <p> Loading and updating of data is supported.
  91             Support for notification depends on the backend.
  92         </p>
  93     */
  94     struct IMergedDataProvider
  95     : salhelper::SimpleReferenceObject
  96     , ITemplateDataProvider
  97     {
  98         /** loads merged data for a (partial) tree and returns it as return value.
  99
 100             @param _aRequest
 101                 identifies the component to be loaded
 102
 103             @param _pListener
 104                 a listener to observe subsequent changes to the data requested
 105
 106                 <p> If NULL, no notifications will be sent. </p>
 107
 108                 <p> Otherwise the listener will be notified of changes.
 109                     The listener must subsequently be removed by calling
 110                     <member>removeRequestListener</member>.
 111                     The listener must live at least until it is removed.
 112                 </p>
 113
 114             @returns
 115                 A valid component instance for the given request.
 116
 117             @throws com::sun::star::uno::Exception
 118                 if the node cannot be retrieved.
 119                 The exact exception being thrown may depend on the underlying backend.
 120         */
 121         virtual ResultHolder< ComponentInstance > getNodeData(ComponentRequest const & _aRequest,
 122                                             ITemplateDataProvider*   _aTemplateProvider,
 123                                             INodeDataListener * _pListener = NULL)
 124             SAL_THROW((com::sun::star::uno::Exception)) = 0;
 125
 126         /** remove a listener registered for a previous request.
 127             <p>This may also release some open resources for the request.</p>
 128
 129             @param _pListener
 130                 a listener that was passed to a previous succes
 131
 132              @param _aRequest
 133                 identifies the component associated with the listener
 134         */
 135         virtual void removeRequestListener(INodeDataListener * _pListener,
 136                                            const ComponentRequest& aRequest) SAL_THROW(()) = 0;
 137
 138         /** applies an update to the stored data.
 139
 140             @param _anUpdate
 141                 identifies the node to be updated and
 142                 describes the changes to be applied.
 143
 144             @throws com::sun::star::uno::Exception
 145                 if the node cannot be updated.
 146                 The exact exception being thrown may depend on the underlying backend.
 147         */
 148         virtual void updateNodeData(UpdateRequest const & _anUpdate)
 149             SAL_THROW((com::sun::star::uno::Exception)) = 0;
 150
 151         /** loads default data for a (partial) tree and returns it as return value
 152
 153             @param _aRequest
 154                 identifies the node to be loaded
 155
 156             @returns
 157                 A valid node instance for the default state of the given node.
 158
 159                 <p>May be NULL, if the node exists but has no default equivalent.</p>
 160
 161             @throws com::sun::star::uno::Exception
 162                 if the default cannot be retrieved.
 163                 The exact exception being thrown may depend on the underlying backend.
 164         */
 165         virtual ResultHolder< NodeInstance > getDefaultData(NodeRequest const & _aRequest)
 166             SAL_THROW((com::sun::star::uno::Exception)) = 0;
 167     };
 168
 169 // ---------------------------------------------------------------------------
 170     } // namespace backend
 171
 172 // ---------------------------------------------------------------------------
 173 } // namespace configmgr
 174
 175 #endif
 176