binfilter/inc/bf_xmloff/MultiPropertySetHelper.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: MultiPropertySetHelper.hxx,v $
  10  * $Revision: 1.7 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef _XMLOFF_CONDITIONALMULTIPROPERTYSETHELPER_HXX
  31 #define _XMLOFF_CONDITIONALMULTIPROPERTYSETHELPER_HXX
  32
  33
  34 #ifndef _COM_SUN_STAR_UNO_SEQUENCE_HXX_
  35 #include <com/sun/star/uno/Sequence.hxx>
  36 #endif
  37
  38 #ifndef _TOOLS_DEBUG_HXX
  39 #include <tools/debug.hxx>
  40 #endif
  41
  42
  43 namespace com { namespace sun { namespace star {
  44     namespace beans { class XMultiPropertySet; }
  45     namespace beans { class XPropertySet; }
  46     namespace beans { class XPropertySetInfo; }
  47 } } }
  48 namespace binfilter {
  49
  50
  51 /**
  52  * The MultiPropertySetHelper performs the follwing functions:
  53  *
  54  * Given a list of property names (as sal_Char** or OUString*), it can
  55  * query an XMultiPropertySet (or XPropertySet) which of these properties
  56  * it supports (method hasProperties(...)). The properties *MUST* be
  57  * sorted alphabetically.
  58  *
  59  * Then, the X(Multi)PropertySet can be queried for values, and only
  60  * the supported properties are queried. (method getValues(...)) The
  61  * values are stored in the helper itself.
  62  *
  63  * Finally, each property can be queried for existence
  64  * (method hasProperty(...)) or its value (method (getValue(...))).
  65  *
  66  * After some initial preparation (hasProperties, getValues) the
  67  * MultiPropertySetHelper can be used similarly to an
  68  * XPropertySet in that you can query the values in the places where you
  69  * need them. However, if an XMultiPropertySet is supplied, the queries
  70  * are more efficient, often significantly so.
  71  */
  72 class MultiPropertySetHelper
  73 {
  74     /// names of all properties
  75     ::rtl::OUString* pPropertyNames;
  76
  77     /// length of pPropertyNames array
  78     sal_Int16 nLength;
  79
  80     /// the sequence of property names that the current (multi)
  81     /// property set implementation supports
  82     ::com::sun::star::uno::Sequence< ::rtl::OUString > aPropertySequence;
  83
  84     /// an array of indices that maps from pPropertyNames indices to
  85     /// aPropertySequence indices
  86     sal_Int16* pSequenceIndex;
  87
  88     /// the last set of values retrieved by getValues
  89     ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any > aValues;
  90
  91     /// result of aValues.getConstArray()
  92     const ::com::sun::star::uno::Any* pValues;
  93
  94     /// an empty Any
  95     ::com::sun::star::uno::Any aEmptyAny;
  96
  97 public:
  98
  99     MultiPropertySetHelper( const sal_Char** pNames );
 100
 101     ~MultiPropertySetHelper();
 102
 103
 104     /**
 105      * Call hasPropertiesByName for the provided XPropertySetInfo and build
 106      * list of allowed properties.
 107      */
 108     void hasProperties( const ::com::sun::star::uno::Reference<
 109                             ::com::sun::star::beans::XPropertySetInfo> & );
 110
 111
 112     /**
 113      * Return whether hasProperties was called
 114      * (i.e. if we are ready to call getValues)
 115      */
 116     sal_Bool checkedProperties();
 117
 118     /**
 119      * Get values from the XMultiPropertySet.
 120      *
 121      * May only be called after hasProperties() was called for the
 122      * appropriate XPropertySetInfo.
 123      */
 124     void getValues( const ::com::sun::star::uno::Reference<
 125                             ::com::sun::star::beans::XMultiPropertySet> & );
 126
 127     /**
 128      * Get values from the XPropertySet. This can be much slower than
 129      * getValues( const Reference<XMultiPropertySet& ) and hence
 130      * should be avoided.
 131      *
 132      * May only be called after hasProperties() was called for the
 133      * appropriate XPropertySetInfo.
 134      */
 135     void getValues( const ::com::sun::star::uno::Reference<
 136                             ::com::sun::star::beans::XPropertySet> & );
 137
 138
 139
 140     /**
 141      * Get a value from the values array.
 142      *
 143      * May only be called after getValues() was called.
 144      */
 145     inline const ::com::sun::star::uno::Any& getValue( sal_Int16 nIndex );
 146
 147     /**
 148      * Find out if this property is supported.
 149      *
 150      * May only be called after hasProperties() was called.
 151      */
 152     inline sal_Bool hasProperty( sal_Int16 nIndex );
 153
 154     /**
 155      * Get a value from the XPropertySet on demand.
 156      *
 157      * If neither getValues nor getValueOnDemand has been called already
 158      * after the last call to resetValues, the values are retrieved
 159      * using getValues. Otherwise the value already retrieved is returned.
 160      * In case XMultiPropertySet is supported by the XPropertySet and
 161      * bTryMult is set, the XMultiPropertySet is used to get the values.
 162      *
 163      */
 164     const ::com::sun::star::uno::Any& getValue( sal_Int16 nIndex,
 165                         const ::com::sun::star::uno::Reference<
 166                             ::com::sun::star::beans::XPropertySet> &,
 167                         sal_Bool bTryMulti = sal_False );
 168
 169     /**
 170      * Get a value from the XMultiPropertySet on demand.
 171      *
 172      * If neither getValues nor getValueOnDemand has been called already
 173      * after the last call to resetValues, the values are retrieved
 174      * using getValues. Otherwise the value already retrieved is returned.
 175      * In case XMultiPropertySet is supported by the XPropertySet,
 176      * XMultiPropertySet is used to get the values.
 177      *
 178      */
 179     const ::com::sun::star::uno::Any& getValue( sal_Int16 nIndex,
 180                         const ::com::sun::star::uno::Reference<
 181                             ::com::sun::star::beans::XMultiPropertySet> & );
 182
 183     inline void resetValues() { pValues = 0; }
 184 };
 185
 186
 187 // inline implementations of the often-called methods getValue and hasProperty:
 188
 189 const ::com::sun::star::uno::Any& MultiPropertySetHelper::getValue(
 190     sal_Int16 nValueNo )
 191 {
 192     DBG_ASSERT( pValues != NULL,
 193                 "called getValue() without calling getValues() before");
 194     DBG_ASSERT( pSequenceIndex != NULL,
 195                 "called getValue() without calling hasProperties() before" );
 196     DBG_ASSERT( nValueNo < nLength, "index out of range" );
 197
 198     sal_Int16 nIndex = pSequenceIndex[ nValueNo ];
 199     return ( nIndex != -1 ) ? pValues[ nIndex ] : aEmptyAny;
 200 }
 201
 202 sal_Bool MultiPropertySetHelper::hasProperty( sal_Int16 nValueNo )
 203 {
 204     DBG_ASSERT( pSequenceIndex != NULL,
 205                 "called getValue() without calling hasProperties() before" );
 206     DBG_ASSERT( nValueNo < nLength, "index out of range" );
 207
 208     return pSequenceIndex[ nValueNo ] != -1;
 209 }
 210
 211 }//end of namespace binfilter
 212 #endif