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