framework/inc/jobs/job.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_JOBS_JOB_HXX_
  21 #define __FRAMEWORK_JOBS_JOB_HXX_
  22
  23 #include <jobs/jobresult.hxx>
  24 #include <jobs/jobdata.hxx>
  25 #include <threadhelp/threadhelpbase.hxx>
  26 #include <macros/debug.hxx>
  27 #include <macros/xinterface.hxx>
  28 #include <macros/xtypeprovider.hxx>
  29 #include <stdtypes.h>
  30 #include <general.h>
  31
  32 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
  33 #include <com/sun/star/lang/XTypeProvider.hpp>
  34 #include <com/sun/star/frame/XFrame.hpp>
  35 #include <com/sun/star/frame/XDesktop2.hpp>
  36 #include <com/sun/star/frame/XDispatchResultListener.hpp>
  37 #include <com/sun/star/task/XJobListener.hpp>
  38 #include <com/sun/star/util/XCloseListener.hpp>
  39 #include <com/sun/star/frame/DispatchResultEvent.hpp>
  40
  41 #include <cppuhelper/weak.hxx>
  42 #include <rtl/ustring.hxx>
  43
  44
  45 namespace framework{
  46
  47
  48
  49
  50 /**
  51     @short  it represent a job; execute it and control it's lifetime
  52
  53     @descr  This implemetation can be used to wrapp jobs, execute it
  54             synchronously or asynchronous, control it's lifetime
  55             and differe between jobs with and without configuration.
  56  */
  57 class Job : public  css::lang::XTypeProvider
  58           , public  css::task::XJobListener
  59           , public  css::frame::XTerminateListener
  60           , public  css::util::XCloseListener
  61           , private ThreadHelpBase
  62           , public  ::cppu::OWeakObject
  63 {
  64     //___________________________________
  65     // structs
  66
  67     private:
  68
  69     /** different possible states for the internal wrapped job.
  70         It can be started, stopped by a queryClosing() request or
  71         disposed() by a notifyClosing() request ...
  72      */
  73     enum ERunState
  74     {
  75         E_NEW,
  76         E_RUNNING,
  77         E_STOPPED_OR_FINISHED,
  78         E_DISPOSED
  79     };
  80
  81     //___________________________________
  82     // member
  83
  84     private:
  85
  86         /**
  87             hold all neccessary information about this job.
  88             It can be used for both modes: with and without configuration.
  89          */
  90         JobData m_aJobCfg;
  91
  92         /**
  93             We need it to create own services on demand.
  94          */
  95         css::uno::Reference< css::lang::XMultiServiceFactory > m_xSMGR;
  96
  97         /**
  98             Hold the (may asynchronous) job alive.
  99          */
 100         css::uno::Reference< css::uno::XInterface > m_xJob;
 101
 102         /**
 103             Used to wait for finishing of asynchronous started jobs.
 104          */
 105         ::osl::Condition m_aAsyncWait;
 106
 107         /**
 108             For some special cases we must know the environment, in which
 109             this job runs. Means the frame inside which we may was triggered.
 110             We use it too, to listen for closing events of this resource.
 111
 112             Please note: If m_xFrame is set - m_xModel should be NULL.
 113             Only one environment can be supported realy.
 114          */
 115         css::uno::Reference< css::frame::XFrame > m_xFrame;
 116
 117         /**
 118             For some special cases we must know the environment, in which
 119             this job runs. Means the document inside which we may was triggered.
 120             We use it too, to listen for closing events of this resource.
 121
 122             Please note: If m_xModel is set - m_xFrame should be NULL.
 123             Only one environment can be supported realy.
 124          */
 125         css::uno::Reference< css::frame::XModel > m_xModel;
 126
 127         /**
 128             We are registered at this instance to listen for office shutdown events.
 129             It's neccessary supress it (if possible) or to react in the right way.
 130          */
 131         css::uno::Reference< css::frame::XDesktop2 > m_xDesktop;
 132
 133         /**
 134             A job can return a dispatch result event after finishing its work.
 135             We have to transport it to any outside interested listener then.
 136             (see m_xResultSourceFake for further information too!)
 137          */
 138         css::uno::Reference< css::frame::XDispatchResultListener > m_xResultListener;
 139
 140         /**
 141             We can't set ourself as source of a dispatch result event ... nor our job.
 142             Because the listener (set as m_xResultListener) expect the original instance,
 143             where it was registered. This original instance is the user of this class.
 144             It must be set explicitly and will be used to fake the source of the event!
 145          */
 146         css::uno::Reference< css::uno::XInterface > m_xResultSourceFake;
 147
 148         /**
 149             Holds the state, if we are listen for desktop/frame or model closing events or not.
 150             The used references are not realy enough to detect a valid listener connection.
 151             Thats why we use this additional information here too.
 152          */
 153         sal_Bool m_bListenOnDesktop;
 154         sal_Bool m_bListenOnFrame;
 155         sal_Bool m_bListenOnModel;
 156
 157         /**
 158             In case we got a close request from our desktop/frame/model (on which we listen) ... and
 159             the ownership was delivered there ... we have to close ourself and this object
 160             in case the internal wrapped and running job finish his work.
 161          */
 162         sal_Bool m_bPendingCloseFrame;
 163         sal_Bool m_bPendingCloseModel;
 164
 165         /**
 166             indicates in which state the internal job currently exist.
 167
 168             We can use this information to throw any suitable veto exception
 169             to prevent the environment against dieing or supress superflous dispose()
 170             calls at the job.
 171          */
 172         ERunState m_eRunState;
 173
 174     //___________________________________
 175     // native interface
 176
 177     public:
 178
 179                  Job( const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR  ,
 180                       const css::uno::Reference< css::frame::XFrame >&              xFrame );
 181                  Job( const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR  ,
 182                       const css::uno::Reference< css::frame::XModel >&              xModel );
 183         virtual ~Job(                                                                      );
 184
 185         void     setDispatchResultFake( const css::uno::Reference< css::frame::XDispatchResultListener >& xListener    ,
 186                                         const css::uno::Reference< css::uno::XInterface >&                xSourceFake  );
 187         void     setJobData           ( const JobData&                                                    aData        );
 188         void     execute              ( const css::uno::Sequence< css::beans::NamedValue >&               lDynamicArgs );
 189         void     die                  (                                                                                );
 190
 191     private:
 192
 193         css::uno::Sequence< css::beans::NamedValue > impl_generateJobArgs  ( const css::uno::Sequence< css::beans::NamedValue >& lDynamicArgs );
 194         void                                         impl_reactForJobResult( const css::uno::Any&                                aResult      );
 195         void                                         impl_startListening   (                                                                  );
 196         void                                         impl_stopListening    (                                                                  );
 197
 198     //___________________________________
 199     // uno interface
 200
 201     public:
 202
 203         FWK_DECLARE_XINTERFACE
 204         FWK_DECLARE_XTYPEPROVIDER
 205
 206         // XJobListener
 207         virtual void SAL_CALL jobFinished( const css::uno::Reference< css::task::XAsyncJob >& xJob,
 208                                            const css::uno::Any&                               aResult ) throw(css::uno::RuntimeException);
 209
 210         // XTerminateListener
 211         virtual void SAL_CALL queryTermination ( const css::lang::EventObject& aEvent ) throw(css::frame::TerminationVetoException,
 212                                                                                               css::uno::RuntimeException          );
 213         virtual void SAL_CALL notifyTermination( const css::lang::EventObject& aEvent ) throw(css::uno::RuntimeException          );
 214
 215         // XCloseListener
 216         virtual void SAL_CALL queryClosing ( const css::lang::EventObject& aEvent         ,
 217                                                    sal_Bool                bGetsOwnership ) throw(css::util::CloseVetoException,
 218                                                                                                   css::uno::RuntimeException   );
 219         virtual void SAL_CALL notifyClosing( const css::lang::EventObject& aEvent         ) throw(css::uno::RuntimeException   );
 220
 221         // XEventListener
 222         virtual void SAL_CALL disposing( const css::lang::EventObject& aEvent ) throw(css::uno::RuntimeException);
 223 };
 224
 225 } // namespace framework
 226
 227 #endif // __FRAMEWORK_JOBS_JOB_HXX_
 228
 229 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */