/************************************************************************* * * OpenOffice.org - a multi-platform office productivity suite * * $RCSfile: cacheddataprovider.hxx,v $ * * $Revision: 1.6 $ * * last change: $Author: ihi $ $Date: 2007-11-23 14:16:19 $ * * The Contents of this file are made available subject to * the terms of GNU Lesser General Public License Version 2.1. * * * GNU Lesser General Public License Version 2.1 * ============================================= * Copyright 2005 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 * ************************************************************************/ /* PLEASE DON'T DELETE ANY COMMENT LINES, ALSO IT'S UNNECESSARY. */ #ifndef CONFIGMGR_BACKEND_CACHEDDATAPROVIDER_HXX #define CONFIGMGR_BACKEND_CACHEDDATAPROVIDER_HXX #ifndef CONFIGMGR_BACKEND_REQUEST_HXX_ #include "request.hxx" #endif #ifndef CONFIGMGR_BACKEND_REQUESTTYPES_HXX_ #include "requesttypes.hxx" #endif #ifndef CONFIGMGR_UTILITY_HXX_ #include "utility.hxx" #endif #ifndef INCLUDED_SHARABLE_TREEFRAGMENT_HXX #include "treefragment.hxx" #endif #ifndef _RTL_REF_HXX_ #include #endif namespace configmgr { // --------------------------------------------------------------------------- namespace backend { // --------------------------------------------------------------------------- typedef data::TreeAddress CacheLocation; // --------------------------------------------------------------------------- struct IDirectDataProvider; struct ICachedDataNotifier; // --------------------------------------------------------------------------- /** Interface providing access to configuration data from some backend, which is cached in a shared data cache. */ struct SAL_NO_VTABLE ICachedDataProvider : Refcounted { /** locates data of a component in the cache.

If the data isn't in the cache it is loaded from the backend.

When the caller is done with the data, freeComponent should be called.

@param _aRequest identifies the component to be loaded. @returns data that can be used to locate the loaded data in the cache. @throws com::sun::star::uno::Exception if loading the data fails. The exact exception being thrown may depend on the underlying backend. */ virtual CacheLocation loadComponent(ComponentRequest const & _aRequest) CFG_UNO_THROW_ALL() = 0; /** releases data of a component from the cache.

Should be called when a client is done with a component. Each calls to loadComponent should be balanced by exactly one call to freeComponent.

@param _aRequest identifies a component previously loaded via loadComponent. @returns data that can be used to locate the loaded data in the cache. */ virtual void freeComponent(ComponentRequest const & _aRequest) CFG_NOTHROW() = 0; /** refreshes data of an existing component from the backend

If the data is in the cache already, it is refreshed from the backend and the change are notified to all registered listeners.

If the data isn't in the cache nothing is done and a NULL location is returned.

Note: the caller must not hold any lock on the cache line affected.

@param _aRequest identifies the component to be refreshed. @returns data that can be used to locate the refreshed data in the cache.

If there is no data to refresh a NULL location is returned.

@throws com::sun::star::uno::Exception if loading the data fails. The exact exception being thrown may depend on the underlying backend. */ virtual CacheLocation refreshComponent(ComponentRequest const & _aRequest) CFG_UNO_THROW_ALL() = 0; /** refreshes data of all existing components from the backend

If the data is in the cache already, it is refreshed from the backend and the changes are notified to all registered listeners.

If the data isn't in the cache nothing is done and a NULL location is returned.

Note: the caller must not hold any lock on the cache line affected.

@throws com::sun::star::uno::Exception if loading the data fails. The exact exception being thrown may depend on the underlying backend. */ virtual void refreshAllComponents() CFG_UNO_THROW_ALL() = 0; /** flushes data of all pending updates from cache to the backend(s) @throws com::sun::star::uno::Exception if flushing the data fails. The exact exception being thrown may depend on the underlying backend. */ virtual void flushPendingUpdates() CFG_UNO_THROW_ALL() = 0; /** locates a template in the cache.

If the data isn't in the cache it is loaded from the backend.

Note: the caller must not hold any lock on the cache line affected.

@param _aRequest identifies the template to be loaded. @returns data that can be used to locate the template data in the cache. @throws com::sun::star::uno::Exception if loading the template data fails. The exact exception being thrown may depend on the underlying backend. */ virtual CacheLocation loadTemplate(TemplateRequest const & _aRequest) CFG_UNO_THROW_ALL() = 0; /** saves changes to the backend and notifies them to registered listeners.

Must be called after the changes have been applied to the cache and before any subsequent changes to the same component.

Notifications are guaranteed to be delivered before any subsequent changes to the same component are possible.

Note: the caller must hold a read lock (but no write lock) on the cache line affected during the call.

@param _anUpdate identifies the node that changed and describes the changes. @throws com::sun::star::uno::Exception if saving the changes to the backend fails. The exact exception being thrown may depend on the underlying backend. */ virtual void saveAndNotify(UpdateRequest const & _anUpdate) CFG_UNO_THROW_ALL() = 0; /** dispose this object and its cache and close the backend

discards the cache and flushes the backend.

*/ virtual void dispose() CFG_UNO_THROW_RTE() = 0; /** @returns an object that can used to broadcast changes done through this object.

The object returned is guaranteed to live as long as this ICachedDataProvider lives.

*/ virtual ICachedDataNotifier & getNotifier() CFG_NOTHROW() = 0; /** @returns an object that can be used to retrieve owned copies of the data, defaults and templates.

The object returned is guaranteed to live as long as this ICachedDataProvider lives.

*/ virtual IDirectDataProvider & getDirectDataProvider() CFG_NOTHROW() = 0; }; // --------------------------------------------------------------------------- /** Listener interface for observing changes in the cache managed by a ICachedDataProvider */ struct SAL_NO_VTABLE ICachedDataListener : Refcounted { /// is called when the provider is closing down virtual void disposing(ICachedDataProvider & _rProvider) CFG_NOTHROW() = 0; /// is called when a new component was loaded into the cache. virtual void componentCreated(ComponentRequest const & _aComponent) CFG_NOTHROW() = 0; /// is called when data of an already loaded component changed in the cache. virtual void componentChanged(UpdateRequest const & _anUpdate) CFG_NOTHROW() = 0; }; // --------------------------------------------------------------------------- /** Interface providing a multicasting service for changes to the cache managed by a ICachedDataProvider */ struct SAL_NO_VTABLE ICachedDataNotifier { // firing notifications. /// notify all registered listeners and close down this notifier virtual void dispose(ICachedDataProvider & _rProvider) CFG_NOTHROW() = 0; /** notify a new component to all registered listeners.

Must be called after the component has been created in the cache.

*/ virtual void notifyCreated(ComponentRequest const & _aComponent) CFG_NOTHROW() = 0; /** notify changed data to all registered listeners.

Must be called after the change has been applied to the cache and before any subsequent changes to the same component.

*/ virtual void notifyChanged(UpdateRequest const & _anUpdate) CFG_NOTHROW() = 0; // listener registration. typedef rtl::Reference ListenerRef; /// register a listener for observing changes to the cached data virtual void addListener(ListenerRef _xListener) CFG_NOTHROW() = 0; /// unregister a listener previously registered virtual void removeListener(ListenerRef _xListener) CFG_NOTHROW() = 0; }; // --------------------------------------------------------------------------- } // namespace backend // --------------------------------------------------------------------------- } // namespace configmgr #endif