framework/inc/jobs/jobdata.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_JOBDATA_HXX
  21 #define INCLUDED_FRAMEWORK_INC_JOBS_JOBDATA_HXX
  22
  23 #include <jobs/configaccess.hxx>
  24 #include <jobs/jobresult.hxx>
  25 #include <stdtypes.h>
  26 #include <general.h>
  27
  28 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
  29 #include <com/sun/star/uno/XComponentContext.hpp>
  30 #include <com/sun/star/beans/NamedValue.hpp>
  31 #include <com/sun/star/frame/DispatchResultEvent.hpp>
  32
  33 #include <rtl/ustring.hxx>
  34
  35 namespace framework{
  36
  37 /**
  38     @short  holds all necessary information about a job and
  39             handle it's configuration (if any exist!)
  40     @descr  It can be used rom different use cases as a container
  41             (or proxy) for all config data of a registered job.
  42             But it doesn't implement any execute functionality!
  43  */
  44 class JobData
  45 {
  46     public:
  47
  48         /** These values can be used to differe between jobs with and jobs without
  49             a configuration. Of course an "unknown state" should be available too,
  50             to detect a missing initialization.
  51          */
  52         enum EMode
  53         {
  54             /// indicates a missing initialization
  55             E_UNKNOWN_MODE,
  56             /// indicates a job with configuration (They alias represent the config key name.)
  57             E_ALIAS,
  58             /// indicates a job without configuration (The pure UNO implementation is used only.)
  59             E_SERVICE,
  60             /// indicates a job with configuration, which was triggered by an event
  61             E_EVENT
  62         };
  63
  64         /** These values represent the environment type, in which a job can run.
  65             A job must known, from which binding it will be started. Because
  66             it's initialization data depends from that!
  67          */
  68         enum EEnvironment
  69         {
  70             /// indicates a missing initialization
  71             E_UNKNOWN_ENVIRONMENT,
  72             /// this job is used by the global JobExecutor service
  73             E_EXECUTION,
  74             /// this job is used by the global dispatch framework
  75             E_DISPATCH,
  76             /// this job is used by the global event broadcaster
  77             E_DOCUMENTEVENT
  78         };
  79
  80         /** Some jobs can be registered to "logical events", which are generated on demand if another document event
  81             occurs. E.g. "onDocumentOpened" in case "OnNew" or "OnLoad" was notified to the JobExecutor instance.
  82             And normally the original event is transported as parameter set to the executed job. But then such job
  83             can't differ between e.g. "OnNew" and "onDocumentOpened".
  84             That's why we must know, for which type of event the job was really triggered .-)
  85
  86             The information "sDocEvent" from this struct must be set on the member JobData::m_sEvent from outside
  87             user of such Jobdata structure.
  88         */
  89         struct TJob2DocEventBinding
  90         {
  91             OUString m_sJobName;
  92             OUString m_sDocEvent;
  93
  94             TJob2DocEventBinding(const OUString& sJobName ,
  95                                  const OUString& sDocEvent)
  96                 : m_sJobName (sJobName )
  97                 , m_sDocEvent(sDocEvent)
  98             {}
  99         };
 100
 101     // member
 102
 103     private:
 104
 105         /**
 106             reference to the uno service manager.
 107             We need it for creating of own uno services ... e.g. for
 108             opening the configuration.
 109          */
 110         css::uno::Reference< css::uno::XComponentContext > m_xContext;
 111
 112         /**
 113             An instance of this class can be used in two different modes:
 114                 - as a configured job
 115                 - as a job without any configuration
 116             First mode is triggered by an alias, which points to the
 117             configuration entries. Second mode is specified by an uno service
 118             or implementation name. Then we do the same things (use the same interfaces)
 119             but don't handle any configuration data.
 120             The effect: This mode can be detected by this member.
 121          */
 122         EMode m_eMode;
 123
 124         /**
 125             Because jobs can be bind to different mechanism inside office, a job
 126             should know inside which environment it runs. E.g. a job can be executed
 127             by the global JobExecutor service (triggered by an event) or e.g. as part
 128             of the global dispatch framework (triggered by an UI control e.g. a menu entry).
 129          */
 130         EEnvironment m_eEnvironment;
 131
 132         /**
 133             the alias name of this job.
 134             Is used as entry of configuration set for job registration, to find all
 135             necessary properties of it..
 136          */
 137         OUString m_sAlias;
 138
 139         /**
 140             the uno implementation name of this job.
 141             It's readed from the configuration. Don't set it from outside!
 142          */
 143         OUString m_sService;
 144
 145         /**
 146             the module context list of this job.
 147             It's readed from the configuration. Don't set it from outside!
 148          */
 149         OUString m_sContext;
 150
 151         /**
 152             a job can be registered for an event.
 153             It can be an empty value! But it will be set from outside any times.
 154             Because it's not clear which job this instance should represent if an event
 155             (instaed of an alias) comes in. Because there can be multiple registrations
 156             for this event. We use this information only, to merge it with the job specific
 157             arguments. A job can be called so, with a) it's onw config data and b) some dynamic
 158             environment data.
 159          */
 160         OUString m_sEvent;
 161
 162         /**
 163             job specific configuration items ... unknown for us!
 164             It's readed from the configuration. Don't set it from outside!
 165          */
 166         css::uno::Sequence< css::beans::NamedValue > m_lArguments;
 167
 168         /**
 169             after a job was successfully executed (by any outside code using our
 170             information) it can return a result. This member make it part of this
 171             container too. So it can be used for further things.
 172             We use it also to update our internal state and the configuration
 173             of the job. But note: only the last result will be saved here!
 174          */
 175         JobResult m_aLastExecutionResult;
 176
 177     // native interface
 178
 179     public:
 180
 181                  JobData( const css::uno::Reference< css::uno::XComponentContext >& rxContext );
 182                  JobData( const JobData&                                                rCopy );
 183         virtual ~JobData(                                                                     );
 184
 185         void operator=( const JobData& rCopy );
 186
 187         EMode                                        getMode                 () const;
 188         EEnvironment                                 getEnvironment          () const;
 189         OUString                              getEnvironmentDescriptor() const;
 190         OUString                              getService              () const;
 191         OUString                              getEvent                () const;
 192         css::uno::Sequence< css::beans::NamedValue > getConfig               () const;
 193         css::uno::Sequence< css::beans::NamedValue > getJobConfig            () const;
 194
 195         bool                                     hasConfig               () const;
 196         bool                                     hasCorrectContext       ( const OUString& rModuleIdent ) const;
 197
 198         void                                         setEnvironment (       EEnvironment                                  eEnvironment );
 199         void                                         setAlias       ( const OUString&                              sAlias       );
 200         void                                         setService     ( const OUString&                              sService     );
 201         void                                         setEvent       ( const OUString&                              sEvent       ,
 202                                                                       const OUString&                              sAlias       );
 203         void                                         setJobConfig   ( const css::uno::Sequence< css::beans::NamedValue >& lArguments   );
 204         void                                         setResult      ( const JobResult&                                    aResult      );
 205         void                                         disableJob     (                                                                  );
 206
 207         static css::uno::Sequence< OUString > getEnabledJobsForEvent( const css::uno::Reference< css::uno::XComponentContext >& rxContext,
 208                                                                              const OUString&                                    sEvent );
 209
 210         static void appendEnabledJobsForEvent( const css::uno::Reference< css::uno::XComponentContext >&              rxContext,
 211                                                const OUString&                                                 sEvent ,
 212                                                      ::std::vector< JobData::TJob2DocEventBinding >& lJobs  );
 213
 214     // private helper
 215
 216     private:
 217
 218         void impl_reset();
 219 };
 220
 221 } // namespace framework
 222
 223 #endif // INCLUDED_FRAMEWORK_INC_JOBS_JOBDATA_HXX
 224
 225 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */