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