framework/inc/dispatch/interceptionhelper.hxx

   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 #ifndef INCLUDED_FRAMEWORK_INC_DISPATCH_INTERCEPTIONHELPER_HXX
  21 #define INCLUDED_FRAMEWORK_INC_DISPATCH_INTERCEPTIONHELPER_HXX
  22
  23 #include <macros/xinterface.hxx>
  24 #include <macros/generic.hxx>
  25 #include <general.h>
  26
  27 #include <com/sun/star/frame/XDispatchProviderInterception.hpp>
  28 #include <com/sun/star/frame/XDispatchProviderInterceptor.hpp>
  29 #include <com/sun/star/frame/XDispatchProvider.hpp>
  30 #include <com/sun/star/frame/XDispatch.hpp>
  31 #include <com/sun/star/frame/XFrame.hpp>
  32 #include <com/sun/star/frame/DispatchDescriptor.hpp>
  33
  34 #include <tools/wldcrd.hxx>
  35 #include <cppuhelper/implbase3.hxx>
  36 #include <cppuhelper/weakref.hxx>
  37
  38 #include <deque>
  39
  40 namespace framework{
  41
  42 /** @short      implements a helper to support interception with additional functionality.
  43
  44     @descr      This helper implements the complete XDispatchProviderInterception interface with
  45                 master/slave functionality AND using of optional features like registration of URL pattern!
  46
  47     @attention  Don't use this class as direct member - use it dynamicly. Do not derive from this class.
  48                 We hold a weakreference to our owner not to our superclass.
  49  */
  50 class InterceptionHelper : public  ::cppu::WeakImplHelper3<
  51                                      css::frame::XDispatchProvider,
  52                                      css::frame::XDispatchProviderInterception,
  53                                      css::lang::XEventListener >
  54 {
  55
  56     // structs, helper
  57
  58     /** @short bind an interceptor component to its URL pattern registration. */
  59     struct InterceptorInfo
  60     {
  61         /** @short reference to the interceptor component. */
  62         css::uno::Reference< css::frame::XDispatchProvider > xInterceptor;
  63
  64         /** @short it's registration for URL patterns.
  65
  66             @descr If the interceptor component does not support the optional interface
  67                    XInterceptorInfo, it will be registered for one pattern "*" by default.
  68                    That would make it possible to handle it in the same manner then real
  69                    registered interceptor objects and we must not implement any special code. */
  70         css::uno::Sequence< OUString > lURLPattern;
  71     };
  72
  73     /** @short implements a list of items of type InterceptorInfo, and provides some special
  74                functions on it.
  75
  76         @descr Because interceptor objects can be registered for URL patterns,
  77                it supports a wildcard search on all list items.
  78      */
  79     class InterceptorList : public ::std::deque< InterceptorInfo >
  80     {
  81         public:
  82
  83             /** @short search for an interceptor inside this list using it's reference.
  84
  85                 @param xInterceptor
  86                         points to the interceptor object, which should be located inside this list.
  87
  88                 @return An iterator object, which points directly to the located item inside this list.
  89                         In case no interceptor could be found, it points to the end of this list!
  90               */
  91             iterator findByReference(const css::uno::Reference< css::frame::XDispatchProviderInterceptor >& xInterceptor)
  92             {
  93                 css::uno::Reference< css::frame::XDispatchProviderInterceptor > xProviderInterface(xInterceptor, css::uno::UNO_QUERY);
  94                 iterator pIt;
  95                 for (pIt=begin(); pIt!=end(); ++pIt)
  96                 {
  97                     if (pIt->xInterceptor == xProviderInterface)
  98                         return pIt;
  99                 }
 100                 return end();
 101             }
 102
 103             /** @short search for an interceptor inside this list using it's reference.
 104
 105                 @param xInterceptor
 106                         points to the interceptor object, which should be located inside this list.
 107
 108                 @return An iterator object, which points directly to the located item inside this list.
 109                         In case no interceptor could be found, it points to the end of this list!
 110               */
 111             iterator findByPattern(const OUString& sURL)
 112             {
 113                 iterator pIt;
 114                 for (pIt=begin(); pIt!=end(); ++pIt)
 115                 {
 116                     sal_Int32              c        = pIt->lURLPattern.getLength();
 117                     const OUString* pPattern = pIt->lURLPattern.getConstArray();
 118
 119                     for (sal_Int32 i=0; i<c; ++i)
 120                     {
 121                         WildCard aPattern(pPattern[i]);
 122                         if (aPattern.Matches(sURL))
 123                             return pIt;
 124                     }
 125                 }
 126                 return end();
 127             }
 128     };
 129
 130     // member
 131
 132     private:
 133
 134         /** @short reference to the frame, which uses this instance to implement it's own interception.
 135
 136             @descr We hold a weak reference only, to make disposing operations easy. */
 137         css::uno::WeakReference< css::frame::XFrame > m_xOwnerWeak;
 138
 139         /** @short this interception helper implements the top level master of an interceptor list ...
 140                    but this member is the lowest possible slave! */
 141         css::uno::Reference< css::frame::XDispatchProvider > m_xSlave;
 142
 143         /** @short contains all registered interceptor objects. */
 144         InterceptorList m_lInterceptionRegs;
 145
 146         /** @short it regulates, which interceptor is used first.
 147                    The last or the first registered one. */
 148         static bool m_bPreferrFirstInterceptor;
 149
 150     // native interface
 151
 152     public:
 153
 154         /** @short creates a new interception helper instance.
 155
 156             @param xOwner
 157                     points to the frame, which use this instances to support it's own interception interfaces.
 158
 159             @param xSlave
 160                     an outside creates dispatch provider, which has to be used here as lowest slave "interceptor".
 161          */
 162         InterceptionHelper(const css::uno::Reference< css::frame::XFrame >&            xOwner,
 163                            const css::uno::Reference< css::frame::XDispatchProvider >& xSlave);
 164
 165     protected:
 166
 167         /** @short standard destructor.
 168
 169             @descr This method destruct an instance of this class and clear some member.
 170                    This method is protected, because its not allowed to use this class as a direct member!
 171                    You MUST use a dynamical instance (pointer). That's the reason for a protected dtor.
 172          */
 173         virtual ~InterceptionHelper();
 174
 175     // uno interface
 176
 177     public:
 178
 179         // XDispatchProvider
 180
 181         /** @short  query for a dispatch, which implements the requested feature.
 182
 183             @descr  We search inside our list of interception registrations, to locate
 184                     any interested interceptor. In case no interceptor exists or nobody is
 185                     interested on this URL our lowest slave will be used.
 186
 187             @param  aURL
 188                         describes the requested dispatch functionality.
 189
 190             @param  sTargetFrameName
 191                         the name of the target frame or a special name like "_blank", "_top" ...
 192                         Won't be used here ... but may by one of our registered interceptor objects
 193                         or our slave.
 194
 195             @param  nSearchFlags
 196                         optional search parameter for targeting, if sTargetFrameName isn't a special one.
 197
 198             @return A valid dispatch object, if any interceptor or at least our slave is interested on the given URL;
 199                     or NULL otherwise.
 200          */
 201         virtual css::uno::Reference< css::frame::XDispatch > SAL_CALL queryDispatch(const css::util::URL&  aURL            ,
 202                                                                                     const OUString& sTargetFrameName,
 203                                                                                           sal_Int32        nSearchFlags    )
 204             throw(css::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 205
 206         // XDispatchProvider
 207
 208         /** @short implements an optimized queryDispatch() for remote.
 209
 210             @descr It capsulate more than one queryDispatch() requests and return a lits of dispatch objects
 211                    as result. Because both lists (in and out) coreespond together, it's not allowed to
 212                    pack it - means suppress NULL references!
 213
 214             @param lDescriptor
 215                     a list of queryDispatch() arguments.
 216
 217             @return A list of dispatch objects.
 218          */
 219         virtual css::uno::Sequence< css::uno::Reference< css::frame::XDispatch > > SAL_CALL queryDispatches(const css::uno::Sequence< css::frame::DispatchDescriptor >& lDescriptor)
 220             throw(css::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 221
 222         // XDispatchProviderInterception
 223
 224         /** @short      register an interceptor.
 225
 226             @descr      Somebody can register himself to intercept all or some special dispatches.
 227                         It's depend from his supported interfaces. If he implement XInterceptorInfo
 228                         he his called for some special URLs only - otherwise we call it for every request!
 229
 230             @attention  We don't check for double registrations here!
 231
 232             @param      xInterceptor
 233                         reference to interceptor, which wish to be registered here.
 234
 235             @throw      A RuntimeException if the given reference is NULL!
 236          */
 237         virtual void SAL_CALL registerDispatchProviderInterceptor(const css::uno::Reference< css::frame::XDispatchProviderInterceptor >& xInterceptor)
 238             throw(css::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 239
 240         // XDispatchProviderInterception
 241
 242         /** @short      release an interceptor.
 243
 244             @descr      Remove the registered interceptor from our internal list
 245                         and delete all special information about it.
 246
 247             @param      xInterceptor
 248                         reference to the interceptor, which wish to be deregistered.
 249
 250             @throw      A RuntimeException if the given reference is NULL!
 251          */
 252         virtual void SAL_CALL releaseDispatchProviderInterceptor( const css::uno::Reference< css::frame::XDispatchProviderInterceptor >& xInterceptor ) throw( css::uno::RuntimeException, std::exception ) SAL_OVERRIDE;
 253
 254         // XEventListener
 255
 256         /** @short      Is called from our owner frame, in case he will be disposed.
 257
 258             @descr      We have to relaease all references to him then.
 259                         Normally we will die by ref count too ...
 260          */
 261         virtual void SAL_CALL disposing(const css::lang::EventObject& aEvent)
 262             throw(css::uno::RuntimeException, std::exception) SAL_OVERRIDE;
 263
 264 }; // class InterceptionHelper
 265
 266 } // namespace framework
 267
 268 #endif // INCLUDED_FRAMEWORK_INC_DISPATCH_INTERCEPTIONHELPER_HXX
 269
 270 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */