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 __FILTER_CONFIG_FILTERCACHE_HXX_
25 #define __FILTER_CONFIG_FILTERCACHE_HXX_
26 
27 //_______________________________________________
28 // includes
29 
30 #include "cacheitem.hxx"
31 #include <com/sun/star/uno/Exception.hpp>
32 #include <com/sun/star/util/URL.hpp>
33 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
34 #include <com/sun/star/uno/XInterface.hpp>
35 #include <com/sun/star/container/XNameAccess.hpp>
36 #include <com/sun/star/container/XNameContainer.hpp>
37 #include <com/sun/star/container/XNameReplace.hpp>
38 #include <com/sun/star/util/ChangesEvent.hpp>
39 #include <com/sun/star/uno/Reference.h>
40 #include <com/sun/star/uno/Any.h>
41 #include <rtl/ustring.hxx>
42 
43 //_______________________________________________
44 // namespace
45 
46 namespace filter{
47     namespace config{
48 
49 //_______________________________________________
50 // definitions
51 
52 //_______________________________________________
53 
54 /** @short      implements a cache, which contains all
55                 elements of our filter and type detection
56                 configuration.
57 
58     @descr      The cache itself is threadsafe implemented.
59                 Because it should be used as a singleton only.
60                 To do so please use reference mechanism as wrapper
61                 around this FilterCache class.
62 
63     @attention  Because we use a trick to get a full initialized
64                 mutex lock during initialization time (means during
65                 the constructor runs), the base class FilterCacheLock
66                 must be the first of all declared one!
67                 Further we make it public. So any user of this class
68                 can lock us from outside too.
69  */
70 class FilterCache : public BaseLock
71 {
72     //-------------------------------------------
73     // public types
74 
75     public:
76 
77         //---------------------------------------
78 
79         /** @short  identify the type of a container item.
80 
81             @descr  Because the cache interface is a generic one
82                     every group of container items must be specified.
83          */
84         enum EItemType
85         {
86             E_TYPE          ,
87             E_FILTER        ,
88             E_FRAMELOADER   ,
89             E_CONTENTHANDLER,
90             E_DETECTSERVICE
91         };
92 
93         //---------------------------------------
94 
95         /** @short      indicates, which items already exists inside this cache
96                         and which not.
97 
98             @descr      This cache supports a 2-step load mechanism.
99                         First only types (and only some special properties of every type!)
100                         but no filters/frame loaders/content handlers will be readed.
101                         That should be enough to work with this cache e.g. for loading
102                         the first document. After this first document was loaded successfully,
103                         a special "load-on-demand-thread" will be started to fill this cache
104                         with ALL other informations, which was not readed before.
105                         Thats the second step. All operations on top of this cache will be
106                         blocked then.
107          */
108         enum EFillState
109         {
110             E_CONTAINS_NOTHING          = 0,
111             E_CONTAINS_STANDARD         = 1,
112             E_CONTAINS_TYPES            = 2,
113             E_CONTAINS_FILTERS          = 4,
114             E_CONTAINS_DETECTSERVICES   = 8,
115             E_CONTAINS_FRAMELOADERS     = 16,
116             E_CONTAINS_CONTENTHANDLERS  = 32,
117             E_CONTAINS_ALL              = 63 // must be a combination of all excepting E_CONTAINS_NOTHING! Please update if items will be added or removed ...
118         };
119 
120     //-------------------------------------------
121     // private types
122 
123     private:
124 
125         //---------------------------------------
126         /** @short      regulate, which properties of a configured item
127                         will be readed.
128 
129             @descr      To perform reading of all configuration items,
130                         only standard properties will be handled. At a second
131                         step all optional properties will be read and added to
132                         our internal structures. Of course the combination of
133                         both options can be used too, to get all properties
134                         at the same time.
135          */
136         enum EReadOption
137         {
138             E_READ_NOTHING  = 0,
139             E_READ_STANDARD = 1,
140             E_READ_UPDATE   = 2,
141             E_READ_ALL      = 3
142         };
143 
144         //---------------------------------------
145         /** @short      indicates the state of a configuration set item.
146 
147             @descr      Inside method flush we check:
148                         <ul>
149                             <li>if the item exists inside config layer but not inside our cache => REMOVED</li>
150                             <li>if the item exists inside config layer and inside our cache => CHANGED</li>
151                             <li>if the item does not exists inside config layer but inside our cache => ADDED.</li>
152                         </ul>
153          */
154         enum EItemFlushState
155         {
156             /// indicates an unchanged item (can occure e.g. if an item was added and(!) removed before it was flushed ...
157             E_ITEM_UNCHANGED = 0,
158             /// indicates an item, which exists inside config layer but not inside our own cache
159             E_ITEM_REMOVED = 1,
160             /// indicates an item, which exists inside config layer and inside our own cache
161             E_ITEM_CHANGED = 2,
162             /// indicates an item, which does not exists inside config layer but inside our own cache
163             E_ITEM_ADDED = 3
164         };
165 
166         //---------------------------------------
167         /** TODO document me */
168         enum EConfigProvider
169         {
170             E_PROVIDER_TYPES = 0,
171             E_PROVIDER_FILTERS = 1,
172             E_PROVIDER_OTHERS = 2,
173             E_PROVIDER_OLD = 3
174         };
175 
176     //-------------------------------------------
177     // member
178 
179     private:
180 
181         //---------------------------------------
182         /** @short  reference to an uno service manager, which can be used
183                     to create own needed services. */
184         mutable css::uno::Reference< css::lang::XMultiServiceFactory > m_xSMGR;
185 
186         //---------------------------------------
187         /** @short  holds the used configuration provider alive, which
188                     provides access to the list of types. */
189         mutable css::uno::Reference< css::uno::XInterface > m_xConfigTypes;
190 
191         //---------------------------------------
192         /** @short  holds the used configuration provider alive, which
193                     provides access to the list of filters. */
194         mutable css::uno::Reference< css::uno::XInterface > m_xConfigFilters;
195 
196         //---------------------------------------
197         /** @short  holds the used configuration provider alive, which
198                     provides access to the list of other values needed
199                     by our type detection framework. */
200         mutable css::uno::Reference< css::uno::XInterface > m_xConfigOthers;
201 
202         //---------------------------------------
203         /** @short  contains all loaded types with its properties. */
204         mutable CacheItemList m_lTypes;
205 
206         //---------------------------------------
207         /** @short  contains all well known detect service with its properties. */
208         mutable CacheItemList m_lDetectServices;
209 
210         //---------------------------------------
211         /** @short  contains all loaded filters with its properties. */
212         mutable CacheItemList m_lFilters;
213 
214         //---------------------------------------
215         /** @short  contains all loaded frame loader with its properties. */
216         mutable CacheItemList m_lFrameLoaders;
217 
218         //---------------------------------------
219         /** @short  contains all loaded content handler with its properties. */
220         mutable CacheItemList m_lContentHandlers;
221 
222         //---------------------------------------
223         /** @short  optimize mapping of URL extensions to a type representation,
224                     by using extensions as key and a list of internal
225                     type names as value. */
226         mutable CacheItemRegistration m_lExtensions2Types;
227 
228         //---------------------------------------
229         /** @short  optimize mapping of URL pattern to a type representation,
230                     by using patterns as key and a list of internal
231                     type names as value. */
232         mutable CacheItemRegistration m_lURLPattern2Types;
233 
234         //---------------------------------------
235         /** @short  contains the current locale of the office and will be
236                     used to work with localized configuration values. */
237         ::rtl::OUString m_sActLocale;
238 
239         ::rtl::OUString m_sProductName;
240 
241         //---------------------------------------
242         /** TODO */
243         ::rtl::OUString m_sOOoXMLFormatName;
244 
245         //---------------------------------------
246         /** TODO */
247         ::rtl::OUString m_sOOoXMLFormatVersion;
248 
249         //---------------------------------------
250         /** @short  contains status, which cache items/properties
251                     was already loaded from the underlying configuration.
252 
253             @descr  This information can be used to detect missing
254                     informations and load it on demand.
255 
256             @see    EFillState
257             @see    load()
258          */
259         EFillState m_eFillState;
260 
261         //---------------------------------------
262         /** TODO document me ... */
263         OUStringList m_lChangedTypes;
264         OUStringList m_lChangedFilters;
265         OUStringList m_lChangedDetectServices;
266         OUStringList m_lChangedFrameLoaders;
267         OUStringList m_lChangedContentHandlers;
268 
269         //---------------------------------------
270         /// readonly acccess to the module configuration of OOo
271         css::uno::Reference< css::container::XNameAccess > m_xModuleCfg;
272 
273     //-------------------------------------------
274     // interface
275 
276     public:
277 
278         //---------------------------------------
279         // ctor/dtor
280 
281         /** @short  standard ctor
282 
283             @descr  Its not allowed to do anything here ...
284                     especialy is forbidden to start operations,
285                     which needs a FilterCache instance too!
286                     Why? Because thie FilterCache instance will be
287                     used as a singleton! And if during this ctor any
288                     action related to this FilterCache singleton is
289                     started ... a race will be the result.
290 
291                     The first method after construction of a new
292                     singleton reference should be "load()". There
293                     a special fill state of this cache can be forced.
294          */
295         FilterCache();
296 
297         //---------------------------------------
298 
299         /** @short  standard dtor.
300          */
301         virtual ~FilterCache();
302 
303         //---------------------------------------
304 
305         /** @short  creates a copy of this container.
306 
307             @descr  Such copy can be used then to modify items (add/change/remove)
308                     without the risk to damage the original container.
309                     After its changed data was flushed to the configuration it can be
310                     removed.
311 
312                     The original container will get these new data automaticly
313                     because it listen for changes on the internal used configuration layer.
314                     If the new data are needed immediatly inside the original container,
315                     the method takeOver() can be used to copy all changes back.
316                     The may be following notifications of the configuration will be superflous then.
317                     But they cant be stopped ...
318 
319                     All internal structures will be copied here. But the internal used
320                     configuration (update) access wont be copied. The cloned instance contains
321                     a different one.
322 
323             @note   The cloned instance is created on the heap. The user of this instance
324                     has to remove it later.
325          */
326         virtual FilterCache* clone() const;
327 
328         //---------------------------------------
329 
330         /** @short  copy the cache content or rClone back to this instance.
331          */
332         virtual void takeOver(const FilterCache& rClone);
333 
334         //---------------------------------------
335 
336         /** @short      force special fill state of this cache.
337 
338             @descr      This method check if all requested items/properties already
339                         exists. Only missing informations will be readed.
340                         Otherwhise this method does nothing!
341 
342                         This method must be called from every user of this cache
343                         everytimes it need a filled cache. Normaly we load
344                         only standard informations into this cache on startup.
345                         After a few seconds we start a special thread, which
346                         may fill this cache completely. But if somehwere outside
347                         need a filled cache before ... it can run into trouble,
348                         if this "load-on-demand" thread does not finished its work before.
349                         This method "load(xxx)" synchronize such load-on-demand requests.
350 
351                         Of course it would be possible to supress this special load thread
352                         in general and start it manualy inside this load() request.
353                         The outside code decide then, if and when this cache will be filled
354                         with all available informations ...
355 
356             @param      bByThread
357                         indicates using of this method by our global "load-on-demand-thread".
358                         Its an implementation detail! We use it to check, if this "load()"
359                         request was forced e.g. by one of our derived service container (which need
360                         it to full fill its own operations) or if it was forced by our own
361                         "load-on-demand-thread", which tries to optimize our startup performance
362                         and start this load() only in case the office startup was already finished!
363 
364             @throw      An exception if the cache could not be filled realy
365                         or seems to be invalid afterwards. But there is no reaction
366                         at all if this method does nothing inside, because the cache
367                         is already full filled!
368          */
369         virtual void load(EFillState eRequired ,
370                           sal_Bool   bByThread = sal_False)
371             throw(css::uno::Exception);
372 
373         //---------------------------------------
374 
375         /** @short      return the current fill state of this cache.
376 
377             @descr      This information can be used e.g. to start
378                         a search on top of this cache with a minimum on
379                         informations ... and do it again, if some other
380                         cache items seems to be available after calling of "loadAll()"
381                         on this cache and first search does not had any valid results.
382 
383             @return     sal_True if the required fill state exists for this cache; FALSE
384                         otherwise.
385          */
386         virtual sal_Bool isFillState(EFillState eRequired) const
387             throw(css::uno::Exception);
388 
389         //---------------------------------------
390 
391         /** @short      return a list of key names for items, which match
392                         the specified criteria.
393 
394             @descr      The returned key names can be used at another method "getItem()"
395                         of this cache to get further informations about this item.
396 
397             @attention  Please note: because this cache can be used inside multithreaded
398                         environments, such returned key name can point to an already removed
399                         item! Please be aware of some "NoSuchElementExceptions" if you try to
400                         call any other method of this cache in relation to this key name.
401 
402             @param      eType
403                         specify the sub container of this cache, which should be used for
404                         searching. see also EItemType.
405 
406             @param      lIProps
407                         specify the property set, which must exist at the searched items
408                         as minimum.
409 
410             @param      lEProps
411                         specify the property set, which must not(!) exist at the searched items
412                         as minimum.
413 
414             @return     [OUStringList]
415                         a list of key names, which identify items of the queried sub container.
416                         May be an empty list.
417 
418             @throw      [css::uno::Exception]
419                         if some input parameter are wrong or the cache itself is not valid
420                         any longer, because any operation before damage it.
421          */
422         virtual OUStringList getMatchingItemsByProps(      EItemType  eType                ,
423                                                      const CacheItem& lIProps              ,
424                                                      const CacheItem& lEProps = CacheItem()) const
425             throw(css::uno::Exception);
426 
427         //---------------------------------------
428 
429         /** @short      indicates if the requested sub container
430                         contains some items.
431 
432             @descr      We dont provide any information about the count
433                         of such items. Because we dont implement any index
434                         based interface! The information "we have items or not"
435                         must be enough for the outside code ... till somewhere
436                         give us a good reason. :-)
437 
438             @param      eType
439                         specify the sub container of this cache, which should be used.
440                         see also EItemType.
441 
442             @return     [sal_Bool]
443                         True, if the requested sub container contains some items;
444                         False otherwhise.
445 
446             @throw      [css::uno::Exception]
447                         if some input parameter are wrong or the cache itself is not valid
448                         any longer, because any operation before damage it.
449          */
450         virtual sal_Bool hasItems(EItemType eType) const
451             throw(css::uno::Exception);
452 
453         //---------------------------------------
454 
455         /** @short      return a list of all key names, which represent
456                         an item inside the specified sub container.
457 
458             @attention  Please note: because this cache can be used inside multithreaded
459                         environments, such returned key names can point to some already removed
460                         items! Please be aware of some "NoSuchElementExceptions" if you try to
461                         call any other method of this cache in relation to this key names.
462 
463             @param      eType
464                         specify the sub container of this cache, which should be used for
465                         searching. see also EItemType.
466 
467             @return     [OUStringList]
468                         a list of key names, which can be used to access the item properties
469                         using some other methods of this cache.
470 
471             @throw      [css::uno::Exception]
472                         if some input parameter are wrong or the cache itself is not valid
473                         any longer, because any operation before damage it.
474          */
475         virtual OUStringList getItemNames(EItemType eType) const
476             throw(css::uno::Exception);
477 
478         //---------------------------------------
479 
480         /** @short      check if the required item exist inside this container.
481 
482             @attention  This method exists to supports some UNO container interfaces
483                         only. (e.g. XNameAccess.hasByName()). But inside multithreaded
484                         environments there is no guarantee, that this item still exists, if
485                         its realy requested e.g. by calling getItem()!
486                         Be aware of some NoSuchElementExistExceptions ...
487 
488             @param      eType
489                         specify the sub container of this cache, which should be used.
490                         see also EItemType.
491 
492             @param      sItem
493                         the key name of the requested item inside the pecified sub container.
494 
495             @throw      [css::uno::Exception]
496                         if some input parameter are wrong or the cache itself is not valid
497                         any longer, because any operation before damage it.
498          */
499         virtual sal_Bool hasItem(      EItemType        eType,
500                                  const ::rtl::OUString& sItem)
501             throw(css::uno::Exception);
502 
503         //---------------------------------------
504 
505         /** @short      return an item, which match the specified type and name.
506 
507             @descr      Because this cache can be used inside multithreaded environments
508                         the caller must be aware of some exceptions - especialy a "NoSuchElementExcepotion".
509                         May another thread already removed the required item before ...
510 
511             @param      eType
512                         specify the sub container of this cache, which should be used for
513                         searching. see also EItemType.
514 
515             @param      sItem
516                         specify the requested item by its key name.
517 
518             @return     [CacheItem]
519                         the required item if it could be located ...
520                         But we throw an exception if the required item does not exist!
521 
522             @throw      [css::container::NoSuchElementException]
523                         if the required item does not still exist.
524 
525             @throw      [css::uno::Exception]
526                         if some input parameter are wrong or the cache itself is not valid
527                         any longer, because any operation before damage it.
528          */
529         virtual CacheItem getItem(      EItemType        eType,
530                                   const ::rtl::OUString& sItem)
531             throw(css::uno::Exception);
532 
533         //---------------------------------------
534 
535         /** TODO document me ...
536          */
537         virtual void removeItem(      EItemType        eType,
538                                 const ::rtl::OUString& sItem)
539             throw(css::uno::Exception);
540 
541         //---------------------------------------
542 
543         /** TODO document me ...
544          */
545         virtual void setItem(      EItemType        eType ,
546                              const ::rtl::OUString& sItem ,
547                              const CacheItem&       aValue)
548             throw(css::uno::Exception);
549 
550         //---------------------------------------
551 
552         /** TODO document me ...
553          */
554         virtual void refreshItem(      EItemType        eType,
555                                  const ::rtl::OUString& sItem)
556             throw(css::uno::Exception);
557 
558         //---------------------------------------
559 
560         /** @short      add some implicit properties to the given
561                         cache item reference.
562 
563             @descr      Such properties can e.g. finalized or mandatory.
564                         They are not persistent  and not realy part of e.g. a
565                         filter not. But they are attributes of a configuration
566                         entry and can influence our container interface.
567 
568             @attention  These properties are not part of the normal CacheItem
569                         returned by the method getItem(). Because getItem() is
570                         used internaly too but these specialized properties
571                         are needed at our container services only. So these
572                         function sets are different to allow different handling.
573 
574             @param      eType
575                         specify the sub container of this cache, which should be used for
576                         searching. see also EItemType.
577 
578             @param      sItem
579                         specify the requested item by its key name.
580 
581             @param      rItem
582                         contains already the normal properties of this item,
583                         and will be used as out parameter to add the implicit
584                         attributes there.
585 
586             @throw      [css::uno::Exception]
587                         if an internal error occured.
588                         Note: If the item is missing inside the underlying configuration
589                         no exception will be thrown. In such case the item is marked as
590                         finalized/mandatory automaticly
591                         Reason: May be the item cames from the old configuration package and
592                         was not migrated to the new one. So we cant provide write access
593                         to such items ...
594          */
595         virtual void addStatePropsToItem(      EItemType        eType,
596                                          const ::rtl::OUString& sItem,
597                                                CacheItem&       rItem)
598             throw(css::uno::Exception);
599 
600         //---------------------------------------
601 
602         /** TODO document me
603          */
604         virtual void removeStatePropsFromItem(CacheItem& aValue)
605             throw(css::uno::Exception);
606 
607         //---------------------------------------
608 
609         /** @short      force writing of all changes (which was made after
610                         last flush was called) back to the configuration.
611 
612             @descr      TODO
613 
614             @throw      [css::uno::Exception]
615                         if the cache itself is not valid
616                         any longer, because any operation before damage it.
617          */
618         virtual void flush()
619             throw(css::uno::Exception);
620 
621         //---------------------------------------
622 
623         /** @short      supports a flat type detection for given URL.
624 
625             @descr      Because such detection works on our optimized internal
626                         structures (e.g. mapping from extensions/pattern to type names),
627                         it should be made inside this cache.
628 
629             @param      aURL
630                         URL of the content, which type should be detected.
631                         Its already parsed and splitted into its differnt parts,
632                         like e.g.: main, jump marks etcpp.
633 
634             @param      rFlatTypes
635                         used as [out] parameter to add all types, which match to the given
636                         URL. Further an information is added for every type. It indicates, how
637                         this type is related to the specified URL (means e.g. if it matches
638                         by extension or URLPattern ...).
639 
640             @attention  Please note: because this cache can be used inside multithreaded
641                         environments, such returned key names can point to some already removed
642                         items! Please be aware of some "NoSuchElementExceptions" if you try to
643                         call any other method of this cache in relation to this key names.
644 
645             @throw      [css::uno::Exception]
646                         if the cache itself is not valid
647                         any longer, because any operation before damage it.
648          */
649         virtual void detectFlatForURL(const css::util::URL& aURL      ,
650                                             FlatDetection&  rFlatTypes) const
651             throw(css::uno::Exception);
652 
653     //-------------------------------------------
654     // private helper
655 
656     private:
657 
658         //---------------------------------------
659 
660         /** @short      return a reference to one of our internal
661                         sub container, which contains items of the
662                         requested type.
663 
664             @param      eType
665                         specify, which sub container is needed outside.
666 
667             @return     [CacheItemList&]
668                         a reference(!) to the right sub container member.
669 
670             @throw      [css::uno::Exception]
671                         if the required list does not exist.
672          */
673         CacheItemList& impl_getItemList(EItemType eType) const
674             throw(css::uno::Exception);
675 
676         //---------------------------------------
677 
678         /** @short      return a valid configuration update access
679                         to the underlying configuration package, which
680                         is fix for this cache.
681 
682             @descr      It checks first, if the internal member m_xConfig already
683                         points to an open update access. If not - it opens a new one.
684                         Doing so this method can be called everytimes a configuration
685                         access is needed.
686 
687             @param      eProvider
688                         specify the needed configuration provider.
689                         see EConfigProvider for further informations ...
690 
691             @attention  If a configuration access was opened successfully
692                         all neccessary listener connections will be established
693                         too. So this cache will be informed about outside updates.
694          */
695         css::uno::Reference< css::uno::XInterface > impl_openConfig(EConfigProvider eProvide)
696             throw(css::uno::Exception);
697 
698         //---------------------------------------
699 
700         /** @short      tries to open the requested configuration root
701                         using the specified modi.
702 
703             @param      sRoot
704                         specify the configuration root, which should be opened.
705 
706             @param      bReadOnly
707                         enable/disable write access on the returned configuration
708                         object.
709 
710             @param      bLocalesMode
711                         enable/disable special handling of localized configuratiom
712                         items by the returned configuration object.
713 
714             @return     A valid reference, if the configuration access could be opened
715                         and initialized within the requested modes successfully;
716                         a NULL reference otherwhise.
717          */
718         css::uno::Reference< css::uno::XInterface > impl_createConfigAccess(const ::rtl::OUString& sRoot       ,
719                                                                                   sal_Bool         bReadOnly   ,
720                                                                                   sal_Bool         bLocalesMode);
721 
722         //---------------------------------------
723 
724         /** @short      reads the specified configuration key
725                         and return its value.
726 
727             @descr      The specified key must be an absolute configuration path,
728                         which can be splitted into its package and relative path tokens.
729 
730             @attention  Because this function might opens a new configuration
731                         read access for reading one key value only, it should
732                         be used in rare cases only. Its an easy way ... but an
733                         expensive one.
734 
735             @param      sDirectKey
736                         the absolute configuration path, which should be readed.
737 
738             @return     [css::uno::Any]
739                         the value of the requested key.
740                         Can be empty if an internal error occured or if the requested
741                         key does not exists!
742          */
743         css::uno::Any impl_getDirectCFGValue(const ::rtl::OUString& sDirectKey);
744 
745         //---------------------------------------
746 
747         /** @short      load the underlying configuration into this cache.
748 
749             @descr      Which items should be readed can be regulate by the
750                         parameter eRequiredState. That provides the possibility
751                         to load standard values on startup only and update this
752                         cache later on demand with all available informations.
753 
754             @param      eRequiredState
755                         indicates, which fill state this cache should have afterwards.
756          */
757         void impl_load(EFillState eRequiredState)
758             throw(css::uno::Exception);
759 
760         //---------------------------------------
761 
762         /** @short      validate the whole cache and create
763                         structures for optimized items access.
764 
765             @descr      Wrong cache items will be removed automaticly.
766                         Wrong dependencies will be corrected automaticly.
767                         If something could not be repaired - an exception
768                         is thrown.
769                         Further some optmized structures will be created.
770                         E.g.: a hash to map extensions to her types.
771 
772             @attention  There is no exception, if the cache could be repaired
773                         but contained wrong elements before!
774 
775             @throw      [css::uno::Exception]
776                         if cache is invalid and could not be repaired.
777          */
778         void impl_validateAndOptimize()
779             throw(css::uno::Exception);
780 
781         //---------------------------------------
782 
783         /** @short      register the specified item for the given type.
784 
785             @descr      Because detect services, frame loader or content handler
786                         are not listed inside the xml configuration as seperated
787                         items (they are properties of any type entry!), this method update
788                         the internal lists of such items. Thats neccessary to have
789                         it accessible for our container interfaces of detect, frame loader
790                         and content handler services.
791 
792             @param      pList
793                         points to a CacheItemList of this filter cache, where
794                         this item registration should be updated or added.
795 
796             @param      sItem
797                         specify the detect service, frame loader or content handler,
798                         which should be registered for the given type.
799 
800             @param      sType
801                         contains the internal type name, where the item should be registered for.
802 
803             @throw      [css::uno::Exception]
804                         If registration failed by any reason.
805                         That does not include double registrations!
806          */
807         void impl_resolveItem4TypeRegistration(      CacheItemList*   pList,
808                                                const ::rtl::OUString& sItem,
809                                                const ::rtl::OUString& sType)
810             throw(css::uno::Exception);
811 
812     //-------------------------------------------
813     // static helper
814 
815     private:
816 
817         //---------------------------------------
818 
819         /** @short  read the specified config set into the cache.
820 
821             @descr  This method provides the following mechanism for reading:
822                     a) read only standard properties of set items
823                     b) read anything
824                     c) read only optional properties and update already existing
825                        items of the specified cache
826 
827             @param  xConfig
828                     API which provides access to the required configuration set.
829 
830             @param  eType
831                     specify the type of config item, which must be interpreted.
832                     Of course this information can be used to locate the right set
833                     at the given xConfig API object.
834 
835             @param  eOption
836                     regulate reading of standard/optional or all properties.
837 
838             @param  pCache
839                     points to the cache member, which should be filled or updated.
840 
841             @throw  [css::uno::Exception]
842                     if an unrecoverable error occure inside this operation.
843          */
844         void impl_loadSet(const css::uno::Reference< css::container::XNameAccess >& xConfig,
845                                 EItemType                                           eType  ,
846                                 EReadOption                                         eOption,
847                                 CacheItemList*                                      pCache )
848             throw(css::uno::Exception);
849 
850         //---------------------------------------
851 
852         /** @short  read the specified container item from the given configuration set.
853 
854             @descr  Its not added to any internal structures here. That must be done
855                     outside this method.
856 
857             @param  xSet
858                     provides access to the configuration set, which includes all items.
859 
860             @param  eType
861                     specify, which container item type must be readed.
862 
863             @param  sItem
864                     means the internal name, which can be used to adress the item
865                     properties relativ to the given configuration set.
866 
867             @param  eOption
868                     regulate, which properties of the requested item should be read.
869                     See defintion of EReadOption for further informations.
870 
871             @throw  [css::uno::Exception]
872                     if an unrecoverable error occure inside this operation.
873          */
874         CacheItem impl_loadItem(const css::uno::Reference< css::container::XNameAccess >& xSet   ,
875                                       EItemType                                           eType  ,
876                                 const ::rtl::OUString&                                    sItem  ,
877                                       EReadOption                                         eOption)
878             throw(css::uno::Exception);
879 
880         //---------------------------------------
881 
882         /** @short  try to load the requested item on demand from the underlying configuration
883                     layer.
884 
885             @descr  The outside code has to be shure, that the item does not already exists
886                     inside this cachse. Otherwise it will be loaded twice. This method
887                     doesnt check such constellations!
888 
889             @param  eType
890                     specify the type of config item, which must be interpreted.
891                     Of course this information can be used to locate the right set
892                     at the given xConfig API object.
893 
894             @param  sItem
895                     the set node name of the requested item.
896 
897             @return An iterator, which points directly to the new cached item.
898                     Is a valid iterator if no exception occured here!
899                     But to improve robustness - it should be checked :-)
900 
901             @throw  [css::container::NoSuchElementException]
902                     if the item does not exists inside the configuration layer too!
903 
904             @throw  [css::uno::Exception]
905                     if an unrecoverable error occure inside this operation.
906          */
907         CacheItemList::iterator impl_loadItemOnDemand(      EItemType        eType,
908                                                       const ::rtl::OUString& sItem)
909             throw(css::uno::Exception);
910 
911         //---------------------------------------
912 
913         /** TODO */
914         void impl_saveItem(const css::uno::Reference< css::container::XNameReplace >& xSet  ,
915                                  EItemType                                            eType ,
916                            const CacheItem&                                           aValue)
917             throw(css::uno::Exception);
918 
919         //---------------------------------------
920 
921         /** TODO */
922         void impl_addItem2FlushList(      EItemType        eType,
923                                     const ::rtl::OUString& sItem)
924             throw(css::uno::Exception);
925 
926 
927         //---------------------------------------
928 
929         /** TODO */
930         void impl_flushByList(const css::uno::Reference< css::container::XNameAccess >& xSet  ,
931                                     EItemType                                           eType ,
932                               const CacheItemList&                                      rCache,
933                               const OUStringList&                                       lItems)
934             throw(css::uno::Exception);
935 
936         //---------------------------------------
937 
938         /** @short  specify, which save operation is neccessary for the specified item.
939 
940             @desrc  If an item of this cache will be added/removed or modified it will
941                     be changed inside memory only first. But we save its name inside a special
942                     list of changed items. If at least the method flush() is called, we use
943                     this list to check if the item was changed/added or removed. This method
944                     checks the exist state of the requested item inside our own cache
945                     and inside the underlying configuration layer to find out, if the item
946                     must be removed/added or modified inside the configuratuion layer.
947 
948             @param  xSet
949                     points directly to the configuration set, where the item should resist
950                     (if it exists!).
951 
952             @param  rList
953                     points to our internal cache list, where the item should resist
954                     (if it exists!).
955 
956             @param  sItem
957                     the internal name of the item, which should be checked.
958 
959             @return An enum value of type EItemFlushState, which indicates the needed
960                     API operation for updating the underlying configuration layer.
961 
962             @throws An exception if anything failed inside this operation.
963                     e.g. the given configuration set was not open.
964          */
965         EItemFlushState impl_specifyFlushOperation(const css::uno::Reference< css::container::XNameAccess >& xSet ,
966                                                    const CacheItemList&                                      rList,
967                                                    const ::rtl::OUString&                                    sItem)
968             throw(css::uno::Exception);
969 
970         //---------------------------------------
971 
972         /** TODO */
973         void impl_readPatchUINames(const css::uno::Reference< css::container::XNameAccess >& xNode,
974                                          CacheItem&                                          rItem)
975             throw(css::uno::Exception);
976 
977         //---------------------------------------
978 
979         /** TODO */
980         void impl_savePatchUINames(const css::uno::Reference< css::container::XNameReplace >& xNode,
981                                    const CacheItem&                                           rItem)
982             throw(css::uno::Exception);
983 
984         //---------------------------------------
985 
986         /** TODO */
987         void impl_readOldFormat()
988             throw(css::uno::Exception);
989 
990         //---------------------------------------
991 
992         /** TODO */
993         CacheItem impl_readOldItem(const css::uno::Reference< css::container::XNameAccess >& xSet ,
994                                          EItemType                                           eType,
995                                    const ::rtl::OUString&                                    sItem)
996             throw(css::uno::Exception);
997 
998         //---------------------------------------
999 
1000         /** TODO */
1001         void impl_interpretDataVal4Type(const ::rtl::OUString& sValue,
1002                                               sal_Int32        nProp ,
1003                                               CacheItem&       rItem );
1004 
1005         //---------------------------------------
1006 
1007         /** TODO */
1008         void impl_interpretDataVal4Filter(const ::rtl::OUString& sValue,
1009                                                 sal_Int32        nProp ,
1010                                                 CacheItem&       rItem );
1011 
1012         //---------------------------------------
1013 
1014         /** TODO */
1015         OUStringList impl_tokenizeString(const ::rtl::OUString& sData     ,
1016                                                sal_Unicode      cSeperator);
1017 
1018         //---------------------------------------
1019 
1020 #if OSL_DEBUG_LEVEL > 0
1021         /** TODO */
1022         ::rtl::OUString impl_searchFrameLoaderForType(const ::rtl::OUString& sType) const;
1023         ::rtl::OUString impl_searchContentHandlerForType(const ::rtl::OUString& sType) const;
1024 #endif
1025 
1026         //---------------------------------------
1027         /** @short check if the specified OOo module is installed.
1028 
1029             @param  sModule
1030                     the long name of the module (e.g. "com.sun.star.text.TextDocument").
1031 
1032             @return sal_True if the requested module is installed; sal_False otherwise.
1033          */
1034         sal_Bool impl_isModuleInstalled(const ::rtl::OUString& sModule);
1035 
1036         //---------------------------------------
1037 
1038         /** @short  convert a list of flag names to its int representation.
1039 
1040             @param  lNames
1041                     the list of flag names.
1042 
1043             @return [sal_Int32]
1044                     the converted flag field.
1045          */
1046         static sal_Int32 impl_convertFlagNames2FlagField(const css::uno::Sequence< ::rtl::OUString >& lNames);
1047 
1048         //---------------------------------------
1049 
1050         /** @short  convert a flag field value to its list representation of flag names.
1051 
1052             @param  nFlags
1053                     the flag field value
1054 
1055             @return [seq< string >]
1056                     the converted flag name list.
1057          */
1058         static css::uno::Sequence< ::rtl::OUString > impl_convertFlagField2FlagNames(sal_Int32 nFlags);
1059 };
1060 
1061     } // namespace config
1062 } // namespace filter
1063 
1064 #endif // __FILTER_CONFIG_FILTERCACHE_HXX_
1065