framework/inc/jobs/job.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: job.hxx,v $
  10  * $Revision: 1.6.82.1 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef __FRAMEWORK_JOBS_JOB_HXX_
  32 #define __FRAMEWORK_JOBS_JOB_HXX_
  33
  34 //_______________________________________
  35 // my own includes
  36
  37 #include <jobs/jobresult.hxx>
  38 #include <jobs/jobdata.hxx>
  39 #include <threadhelp/threadhelpbase.hxx>
  40 #include <macros/debug.hxx>
  41 #include <macros/xinterface.hxx>
  42 #include <macros/xtypeprovider.hxx>
  43 #include <stdtypes.h>
  44 #include <general.h>
  45
  46 //_______________________________________
  47 // interface includes
  48 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
  49 #include <com/sun/star/lang/XTypeProvider.hpp>
  50 #include <com/sun/star/frame/XFrame.hpp>
  51 #include <com/sun/star/frame/XDesktop.hpp>
  52 #include <com/sun/star/frame/XDispatchResultListener.hpp>
  53 #include <com/sun/star/task/XJobListener.hpp>
  54 #include <com/sun/star/util/XCloseListener.hpp>
  55 #include <com/sun/star/frame/DispatchResultEvent.hpp>
  56
  57 //_______________________________________
  58 // other includes
  59 #include <cppuhelper/weak.hxx>
  60 #include <rtl/ustring.hxx>
  61
  62 //_______________________________________
  63 // namespace
  64
  65 namespace framework{
  66
  67 //_______________________________________
  68 // public const
  69
  70 //_______________________________________
  71 // definitions
  72
  73 /**
  74     @short  it represent a job; execute it and control it's lifetime
  75
  76     @descr  This implemetation can be used to wrapp jobs, execute it
  77             synchronously or asynchronous, control it's lifetime
  78             and differe between jobs with and without configuration.
  79  */
  80 class Job : public  css::lang::XTypeProvider
  81           , public  css::task::XJobListener
  82           , public  css::frame::XTerminateListener
  83           , public  css::util::XCloseListener
  84           , private ThreadHelpBase
  85           , public  ::cppu::OWeakObject
  86 {
  87     //___________________________________
  88     // structs
  89
  90     private:
  91
  92     /** different possible states for the internal wrapped job.
  93         It can be started, stopped by a queryClosing() request or
  94         disposed() by a notifyClosing() request ...
  95      */
  96     enum ERunState
  97     {
  98         E_NEW,
  99         E_RUNNING,
 100         E_STOPPED_OR_FINISHED,
 101         E_DISPOSED
 102     };
 103
 104     //___________________________________
 105     // member
 106
 107     private:
 108
 109         /**
 110             hold all neccessary informations about this job.
 111             It can be used for both modes: with and without configuration.
 112          */
 113         JobData m_aJobCfg;
 114
 115         /**
 116             We need it to create own services on demand.
 117          */
 118         css::uno::Reference< css::lang::XMultiServiceFactory > m_xSMGR;
 119
 120         /**
 121             Hold the (may asynchronous) job alive.
 122          */
 123         css::uno::Reference< css::uno::XInterface > m_xJob;
 124
 125         /**
 126             Used to wait for finishing of asynchronous started jobs.
 127          */
 128         ::osl::Condition m_aAsyncWait;
 129
 130         /**
 131             For some special cases we must know the environment, in which
 132             this job runs. Means the frame inside which we may was triggered.
 133             We use it too, to listen for closing events of this ressource.
 134
 135             Please note: If m_xFrame is set - m_xModel should be NULL.
 136             Only one environment can be supported realy.
 137          */
 138         css::uno::Reference< css::frame::XFrame > m_xFrame;
 139
 140         /**
 141             For some special cases we must know the environment, in which
 142             this job runs. Means the document inside which we may was triggered.
 143             We use it too, to listen for closing events of this ressource.
 144
 145             Please note: If m_xModel is set - m_xFrame should be NULL.
 146             Only one environment can be supported realy.
 147          */
 148         css::uno::Reference< css::frame::XModel > m_xModel;
 149
 150         /**
 151             We are registered at this instance to listen for office shutdown events.
 152             It's neccessary supress it (if possible) or to react in the right way.
 153          */
 154         css::uno::Reference< css::frame::XDesktop > m_xDesktop;
 155
 156         /**
 157             A job can return a dispatch result event after finishing its work.
 158             We have to transport it to any outside interested listener then.
 159             (see m_xResultSourceFake for further informations too!)
 160          */
 161         css::uno::Reference< css::frame::XDispatchResultListener > m_xResultListener;
 162
 163         /**
 164             We can't set ourself as source of a dispatch result event ... nor our job.
 165             Because the listener (set as m_xResultListener) expect the original instance,
 166             where it was registered. This original instance is the user of this class.
 167             It must be set explicitly and will be used to fake the source of the event!
 168          */
 169         css::uno::Reference< css::uno::XInterface > m_xResultSourceFake;
 170
 171         /**
 172             Holds the state, if we are listen for desktop/frame or model closing events or not.
 173             The used references are not realy enough to detect a valid listener connection.
 174             Thats why we use this additional information here too.
 175          */
 176         sal_Bool m_bListenOnDesktop;
 177         sal_Bool m_bListenOnFrame;
 178         sal_Bool m_bListenOnModel;
 179
 180         /**
 181             In case we got a close request from our desktop/frame/model (on which we listen) ... and
 182             the ownership was delivered there ... we have to close ourself and this object
 183             in case the internal wrapped and running job finish his work.
 184          */
 185         sal_Bool m_bPendingCloseFrame;
 186         sal_Bool m_bPendingCloseModel;
 187
 188         /**
 189             indicates in which state the internal job currently exist.
 190
 191             We can use this information to throw any suitable veto exception
 192             to prevent the environment against dieing or supress superflous dispose()
 193             calls at the job.
 194          */
 195         ERunState m_eRunState;
 196
 197     //___________________________________
 198     // native interface
 199
 200     public:
 201
 202                  Job( const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR  ,
 203                       const css::uno::Reference< css::frame::XFrame >&              xFrame );
 204                  Job( const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR  ,
 205                       const css::uno::Reference< css::frame::XModel >&              xModel );
 206         virtual ~Job(                                                                      );
 207
 208         void     setDispatchResultFake( const css::uno::Reference< css::frame::XDispatchResultListener >& xListener    ,
 209                                         const css::uno::Reference< css::uno::XInterface >&                xSourceFake  );
 210         void     setJobData           ( const JobData&                                                    aData        );
 211         void     execute              ( const css::uno::Sequence< css::beans::NamedValue >&               lDynamicArgs );
 212         void     die                  (                                                                                );
 213
 214     private:
 215
 216         css::uno::Sequence< css::beans::NamedValue > impl_generateJobArgs  ( const css::uno::Sequence< css::beans::NamedValue >& lDynamicArgs );
 217         void                                         impl_reactForJobResult( const css::uno::Any&                                aResult      );
 218         void                                         impl_startListening   (                                                                  );
 219         void                                         impl_stopListening    (                                                                  );
 220
 221     //___________________________________
 222     // uno interface
 223
 224     public:
 225
 226         FWK_DECLARE_XINTERFACE
 227         FWK_DECLARE_XTYPEPROVIDER
 228
 229         // XJobListener
 230         virtual void SAL_CALL jobFinished( const css::uno::Reference< css::task::XAsyncJob >& xJob,
 231                                            const css::uno::Any&                               aResult ) throw(css::uno::RuntimeException);
 232
 233         // XTerminateListener
 234         virtual void SAL_CALL queryTermination ( const css::lang::EventObject& aEvent ) throw(css::frame::TerminationVetoException,
 235                                                                                               css::uno::RuntimeException          );
 236         virtual void SAL_CALL notifyTermination( const css::lang::EventObject& aEvent ) throw(css::uno::RuntimeException          );
 237
 238         // XCloseListener
 239         virtual void SAL_CALL queryClosing ( const css::lang::EventObject& aEvent         ,
 240                                                    sal_Bool                bGetsOwnership ) throw(css::util::CloseVetoException,
 241                                                                                                   css::uno::RuntimeException   );
 242         virtual void SAL_CALL notifyClosing( const css::lang::EventObject& aEvent         ) throw(css::uno::RuntimeException   );
 243
 244         // XEventListener
 245         virtual void SAL_CALL disposing( const css::lang::EventObject& aEvent ) throw(css::uno::RuntimeException);
 246 };
 247
 248 } // namespace framework
 249
 250 #endif // __FRAMEWORK_JOBS_JOB_HXX_