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