/src/libreoffice/framework/inc/jobs/jobdata.hxx

Source
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   Licensed to the Apache Software Foundation (ASF) under one or more
 *   contributor license agreements. See the NOTICE file distributed
 *   with this work for additional information regarding copyright
 *   ownership. The ASF licenses this file to you under the Apache
 *   License, Version 2.0 (the "License"); you may not use this file
 *   except in compliance with the License. You may obtain a copy of
 *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
 */

#pragma once

#include <com/sun/star/uno/XComponentContext.hpp>
#include <com/sun/star/beans/NamedValue.hpp>

#include <rtl/ustring.hxx>

#include <string_view>
#include <utility>
#include <vector>

namespace framework{

/**
    @short  holds all necessary information about a job and
            handle it's configuration (if any exist!)
    @descr  It can be used from different use cases as a container
            (or proxy) for all config data of a registered job.
            But it doesn't implement any execute functionality!
 */
class JobData final
{
    public:

        /** These values can be used to differe between jobs with and jobs without
            a configuration. Of course an "unknown state" should be available too,
            to detect a missing initialization.
         */
        enum EMode
        {
            /// indicates a missing initialization
            E_UNKNOWN_MODE,
            /// indicates a job with configuration (They alias represent the config key name.)
            E_ALIAS,
            /// indicates a job without configuration (The pure UNO implementation is used only.)
            E_SERVICE,
            /// indicates a job with configuration, which was triggered by an event
            E_EVENT
        };

        /** These values represent the environment type, in which a job can run.
            A job must known, from which binding it will be started. Because
            it's initialization data depends from that!
         */
        enum EEnvironment
        {
            /// indicates a missing initialization
            E_UNKNOWN_ENVIRONMENT,
            /// this job is used by the global JobExecutor service
            E_EXECUTION,
            /// this job is used by the global dispatch framework
            E_DISPATCH,
            /// this job is used by the global event broadcaster
            E_DOCUMENTEVENT
        };

        /** Some jobs can be registered to "logical events", which are generated on demand if another document event
            occurs. E.g. "onDocumentOpened" in case "OnNew" or "OnLoad" was notified to the JobExecutor instance.
            And normally the original event is transported as parameter set to the executed job. But then such job
            can't differ between e.g. "OnNew" and "onDocumentOpened".
            That's why we must know, for which type of event the job was really triggered .-)

            The information "sDocEvent" from this struct must be set on the member JobData::m_sEvent from outside
            user of such Jobdata structure.
        */
        struct TJob2DocEventBinding
        {
            OUString m_sJobName;
            OUString m_sDocEvent;

            TJob2DocEventBinding(OUString sJobName ,
                                 OUString sDocEvent)
                : m_sJobName (std::move(sJobName ))
                , m_sDocEvent(std::move(sDocEvent))
            {}
        };

    // member

    private:

        /**
            reference to the uno service manager.
            We need it for creating of own uno services ... e.g. for
            opening the configuration.
         */
        css::uno::Reference< css::uno::XComponentContext > m_xContext;

        /**
            An instance of this class can be used in two different modes:
                - as a configured job
                - as a job without any configuration
            First mode is triggered by an alias, which points to the
            configuration entries. Second mode is specified by a uno service
            or implementation name. Then we do the same things (use the same interfaces)
            but don't handle any configuration data.
            The effect: This mode can be detected by this member.
         */
        EMode m_eMode;

        /**
            Because jobs can be bind to different mechanism inside office, a job
            should know inside which environment it runs. E.g. a job can be executed
            by the global JobExecutor service (triggered by an event) or e.g. as part
            of the global dispatch framework (triggered by an UI control e.g. a menu entry).
         */
        EEnvironment m_eEnvironment;

        /**
            the alias name of this job.
            Is used as entry of configuration set for job registration, to find all
            necessary properties of it...
         */
        OUString m_sAlias;

        /**
            the uno implementation name of this job.
            It's read from the configuration. Don't set it from outside!
         */
        OUString m_sService;

        /**
            the module context list of this job.
            It's read from the configuration. Don't set it from outside!
         */
        OUString m_sContext;

        /**
            a job can be registered for an event.
            It can be an empty value! But it will be set from outside any times.
            Because it's not clear which job this instance should represent if an event
            (instead of an alias) comes in. Because there can be multiple registrations
            for this event. We use this information only, to merge it with the job specific
            arguments. A job can be called so, with a) its own config data and b) some dynamic
            environment data.
         */
        OUString m_sEvent;

        /**
            job specific configuration items... unknown for us!
            It's read from the configuration. Don't set it from outside!
         */
        std::vector< css::beans::NamedValue > m_lArguments;

    // native interface

    public:

                 JobData( css::uno::Reference< css::uno::XComponentContext > xContext );
                 JobData( const JobData&                                                rCopy );
                 ~JobData(                                                                     );

        JobData& operator=( const JobData& rCopy );

        EMode                                        getMode                 () const;
        EEnvironment                                 getEnvironment          () const;
        OUString                              getEnvironmentDescriptor() const;
        const OUString &                              getService              () const;
        const OUString &                              getEvent                () const;
        css::uno::Sequence< css::beans::NamedValue > getConfig               () const;
        const std::vector< css::beans::NamedValue > & getJobConfig            () const;

        bool                                     hasConfig               () const;
        bool                                     hasCorrectContext       ( std::u16string_view rModuleIdent ) const;

        void                                         setEnvironment (       EEnvironment                                  eEnvironment );
        void                                         setAlias       ( const OUString&                              sAlias       );
        void                                         setService     ( const OUString&                              sService     );
        void                                         setEvent       ( const OUString&                              sEvent       ,
                                                                      const OUString&                              sAlias       );
        void                                         setJobConfig   ( std::vector< css::beans::NamedValue >&& lArguments   );
        void                                         disableJob     (                                                                  );

        static std::vector< OUString > getEnabledJobsForEvent( const css::uno::Reference< css::uno::XComponentContext >& rxContext,
                                                                std::u16string_view                                sEvent );

        static void appendEnabledJobsForEvent( const css::uno::Reference< css::uno::XComponentContext >&              rxContext,
                                               const OUString&                                                 sEvent ,
                                                     ::std::vector< JobData::TJob2DocEventBinding >& lJobs  );

    // private helper

    private:

        void impl_reset();
};

} // namespace framework

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */

Coverage Report

Created: 2026-06-30 11:14

Line	Count	Source
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	0	: m_sJobName (std::move(sJobName ))
93	0	, m_sDocEvent(std::move(sDocEvent))
94	0	{}
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		const OUString & getService () const;
178		const OUString & getEvent () const;
179		css::uno::Sequence< css::beans::NamedValue > getConfig () const;
180		const 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: */