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