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