framework/source/inc/loadenv/loadenv.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 #ifndef __FRAMEWORK_LOADENV_LOADENV_HXX_
  20 #define __FRAMEWORK_LOADENV_LOADENV_HXX_
  21
  22
  23 #include <loadenv/loadenvexception.hxx>
  24 #include <loadenv/actionlockguard.hxx>
  25 #include <threadhelp/threadhelpbase.hxx>
  26
  27 #include <com/sun/star/lang/IllegalArgumentException.hpp>
  28 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
  29 #include <com/sun/star/frame/XComponentLoader.hpp>
  30 #include <com/sun/star/frame/XFrameLoader.hpp>
  31 #include <com/sun/star/frame/XLoadEventListener.hpp>
  32 #include <com/sun/star/frame/XDispatchResultListener.hpp>
  33 #include <com/sun/star/frame/XFrame.hpp>
  34 #include <com/sun/star/io/IOException.hpp>
  35 #include <com/sun/star/uno/XComponentContext.hpp>
  36 #include <com/sun/star/util/URL.hpp>
  37
  38 #include <comphelper/mediadescriptor.hxx>
  39 #include <comphelper/sequenceashashmap.hxx>
  40 #include <cppuhelper/implbase2.hxx>
  41
  42
  43 namespace framework {
  44
  45 class QuietInteraction;
  46
  47 /** @short  implements general mechainsm for loading documents.
  48
  49     @descr  An instance of this class can be used inside the API calls
  50             XComponentLoader::loadComponentFromURL() and
  51             XDispatch::dispatch().
  52
  53     @author as96863
  54  */
  55 class LoadEnv : private ThreadHelpBase
  56 {
  57 public:
  58
  59     /** @short  enable/disable special features
  60                 of a load request.
  61
  62         @desrc  Such features must outcome without
  63                 any special parameters.
  64                 To make enableing/disabling of
  65                 features very easy (e.g. at the ctor of
  66                 this class) these values must be combinable
  67                 as flags. That means: its values must be in
  68                 range of [2^n]!
  69      */
  70     enum EFeature
  71     {
  72         /// we should be informed, if no feature is enabled :-)
  73         E_NO_FEATURE = 0,
  74         /// enable using of UI elements during loading (means progress, interaction handler etcpp.)
  75         E_WORK_WITH_UI = 1,
  76         /// enable loading of resources, which are not related to a target frame! (see concept of ContentHandler)
  77         E_ALLOW_CONTENTHANDLER = 2
  78     };
  79
  80     /** @short  classify a content.
  81
  82         @descr  The load environment must know, if a content
  83                 is related to a target frame or not. Only "visible"
  84                 components, which full fill the requirements of the
  85                 model-controller-view paradigm can be loaded into a frame.
  86                 Such contents are classified as E_CAN_BE_LOADED.
  87
  88                 But e.g. for the dispatch framework exists special ContentHandler
  89                 objects, which can load a content in "non visible" mode ...
  90                 and do not need a target frame for its operation. Such
  91                 ContentHandler e.g. plays sounds.
  92                 Such contents are classified as E_CAN_BE_HANDLED.
  93
  94                 And last but not least a content can be "not valid" in general.
  95      */
  96     enum EContentType
  97     {
  98         /// identifies a content, which seems to be invalid in general
  99         E_UNSUPPORTED_CONTENT,
 100         /// identifies a content, which can be used with a ContentHandler and is not related to a target frame
 101         E_CAN_BE_HANDLED,
 102         /// identifies a content, which can be loaded into a target frame
 103         E_CAN_BE_LOADED,
 104         /// special mode for non real loading, In such case the model is given directly!
 105         E_CAN_BE_SET
 106     };
 107
 108 private:
 109
 110     /** @short  reference to an uno service manager, which must be used
 111                 to created on needed services on demand.
 112      */
 113     css::uno::Reference< css::lang::XMultiServiceFactory > m_xSMGR;
 114
 115     /** @short  points to the frame, which uses this LoadEnv object
 116                 and must be used to start target search there.
 117      */
 118     css::uno::Reference< css::frame::XFrame > m_xBaseFrame;
 119
 120     /** @short  points to the frame, into which the new component was loaded.
 121
 122         @descr  Note: This reference will be empty if loading failed
 123                 or a non visible content was loaded!
 124                 It can be the same frame as m_xBaseFrame it describe, in case
 125                 the target "_self", "" or the search flag "SELF" was used.
 126                 Otherwhise its the new created or recycled frame, which was
 127                 used for loading and contains further the new component.
 128
 129                 Please use method getTarget() or getTargetComponent()
 130                 to return the frame/controller or model to any interested
 131                 user of the results of this load request.
 132      */
 133     css::uno::Reference< css::frame::XFrame > m_xTargetFrame;
 134
 135     /** @short  contains the name of the target, in which the specified resource
 136                 of this instance must be loaded.
 137      */
 138     OUString m_sTarget;
 139
 140     /** @short  if m_sTarget is not a special one, this flags regulate searching
 141                 of a suitable one.
 142      */
 143     sal_Int32 m_nSearchFlags;
 144
 145     /** @short  contains all needed information about the resource,
 146                 which should be loaded.
 147
 148         @descr  Inside this struct e.g. the URL, its type and filter name,
 149                 the stream or a model directly are saved.
 150      */
 151     ::comphelper::MediaDescriptor m_lMediaDescriptor;
 152
 153     /** @short  because the mediadescriptor contains the complete URL ... but
 154                 some functionality need the structured version, we hold it twice :-(.
 155      */
 156     css::util::URL m_aURL;
 157
 158     /** @short  enable/disable special features of a load request. */
 159     EFeature m_eFeature;
 160
 161     /** @short  classify the content, which should be loaded by this instance. */
 162     EContentType m_eContentType;
 163
 164     /** @short  it indicates, that the member m_xTargetFrame was new created for this
 165                 load request and must be closed in case loading (not handling!)
 166                 operation failed. The default value is sal_False!
 167      */
 168     sal_Bool m_bCloseFrameOnError;
 169
 170     /** @short  it indicates, that the old document (which was located inside m_xBaseFrame
 171                 in combination with the m_sTarget value "_self") was suspended.
 172                 Normaly it will be replaced by the new loaded document. But in case
 173                 loading (not handling!) failed, it must be reactivated.
 174                 The default value is sal_False!
 175      */
 176     sal_Bool m_bReactivateControllerOnError;
 177
 178     /** @short  it holds one (!) asynchronous used contenthandler or frameloader
 179                 alive, till the asynchronous operation will be finished.
 180      */
 181     css::uno::Reference< css::uno::XInterface > m_xAsynchronousJob;
 182
 183     /** @short  holds the information about the finished load process.
 184
 185         @descr  The content of m_xTargetFrame cant be used as valid indicator,
 186                 (in case the micht existing old document was reactivated)
 187                 we must hold the result of the load process explicitly.
 188      */
 189     sal_Bool m_bLoaded;
 190
 191     /** @short      holds an XActionLock on the internal used task member.
 192
 193         @seealso    m_xTargetFrame
 194      */
 195     ActionLockGuard m_aTargetLock;
 196
 197     QuietInteraction*   m_pQuietInteraction;
 198
 199 public:
 200
 201     /** @short  initialize a new instance of this load environment.
 202
 203         @param  xSMGR
 204                 reference to an uno service manager, which can be used internaly
 205                 to create on needed services on demand.
 206
 207         @throw  Currently there is no reason to throw such exception!
 208
 209         @throw  A RuntimeException in case any internal process indicates, that
 210                 the whole runtime cant be used any longer.
 211      */
 212     LoadEnv(const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR)
 213         throw(LoadEnvException, css::uno::RuntimeException);
 214
 215     /** @short  deinitialize an instance of this class in the right way.
 216      */
 217     ~LoadEnv();
 218
 219     static css::uno::Reference< css::lang::XComponent > loadComponentFromURL(const css::uno::Reference< css::frame::XComponentLoader >&    xLoader,
 220                                                                              const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR  ,
 221                                                                              const OUString&                                        sURL   ,
 222                                                                              const OUString&                                        sTarget,
 223                                                                                    sal_Int32                                               nFlags ,
 224                                                                              const css::uno::Sequence< css::beans::PropertyValue >&        lArgs  )
 225         throw(css::lang::IllegalArgumentException,
 226               css::io::IOException               ,
 227               css::uno::RuntimeException         );
 228
 229     /** @short  set some changeable parameters for a new load request.
 230
 231         @descr  The parameter for targeting, the content description, and
 232                 some environment specifier (UI, dispatch functionality)
 233                 can be set here ... BEFORE the real load process is started
 234                 by calling startLoading(). Of course a still running load request
 235                 will be detected here and a suitable exception will be thrown.
 236                 Such constellation can be detected outside by using provided
 237                 synchronisation methods or callbacks.
 238
 239         @param  sURL
 240                 points to the resource, which should be loaded.
 241
 242         @param  lMediaDescriptor
 243                 contains additional information for the following load request.
 244
 245         @param  xBaseFrame
 246                 points to the frame which must be used as start point for target search.
 247
 248         @param  sTarget
 249                 regulate searching/creating of frames, which should contain the
 250                 new loaded component afterwards.
 251
 252         @param  nSearchFlags
 253                 regulate searching of targets, if sTarget is not a special one.
 254
 255         @param  eFeature
 256                 flag field, which enable/disable special features of this
 257                 new instance for following load call.
 258
 259         @param  eContentType
 260                 classify the given content.
 261                 This value is set to a default value "UNKNWON_CONTENT", which force
 262                 an internal check, if this content is loadable or not.
 263                 But may this check was already made by the caller of this method and
 264                 passing this information to this LoadEnv instance can supress this
 265                 might expensive check.
 266                 That can be useful in case this information is needed outside too,
 267                 to decide if its neccessary to create some resources for this load
 268                 request ... or to reject the request imidiatly if it seems to be not
 269                 loadable in general.
 270
 271         @throw  A LoadEnvException e.g. if another load operation is till in progress
 272                 or initialization of a new one fail by other reasons.
 273                 The real reason, a suitable message and ID will be given here immidiatly.
 274
 275         @throw  A RuntimeException in case any internal process indicates, that
 276                 the whole runtime cant be used any longer.
 277      */
 278     void initializeLoading(const OUString&                                           sURL            ,
 279                                    const css::uno::Sequence< css::beans::PropertyValue >&           lMediaDescriptor,
 280                                    const css::uno::Reference< css::frame::XFrame >&                 xBaseFrame      ,
 281                                    const OUString&                                           sTarget         ,
 282                                          sal_Int32                                                  nSearchFlags    ,
 283                                          EFeature                                                   eFeature        = E_NO_FEATURE         ,
 284                                          EContentType                                               eContentType    = E_UNSUPPORTED_CONTENT);
 285
 286     /** @short  start loading of the resource represented by this loadenv instance.
 287
 288         @descr  There is no direct return value possible here. Because it depends
 289                 from the usage of this instance! E.g. for loading a "visible component"
 290                 a frame with a controller/model inside can be possible. For loading
 291                 of a "non visible component" only an information about a successfully start
 292                 can be provided.
 293                 Further it cant be guranteed, that the internal process runs synchronous.
 294                 Thats why we preferr using of specialized methods afterwards e.g. to:
 295                     - wait till the internal job will be finished
 296                       and get the results
 297                     - or to let it run without any further control from outside.
 298
 299         @throw  A LoadEnvException if start of the load process failed (because
 300                 another is still in progress!).
 301                 The reason, a suitable message and ID will be given here immidiatly.
 302
 303         @throw  A RuntimeException in case any internal process indicates, that
 304                 the whole runtime cant be used any longer.
 305      */
 306     void startLoading();
 307
 308     //_______________________________________
 309
 310     /** @short  wait for an alreay running load request (started by calling
 311                 startLoading() before).
 312
 313         @descr  The timeout parameter can be used to wait some times only
 314                 or forever. The return value indicates if the load request
 315                 was finished during the specified timeout period.
 316                 But it indicates not, if the load request was successfully or not!
 317
 318         @param  nTimeout
 319                 specify a timeout in [ms].
 320                 A value 0 let it wait forever!
 321
 322         @return sal_True if the started load process could be finished in time;
 323                 sal_False if the specified time was over.
 324
 325         @throw  ... currently not used :-)
 326
 327         @throw  A RuntimeException in case any internal process indicates, that
 328                 the whole runtime cant be used any longer.
 329      */
 330     sal_Bool waitWhileLoading(sal_uInt32 nTimeout = 0);
 331
 332     //_______________________________________
 333     /** TODO document me ... */
 334     css::uno::Reference< css::lang::XComponent > getTargetComponent() const;
 335
 336 public:
 337
 338     /** @short      checks if the specified content can be handled by a
 339                     ContentHandler only and is not related to a target frame,
 340                     or if it can be loaded by a FrameLoader into a target frame
 341                     as "visible" component.
 342
 343         @descr      using:
 344                         switch(classifyContent(...))
 345                         {
 346                             case E_CAN_BE_HANDLED :
 347                                 handleIt(...);
 348                                 break;
 349
 350                             case E_CAN_BE_LOADED :
 351                                 xFrame = locateTargetFrame();
 352                                 loadIt(xFrame);
 353                                 break;
 354
 355                             case E_NOT_A_CONTENT :
 356                             default              : throw ...;
 357                         }
 358
 359         @param      sURL
 360                     describe the content.
 361
 362         @param      lMediaDescriptor
 363                     describe the content more detailed!
 364
 365         @return     A suitable enum value, which classify the specified content.
 366      */
 367     static EContentType classifyContent(const OUString&                                 sURL            ,
 368                                         const css::uno::Sequence< css::beans::PropertyValue >& lMediaDescriptor);
 369
 370     /** TODO document me ... */
 371     static  void initializeUIDefaults(
 372                 const css::uno::Reference< css::uno::XComponentContext >& i_rxContext,
 373                 ::comphelper::MediaDescriptor& io_lMediaDescriptor,
 374                 const bool _bUIMode,
 375                 QuietInteraction** o_ppQuiteInteraction
 376             );
 377
 378     /** TODO document me ... */
 379     void impl_setResult(sal_Bool bResult);
 380
 381     /** TODO document me ... */
 382     css::uno::Reference< css::uno::XInterface > impl_searchLoader();
 383
 384     //_______________________________________
 385
 386     /** @short  it means; show the frame, bring it to front,
 387                 might set the right icon etcpp. in case loading was
 388                 successfully or reactivate a might existing old document or
 389                 close the frame if it was created before in case loading failed.
 390
 391         @throw  A LoadEnvException only in cases, where an internal error indicates,
 392                 that the complete load environment seems to be not useable in general.
 393                 In such cases a RuntimeException would be to hard for the outside code :-)
 394
 395         @throw  A RuntimeException in case any internal process indicates, that
 396                 the whole runtime cant be used any longer.
 397      */
 398     void impl_reactForLoadingState()
 399         throw(LoadEnvException, css::uno::RuntimeException);
 400
 401 private:
 402
 403     /** @short  tries to detect the type and the filter of the specified content.
 404
 405         @descr  This method update the available media descriptor of this instance,
 406                 so it contains the right type, a corresponding filter, may a
 407                 valid frame loader etc. In case detection failed, this descriptor
 408                 is corrected first, before a suitable exception will be thrown.
 409                 (Excepting a RuntimeException occure!)
 410
 411         @attention  Not all types we know, are supported by filters. So it does not
 412                     indicates an error, if no suitable filter(loader etcpp will be found
 413                     for a type. But a type must be detected for the specified content.
 414                     Otherwhise its an error and loading cant be finished successfully.
 415
 416         @throw  A LoadEnvException if detection failed.
 417
 418         @throw  A RuntimeException in case any internal process indicates, that
 419                 the whole runtime cant be used any longer.
 420      */
 421     void impl_detectTypeAndFilter()
 422         throw(LoadEnvException, css::uno::RuntimeException);
 423
 424     /** @short  tries to ask user for it's filter decision in case
 425                 normal detection failed.
 426
 427         @descr  We use a may existing interaction handler to do so.
 428
 429         @return [string]
 430                 the type selected by the user.
 431
 432         @attention  Internaly we update the member m_lMediaDescriptor!
 433      */
 434     OUString impl_askUserForTypeAndFilterIfAllowed()
 435         throw(LoadEnvException, css::uno::RuntimeException);
 436
 437     /** @short  tries to use ContentHandler objects for loading.
 438
 439         @descr  It searches for a suitable content handler object, registered
 440                 for the detected content type (must be done before by calling
 441                 impl_detectTypeAndFilter()). Because such handler does not depend
 442                 from a real target frame, location of such frame will be
 443                 supressed here.
 444                 In case handle failed all new created resources will be
 445                 removed before a suitable exception is thrown.
 446                 (Excepting a RuntimeException occure!)
 447
 448         @return TODO
 449
 450         @throw  A LoadEnvException if handling failed.
 451
 452         @throw  A RuntimeException in case any internal process indicates, that
 453                 the whole runtime cant be used any longer.
 454      */
 455     sal_Bool impl_handleContent()
 456         throw(LoadEnvException, css::uno::RuntimeException);
 457
 458     /** @short  tries to use FrameLoader objects for loading.
 459
 460         @descr  First the target frame will be located. If it could be found
 461                 or new created a filter/frame loader will be instanciated and
 462                 used to load the content into this frame.
 463                 In case loading failed all new created resources will be
 464                 removed before a suitable exception is thrown.
 465                 (Excepting a RuntimeException occure!)
 466
 467         @return TODO
 468
 469         @throw  A LoadEnvException if loading failed.
 470
 471         @throw  A RuntimeException in case any internal process indicates, that
 472                 the whole runtime cant be used any longer.
 473      */
 474     sal_Bool impl_loadContent()
 475         throw(LoadEnvException, css::uno::RuntimeException);
 476
 477     /** @short  checks if the specified content is already loaded.
 478
 479         @descr  It depends from the set target information, if such
 480                 search is allowed or not! So this method checks first,
 481                 if the target is the special one "_default".
 482                 If not it returns with an empty result immidatly!
 483                 In case search is allowed, an existing document with the
 484                 same URL is searched. If it could be found, the corresponding
 485                 view will get the focus and this method return the corresponding frame.
 486                 Optional jumpmarks will be accepted here too. So the
 487                 view of the document will be updated to show the position
 488                 inside the document, which is related to the jumpmark.
 489
 490         @return A valid reference to the target frame, which contains the already loaded content
 491                 and could be activated successfully. An empty reference oterwhise.
 492
 493         @throw  A LoadEnvException only in cases, where an internal error indicates,
 494                 that the complete load environment seems to be not useable in general.
 495                 In such cases a RuntimeException would be to hard for the outside code :-)
 496
 497         @throw  A RuntimeException in case any internal process indicates, that
 498                 the whole runtime cant be used any longer.
 499      */
 500     css::uno::Reference< css::frame::XFrame > impl_searchAlreadyLoaded()
 501         throw(LoadEnvException, css::uno::RuntimeException);
 502
 503     /** @short  search for any target frame, which seems to be useable
 504                 for this load request.
 505
 506         @descr  Because this special feature is bound to the target specifier "_default"
 507                 its checked inside first. If its not set => this method return an empty
 508                 reference. Otherwhise any currently existing frame will be analyzed, if
 509                 it can be used here. The following rules exists:
 510
 511                 <ul>
 512                     <li>The frame must be empty ...</li>
 513                     <li>or contains an empty document of the same application module
 514                         which the new document will have (Note: the filter of the new content
 515                         must be well known here!)</li>
 516                     <li>and(!) this target must not be already used by any other load request.</li>
 517                 </ul>
 518
 519                 If a suitable target is located it will be locked. Thats why the last rule
 520                 exists! If this method returns a valid frame reference, it was locked to be useable
 521                 for this load request only. (Dont forget to reset this state later!)
 522                 Concurrent LoadEnv instances can synchronize her work be using such locks :-) HOPEFULLY
 523
 524         @throw  A LoadEnvException only in cases, where an internal error indicates,
 525                 that the complete load environment seems to be not useable in general.
 526                 In such cases a RuntimeException would be to hard for the outside code :-)
 527
 528         @throw  A RuntimeException in case any internal process indicates, that
 529                 the whole runtime cant be used any longer.
 530      */
 531     css::uno::Reference< css::frame::XFrame > impl_searchRecycleTarget()
 532         throw(LoadEnvException, css::uno::RuntimeException);
 533
 534     /** @short  because showing of a frame is needed more then once ...
 535                 it's implemented as an separate method .-)
 536
 537         @descr  Note: Showing of a frame is bound to a special feature ...
 538                 a) If we recycle any existing frame, we must bring it to front.
 539                    Showing of such frame isnt needed realy .. because we recycle
 540                    visible frames only!
 541                 b) If the document was already shown (e.g. by our progress implementation)
 542                    we do nothing here. The reason  behind: The document was already shown ..
 543                    and it was already make a top window ...
 544                    If the user activated another frame inbetween (because loading needed some time)
 545                    it's not allowed to disturb the user again. Then the frame must resists in the background.
 546                 c) If the frame was not shown before ... but loading of a visible document into this frame
 547                    was finished ... we need both actions: setVisible() and toFront().
 548
 549         @param  xWindow
 550                 points to the container window of a frame.
 551
 552         @param  bForceToFront
 553                 if it's set to sal_False ... showing of the window is done more intelligent.
 554                 setVisible() is called only if the window was not shown before.
 555                 This mode is needed by b) and c)
 556                 If it's set to sal_True ... both actions has to be done: setVisible(), toFront()!
 557                 This mode is needed by a)
 558      */
 559     void impl_makeFrameWindowVisible(const css::uno::Reference< css::awt::XWindow >& xWindow      ,
 560                                            sal_Bool                                  bForceToFront);
 561
 562     /** @short  checks whether a frame is already used for another load request or not.
 563
 564         @descr  Such frames cant be used for our "recycle feature"!
 565
 566         @param  xFrame
 567                 the frame, which should be checked.
 568
 569         @return [sal_Bool]
 570                 sal_True if this frame is already used for loading,
 571                 sal_False otherwise.
 572      */
 573     sal_Bool impl_isFrameAlreadyUsedForLoading(const css::uno::Reference< css::frame::XFrame >& xFrame) const;
 574
 575     /** @short  try to determine the used application module
 576                 of this load request and applay right position and size
 577                 for this document window ... hopefully before we show it .-)
 578      */
 579     void impl_applyPersistentWindowState(const css::uno::Reference< css::awt::XWindow >& xWindow);
 580
 581     /** @short  determine if it's allowed to open new document frames.
 582      */
 583     sal_Bool impl_furtherDocsAllowed();
 584
 585     /** @short  jumps to the requested bookmark inside a given document.
 586      */
 587     void impl_jumpToMark(const css::uno::Reference< css::frame::XFrame >& xFrame,
 588                          const css::util::URL&                            aURL  );
 589 };
 590
 591 } // namespace framework
 592
 593 #endif // __FRAMEWORK_LOADENV_LOADENV_HXX_
 594
 595 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */