framework/inc/jobs/jobdata.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: jobdata.hxx,v $
  10  * $Revision: 1.7.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_JOBDATA_HXX_
  32 #define __FRAMEWORK_JOBS_JOBDATA_HXX_
  33
  34 //_______________________________________
  35 // my own includes
  36
  37 #include <jobs/configaccess.hxx>
  38 #include <jobs/jobresult.hxx>
  39 #include <threadhelp/threadhelpbase.hxx>
  40 #include <macros/debug.hxx>
  41 #include <stdtypes.h>
  42 #include <general.h>
  43
  44 //_______________________________________
  45 // interface includes
  46 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
  47 #include <com/sun/star/beans/NamedValue.hpp>
  48 #include <com/sun/star/frame/DispatchResultEvent.hpp>
  49
  50 //_______________________________________
  51 // other includes
  52 #include <tools/datetime.hxx>
  53 #include <rtl/ustring.hxx>
  54
  55 //_______________________________________
  56 // namespace
  57
  58 namespace framework{
  59
  60 //_______________________________________
  61 // public const
  62
  63 //_______________________________________
  64 // definitions
  65
  66 /**
  67     @short  holds all neccessary informations about a job and
  68             handle it's configuration (if any exist!)
  69     @descr  It can be used rom different use cases as a container
  70             (or proxy) for all config data of a registered job.
  71             But it doesn't implement any execute functionality!
  72  */
  73 class JobData : private ThreadHelpBase
  74 {
  75     //___________________________________
  76     // const
  77
  78     public:
  79
  80         /// specifies the root package and key to find registered jobs
  81         static const sal_Char* JOBCFG_ROOT;
  82         /// define the cfg key "Arguments" of a job relativ to JOBCFG_ROOT/<job alias>
  83         static const sal_Char* JOBCFG_PROP_ARGUMENTS;
  84         /// define the cfg key "Service" of a job relativ to JOBCFG_ROOT/<job alias>
  85         static const sal_Char* JOBCFG_PROP_SERVICE;
  86
  87         /// specifies the root package and key to find event registrations
  88         static const sal_Char* EVENTCFG_ROOT;
  89         /// define the cfg key "JobList" of an event relativ to EVENTCFG_ROOT/<event>
  90         static const sal_Char* EVENTCFG_PATH_JOBLIST;
  91         /// define the cfg key "AdminTime" of a job registration relativ to EVENTCFG_ROOT/<event>/EVENTCFG_PROP_JOBLIST/<job alias>
  92         static const sal_Char* EVENTCFG_PROP_ADMINTIME;
  93         /// define the cfg key "UserTime" of a job registration relativ to EVENTCFG_ROOT/<event>/EVENTCFG_PROP_JOBLIST/<job alias>
  94         static const sal_Char* EVENTCFG_PROP_USERTIME;
  95
  96         /// mark the starting point of static job data inside argument list of job execution
  97         static const sal_Char* PROPSET_CONFIG;
  98         /// mark the starting point of job specific data inside argument list of job execution
  99         static const sal_Char* PROPSET_OWNCONFIG;
 100         /// mark the starting point of environment data inside argument list of job execution
 101         static const sal_Char* PROPSET_ENVIRONMENT;
 102         /// mark the starting point of any other dynamic generated data inside argument list of job execution (e.g. from a dispatch() request)
 103         static const sal_Char* PROPSET_DYNAMICDATA;
 104
 105         static const sal_Char* PROP_ALIAS;
 106         static const sal_Char* PROP_EVENTNAME;
 107         static const sal_Char* PROP_ENVTYPE;
 108         static const sal_Char* PROP_FRAME;
 109         static const sal_Char* PROP_MODEL;
 110         static const sal_Char* PROP_SERVICE;
 111
 112     //___________________________________
 113     // structs
 114
 115     public:
 116
 117         /** These values can be used to differe between jobs with and jobs without
 118             a configuration. Of course an "unknown state" should be available too,
 119             to detect a missing initialization.
 120          */
 121         enum EMode
 122         {
 123             /// indicates a missing initialization
 124             E_UNKNOWN_MODE,
 125             /// indicates a job with configuration (They alias represent the config key name.)
 126             E_ALIAS,
 127             /// indicates a job without configuration (The pure UNO implementation is used only.)
 128             E_SERVICE,
 129             /// indicates a job with configuration, which was triggered by an event
 130             E_EVENT
 131         };
 132
 133         /** These values represent the environment type, in which a job can run.
 134             A job must known, from which binding it will be started. Because
 135             it's initialization data depends from that!
 136          */
 137         enum EEnvironment
 138         {
 139             /// indicates a missing initialization
 140             E_UNKNOWN_ENVIRONMENT,
 141             /// this job is used by the global JobExecutor service
 142             E_EXECUTION,
 143             /// this job is used by the global dispatch framework
 144             E_DISPATCH,
 145             /// this job is used by the global event broadcaster
 146             E_DOCUMENTEVENT
 147         };
 148
 149         /** Some jobs can be registered to "logical events", which are generated on demand if another document event
 150             occures. E.g. "onDocumentOpened" in case "OnNew" or "OnLoad" was notified to the JobExecutor instance.
 151             And normaly the original event is transported as parameter set to the executed job. But then such job
 152             cant differ between e.g. "OnNew" and "onDocumentOpened".
 153             That's why we must know, for which type of event the job was realy triggered .-)
 154
 155             The information "sDocEvent" from this struct must be set on the member JobData::m_sEvent from outside
 156             user of such Jobdata structure.
 157         */
 158         struct TJob2DocEventBinding
 159         {
 160             ::rtl::OUString m_sJobName;
 161             ::rtl::OUString m_sDocEvent;
 162
 163             TJob2DocEventBinding(const ::rtl::OUString& sJobName ,
 164                                  const ::rtl::OUString& sDocEvent)
 165                 : m_sJobName (sJobName )
 166                 , m_sDocEvent(sDocEvent)
 167             {}
 168         };
 169
 170     //___________________________________
 171     // member
 172
 173     private:
 174
 175         /**
 176             reference to the uno service manager.
 177             We need it for creating of own uno services ... e.g. for
 178             opening the configuration.
 179          */
 180         css::uno::Reference< css::lang::XMultiServiceFactory > m_xSMGR;
 181
 182         /**
 183             An instance of this class can be used in two different modes:
 184                 - as a configured job
 185                 - as a job without any configuration
 186             First mode is triggered by an alias, which points to the
 187             configuration entries. Second mode is specified by an uno service
 188             or implementation name. Then we does the same things (use the same interfaces)
 189             but don't handle any configuration data.
 190             The effect: This mode can be detected by this member.
 191          */
 192         EMode m_eMode;
 193
 194         /**
 195             Because jobs can be bind to different mechanism inside office, a job
 196             should know inside which environment it runs. E.g. a job can be executed
 197             by the global JobExecutor service (triggered by an event) or e.g. as part
 198             of the global dispatch framework (triggered by an UI control e.g. a menu entry).
 199          */
 200         EEnvironment m_eEnvironment;
 201
 202         /**
 203             the alias name of this job.
 204             Is used as entry of configuration set for job registration, to find all
 205             neccessary properties of it..
 206          */
 207         ::rtl::OUString m_sAlias;
 208
 209         /**
 210             the uno implementation name of this job.
 211             It's readed from the configuration. Don't set it from outside!
 212          */
 213         ::rtl::OUString m_sService;
 214
 215         /**
 216             a job can be registered for an event.
 217             It can be an empty value! But it will be set from outside any times.
 218             Because it's not clear which job this instance should represent if an event
 219             (instaed of an alias) comes in. Because there can be multiple registrations
 220             for this event. We use this information only, to merge it with the job specific
 221             arguments. A job can be called so, with a) it's onw config data and b) some dynamic
 222             environment data.
 223          */
 224         ::rtl::OUString m_sEvent;
 225
 226         /**
 227             job specific configuration items ... unknown for us!
 228             It's readed from the configuration. Don't set it from outside!
 229          */
 230         css::uno::Sequence< css::beans::NamedValue > m_lArguments;
 231
 232         /**
 233             after a job was sucessfully executed (by any outside code using our
 234             informations) it can return a result. This member make it part of this
 235             container too. So it can be used for further things.
 236             We use it also to actualize our internal state and the configuration
 237             of the job. But note: only the last result will be saved here!
 238          */
 239         JobResult m_aLastExecutionResult;
 240
 241     //___________________________________
 242     // native interface
 243
 244     public:
 245
 246                  JobData( const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR );
 247                  JobData( const JobData&                                                rCopy );
 248         virtual ~JobData(                                                                     );
 249
 250         void operator=( const JobData& rCopy );
 251
 252         EMode                                        getMode                 () const;
 253         EEnvironment                                 getEnvironment          () const;
 254         ::rtl::OUString                              getEnvironmentDescriptor() const;
 255         ::rtl::OUString                              getService              () const;
 256         ::rtl::OUString                              getEvent                () const;
 257         css::uno::Sequence< css::beans::NamedValue > getConfig               () const;
 258         css::uno::Sequence< css::beans::NamedValue > getJobConfig            () const;
 259
 260         sal_Bool                                     hasConfig               () const;
 261
 262         void                                         setEnvironment (       EEnvironment                                  eEnvironment );
 263         void                                         setAlias       ( const ::rtl::OUString&                              sAlias       );
 264         void                                         setService     ( const ::rtl::OUString&                              sService     );
 265         void                                         setEvent       ( const ::rtl::OUString&                              sEvent       ,
 266                                                                       const ::rtl::OUString&                              sAlias       );
 267         void                                         setJobConfig   ( const css::uno::Sequence< css::beans::NamedValue >& lArguments   );
 268         void                                         setResult      ( const JobResult&                                    aResult      );
 269         void                                         disableJob     (                                                                  );
 270
 271         static css::uno::Sequence< ::rtl::OUString > getEnabledJobsForEvent( const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR  ,
 272                                                                              const ::rtl::OUString&                                        sEvent );
 273
 274         static void appendEnabledJobsForEvent( const css::uno::Reference< css::lang::XMultiServiceFactory >&          xSMGR  ,
 275                                                const ::rtl::OUString&                                                 sEvent ,
 276                                                      ::comphelper::SequenceAsVector< JobData::TJob2DocEventBinding >& lJobs  );
 277
 278     //___________________________________
 279     // private helper
 280
 281     private:
 282
 283         void impl_reset();
 284 };
 285
 286 } // namespace framework
 287
 288 #endif // __FRAMEWORK_JOBS_JOBDATA_HXX_