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