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