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_SERVICES_DETECTORFACTORY_HXX_
25 #define __FRAMEWORK_SERVICES_DETECTORFACTORY_HXX_
26 
27 //_______________________________________________
28 // includes of own project
29 
30 #include <classes/filtercache.hxx>
31 #include <threadhelp/threadhelpbase.hxx>
32 #include <macros/xinterface.hxx>
33 #include <macros/xtypeprovider.hxx>
34 #include <macros/xserviceinfo.hxx>
35 #include <macros/generic.hxx>
36 #include <macros/debug.hxx>
37 #include <general.h>
38 
39 //_______________________________________________
40 // includes of interfaces
41 #include <com/sun/star/beans/PropertyValue.hpp>
42 #include <com/sun/star/lang/XInitialization.hpp>
43 #include <com/sun/star/lang/WrappedTargetException.hpp>
44 #include <com/sun/star/lang/IllegalArgumentException.hpp>
45 #include <com/sun/star/container/ElementExistException.hpp>
46 #include <com/sun/star/container/NoSuchElementException.hpp>
47 #include <com/sun/star/container/XNameContainer.hpp>
48 #include <com/sun/star/container/NoSuchElementException.hpp>
49 #include <com/sun/star/io/XInputStream.hpp>
50 #include <com/sun/star/util/XFlushable.hpp>
51 
52 //_______________________________________________
53 // includes of other projects
54 #include <cppuhelper/interfacecontainer.hxx>
55 #include <cppuhelper/weak.hxx>
56 
57 //_______________________________________________
58 // namespace
59 
60 namespace framework{
61 
62 //_______________________________________________
63 // exported const
64 
65 //_______________________________________________
66 // exported definitions
67 
68 /// @HTML
69 /** @short      factory to create detect service objects and initialize it in the right way.
70 
71     @descr      This class can be used to create new detect services for specified contents.
72                 It uses cached values of the configuration to lay down, which detector match
73                 a given name. Further this class provides full access to the configuration data
74                 of such detect services and following implementations will support some special
75                 query modes.
76 
77     @author     as96863
78 
79     @docdate    07.03.2003 by as96863
80 
81     @todo       <ul>
82                     <li>implementation of query mode</li>
83                     <li>simple restore mechanism of last consistent cache state,
84                         if flush failed</li>
85                 </ul>
86  */
87 /// @NOHTML
88 
89 class DetectorFactory : // interfaces
90 						public	css::lang::XTypeProvider			,
91 						public	css::lang::XServiceInfo				,
92 						public	css::lang::XMultiServiceFactory		,
93 						public	css::container::XNameContainer		,		// => XNameReplace => XNameAccess => XElementAccess
94 						public	css::util::XFlushable				,
95 						// base classes
96 						// Order is necessary for right initialization of it!
97                         private ThreadHelpBase                      ,
98 						public	::cppu::OWeakObject
99 {
100     //-------------------------------------------
101     // member
102 
103     private:
104 
105         /** reference to the global uno service manager.
106             It will be used to create own needed services on demand. */
107         css::uno::Reference< css::lang::XMultiServiceFactory > m_xSMGR;
108 
109         /** singleton, which contains all needed configuration data and provides
110             read/write access on it. */
111         FilterCache m_aCache;
112 
113         /** contains all registered listener. */
114         ::cppu::OMultiTypeInterfaceContainerHelper m_aListenerContainer;
115 
116     //-------------------------------------------
117     // interface
118 
119 	public:
120 
121         //---------------------------------------
122         // XInterface, XTypeProvider, XServiceInfo
123 
124         DECLARE_XINTERFACE
125         DECLARE_XTYPEPROVIDER
126         DECLARE_XSERVICEINFO
127 
128         #ifdef ENABLE_AUTODOC_FIX
129         ;
130         #endif
131 
132         //---------------------------------------
133 
134         /** @short  initialize new instance of this class.
135 
136             @param  xSMGR
137                     reference to the global uno service manager, which created this new factory instance.
138                     It must be used during runtime to create own needed services.
139          */
140 
141         DetectorFactory( const css::uno::Reference< css::lang::XMultiServiceFactory >& xSMGR );
142 
143         //---------------------------------------
144 
145         /** @short  release internal structures.
146          */
147 
148         virtual ~DetectorFactory();
149 
150         //---------------------------------------
151         // XMultiServiceFactory
152 
153         /** @short  create a new detect service and initialize it with it's own configuration data.
154 
155             @param  sName
156                     means the uno implementation name of a detect service.
157 
158             @exception  com::sun::star::uno::Exception
159                         if the requested service could not be created or initialized.
160          */
161 
162         virtual css::uno::Reference< css::uno::XInterface > SAL_CALL createInstance( const ::rtl::OUString& sName )
163             throw(css::uno::Exception       ,
164                   css::uno::RuntimeException);
165 
166         //---------------------------------------
167         // XMultiServiceFactory
168 
169         /** @short  does the same as createInstance() method, but initialize created detect service with some
170                     additional data.
171 
172             @param  sName
173                     means the uno implementation name of a detect service.
174 
175             @param  lArguments
176                     the optional arguments, which are passed to the created detect service against
177                     it's own configuration data.
178 
179             @exception  com::sun::star::uno::Exception
180                         if the requested service could not be created or initialized.
181          */
182 
183         virtual css::uno::Reference< css::uno::XInterface > SAL_CALL createInstanceWithArguments( const ::rtl::OUString&                     sName      ,
184                                                                                                   const css::uno::Sequence< css::uno::Any >& lArguments )
185             throw(css::uno::Exception       ,
186                   css::uno::RuntimeException);
187 
188         //---------------------------------------
189         // XMultiServiceFactory
190 
191         /** @short  return list of all well know detect services, which can be created by this factory.
192 
193             @attention  Because this service implements read/write access to the configuration too,
194                         this list is dynamic. Means: in multithreaded environments some items of this
195                         return list could be invalid next time!
196 
197             @return A list of all registered detect services.
198          */
199 
200         virtual css::uno::Sequence< ::rtl::OUString > SAL_CALL getAvailableServiceNames()
201             throw(css::uno::RuntimeException);
202 
203         //---------------------------------------
204         // XNameContainer
205 
206         /** @short  add new detect service entry to this container.
207 
208             @descr  This will change all internal structures only!
209                     Updating of the configuration layer and notify of all registered
210                     listener will be done inside API call XFlushable::flush() on this
211                     container.
212 
213             @param  sName
214                     means the uno implementation name of this new detect service entry.
215 
216             @param  aPropertySet [sequence< com::sun::star::beans::PropertyValue >!]
217                     describe this new entry. For a list of all supported properties
218                     have a look on method >>getByName()<<.
219                     Note: Missing values will be created with defaults!
220 
221             @exception  com::sun::star::lang::IllegalArgumentException
222                         if one of the incoming parameters seems to be invalid.
223                         That doesn't include the check, if this item already exist!
224 
225             @exception  com::sun::star::container::ElementExistException
226                         if this item already exist inside this container.
227 
228             @exception  com::sun::star::lang::WrappedTargetException
229                         f creation of the internal structures failed.
230          */
231 
232         virtual void SAL_CALL insertByName( const ::rtl::OUString& sName        ,
233                                             const css::uno::Any&   aPropertySet )
234             throw(css::lang::IllegalArgumentException  ,
235                   css::container::ElementExistException,
236                   css::lang::WrappedTargetException    ,
237                   css::uno::RuntimeException           );
238 
239         //---------------------------------------
240         // XNameContainer
241 
242         /** @short  remove a detect service entry from this container.
243 
244             @descr  This will change all internal structures only!
245                     Updating of the configuration layer and notify of all registered
246                     listener will be done inside API call XFlushable::flush() on this
247                     container.
248 
249             @param  sName
250                     means the uno implementation name of a detect service entry.
251 
252             @exception  com::sun::star::container::NoSuchElementException
253                         if the requested item does not exist inside this container.
254 
255             @exception  com::sun::star::lang::WrappedTargetException
256                         if creation of the internal structures failed.
257          */
258 
259         virtual void SAL_CALL removeByName( const ::rtl::OUString& sName )
260             throw(css::container::NoSuchElementException,
261                   css::lang::WrappedTargetException     ,
262                   css::uno::RuntimeException            );
263 
264         //---------------------------------------
265         // XNameReplace
266 
267         /** @short  change a detect service entry inside this container.
268 
269             @descr  This will change all internal structures only!
270                     Updating of the configuration layer and notify of all registered
271                     listener will be done inside API call XFlushable::flush() on this
272                     container.
273 
274             @param  sName
275                     means the uno implementation name of a detect service entry.
276 
277             @param  aPropertySet [sequence< com::sun::star::beans::PropertyValue >!]
278                     describe the changes on this entry. For a list of all supported properties
279                     have a look on method getByName().
280                     Note: Missing properties will be untouched.
281 
282             @exception  com::sun::star::lang::IllegalArgumentException
283                         if one of the incoming parameters seems to be invalid.
284                         That doesn't include the check, if this item exist!
285 
286             @exception  com::sun::star::container::NoSuchElementException
287                         if the requested item does not exist inside this container.
288 
289             @exception  com::sun::star::lang::WrappedTargetException
290                         if updating of the internal structures failed.
291          */
292 
293         virtual void SAL_CALL replaceByName( const ::rtl::OUString& sName        ,
294                                              const css::uno::Any&   aPropertySet )
295             throw(css::lang::IllegalArgumentException   ,
296                   css::container::NoSuchElementException,
297                   css::lang::WrappedTargetException     ,
298                   css::uno::RuntimeException            );
299 
300         //---------------------------------------
301         // XNameAccess
302 
303         /// @HTML
304         /** @short  return properties of queried detector item.
305 
306             @descr  Use this method to get all informations about a detector item of this cache.
307                     A sequence< com::sun::star::beans::PropertyValue > packed inside an Any will be returned.
308                     Following properties are defined:
309                     <table border=1>
310                     <tr>
311                         <td><b>Property</b></td>
312                         <td><b>Value<b></td>
313                         <td><b>Description<b></td>
314                     </tr>
315                     <tr>
316                         <td>Name</td>
317                         <td>[string]</td>
318                             <td>the uno implementation name for this detect service</td>
319                     </tr>
320                     <tr>
321                         <td>Types</td>
322                         <td>[sequence< string >]</td>
323                         <td>a list of all internbal type names, which this detect service is registered for</td>
324                     </tr>
325                     </table>
326 
327             @param  sName
328                     the uno implementation name the requested detector.
329 
330             @return A property set, which describes this detect service.
331                     It uses a sequence< com::sun::star::beans::PropertyValue > internally.
332 
333             @exception  com::sun::star::container::NoSuchElementException
334                         if the requested entry does not exist inside this container.
335          */
336         /// @NOHTML
337 
338         virtual css::uno::Any SAL_CALL getByName( const ::rtl::OUString& sName )
339             throw(css::container::NoSuchElementException,
340                   css::lang::WrappedTargetException     ,
341                   css::uno::RuntimeException            );
342 
343         //---------------------------------------
344         // XNameAccess
345 
346         /** @short  return list of all well know container entries available on this container.
347 
348             @attention  Because this service implements read/write access to the configuration too,
349                         this list is dynamic. Means: in multithreaded environments some items of this
350                         return list could be invalid next time!
351 
352             @return A list of all well known container items.
353          */
354 
355         virtual css::uno::Sequence< ::rtl::OUString > SAL_CALL getElementNames()
356             throw(css::uno::RuntimeException);
357 
358         //---------------------------------------
359         // XNameAccess
360 
361         /** @short  check if searched entry exist inside this container.
362 
363             @attention  In multithreaded environments it's not guaranteed, that a
364                         queried item exist next time really! It can be deleted by
365                         another thread ...
366 
367             @param  sName
368                     the name of the queried container entry.
369 
370             @return sal_True if the requested item exist; sal_False otherwise.
371          */
372 
373         virtual sal_Bool SAL_CALL hasByName( const ::rtl::OUString& sName )
374             throw(css::uno::RuntimeException);
375 
376         //---------------------------------------
377         // XElementAccess
378 
379         /** @short  return the uno type, which is used for all container items.
380 
381             @return Type of sequence< com::sun::star::beans::PropertyValue > every time - because it's fix.
382          */
383 
384         virtual css::uno::Type SAL_CALL getElementType()
385             throw(css::uno::RuntimeException);
386 
387         //---------------------------------------
388         // XElementAccess
389 
390         /** @short  return fill state of this cache.
391 
392             @return sal_True if any item exist inside this conatiner; sal_False otherwise.
393          */
394 
395         virtual sal_Bool SAL_CALL hasElements()
396             throw(css::uno::RuntimeException);
397 
398         //---------------------------------------
399         // XFlushable
400 
401         /** @short  update the configuration layer and notify all registered listener.
402 
403             @descr  All container interface methods update the internal structures of
404                     this container only. But the underlying configuration layer and
405                     may some possible other caches was not updated.
406                     Calling of flush() will do that.
407                     At the same time all currently registered flush listener will be informed,
408                     so they can update her structures too.
409                     Note: Before all these operations are started really, all changes will be
410                     verified and if necessary some corrections will be done.
411                     In case the cache will be invalid and could not be repaired an exception is thrown!
412                     Normally this container will not work correctly afterwards ...
413 
414             @exception  com::sun::star::uno::RuntimeException
415                         if the changes on this container was invald and could not be repaired.
416          */
417 
418         virtual void SAL_CALL flush()
419             throw(css::uno::RuntimeException);
420 
421         //---------------------------------------
422         // XFlushable
423 
424         /** @short  register listener for container updates.
425 
426             @param  xListener
427                     reference to listener, which wish to be registered.
428 
429             @exception  com::sun::star::uno::RuntimeException
430                         if the given listener is an invalid reference.
431                         Note: multiple calls of this method for the same listener won't be checked!
432          */
433 
434         virtual void SAL_CALL addFlushListener( const css::uno::Reference< css::util::XFlushListener >& xListener )
435             throw(css::uno::RuntimeException);
436 
437         //---------------------------------------
438         // XFlushable
439 
440         /** @short  deregister listener for container updates.
441 
442             @param  xListener
443                     reference to listener, which wish to be deregistered.
444 
445             @exception  com::sun::star::uno::RuntimeException
446                         if the given listener is an invalid reference.
447                         Note: multiple calls of this method for the same listener won't be checked!
448          */
449 
450         virtual void SAL_CALL removeFlushListener( const css::uno::Reference< css::util::XFlushListener >& xListener )
451             throw(css::uno::RuntimeException);
452 
453 }; // class DetectorFactory
454 
455 } // namespace framework
456 
457 #endif // #ifndef __FRAMEWORK_SERVICES_DETECTORFACTORY_HXX_
458