xmloff/inc/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 #include <rtl/ustring.hxx>
  34 #include <com/sun/star/uno/Sequence.hxx>
  35 #include <tools/debug.hxx>
  36
  37
  38 namespace com { namespace sun { namespace star {
  39     namespace beans { class XMultiPropertySet; }
  40     namespace beans { class XPropertySet; }
  41     namespace beans { class XPropertySetInfo; }
  42 } } }
  43
  44
  45 /**
  46  * The MultiPropertySetHelper performs the follwing functions:
  47  *
  48  * Given a list of property names (as sal_Char** or OUString*), it can
  49  * query an XMultiPropertySet (or XPropertySet) which of these properties
  50  * it supports (method hasProperties(...)). The properties *MUST* be
  51  * sorted alphabetically.
  52  *
  53  * Then, the X(Multi)PropertySet can be queried for values, and only
  54  * the supported properties are queried. (method getValues(...)) The
  55  * values are stored in the helper itself.
  56  *
  57  * Finally, each property can be queried for existence
  58  * (method hasProperty(...)) or its value (method (getValue(...))).
  59  *
  60  * After some initial preparation (hasProperties, getValues) the
  61  * MultiPropertySetHelper can be used similarly to an
  62  * XPropertySet in that you can query the values in the places where you
  63  * need them. However, if an XMultiPropertySet is supplied, the queries
  64  * are more efficient, often significantly so.
  65  */
  66 class MultiPropertySetHelper
  67 {
  68     /// names of all properties
  69     ::rtl::OUString* pPropertyNames;
  70
  71     /// length of pPropertyNames array
  72     sal_Int16 nLength;
  73
  74     /// the sequence of property names that the current (multi)
  75     /// property set implementation supports
  76     ::com::sun::star::uno::Sequence< ::rtl::OUString > aPropertySequence;
  77
  78     /// an array of indices that maps from pPropertyNames indices to
  79     /// aPropertySequence indices
  80     sal_Int16* pSequenceIndex;
  81
  82     /// the last set of values retrieved by getValues
  83     ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any > aValues;
  84
  85     /// result of aValues.getConstArray()
  86     const ::com::sun::star::uno::Any* pValues;
  87
  88     /// an empty Any
  89     ::com::sun::star::uno::Any aEmptyAny;
  90
  91 public:
  92
  93     MultiPropertySetHelper( const sal_Char** pNames );
  94
  95     MultiPropertySetHelper( const ::rtl::OUString* pNames );
  96
  97     ~MultiPropertySetHelper();
  98
  99
 100     /**
 101      * Call hasPropertiesByName for the provided XPropertySetInfo and build
 102      * list of allowed properties.
 103      */
 104     void hasProperties( const ::com::sun::star::uno::Reference<
 105                             ::com::sun::star::beans::XPropertySetInfo> & );
 106
 107
 108     /**
 109      * Return whether hasProperties was called
 110      * (i.e. if we are ready to call getValues)
 111      */
 112     sal_Bool checkedProperties();
 113
 114     /**
 115      * Get values from the XMultiPropertySet.
 116      *
 117      * May only be called after hasProperties() was called for the
 118      * appropriate XPropertySetInfo.
 119      */
 120     void getValues( const ::com::sun::star::uno::Reference<
 121                             ::com::sun::star::beans::XMultiPropertySet> & );
 122
 123     /**
 124      * Get values from the XPropertySet. This can be much slower than
 125      * getValues( const Reference<XMultiPropertySet& ) and hence
 126      * should be avoided.
 127      *
 128      * May only be called after hasProperties() was called for the
 129      * appropriate XPropertySetInfo.
 130      */
 131     void getValues( const ::com::sun::star::uno::Reference<
 132                             ::com::sun::star::beans::XPropertySet> & );
 133
 134
 135
 136     /**
 137      * Get a value from the values array.
 138      *
 139      * May only be called after getValues() was called.
 140      */
 141     inline const ::com::sun::star::uno::Any& getValue( sal_Int16 nIndex );
 142
 143     /**
 144      * Find out if this property is supported.
 145      *
 146      * May only be called after hasProperties() was called.
 147      */
 148     inline sal_Bool hasProperty( sal_Int16 nIndex );
 149
 150     /**
 151      * Get a value from the XPropertySet on demand.
 152      *
 153      * If neither getValues nor getValueOnDemand has been called already
 154      * after the last call to resetValues, the values are retrieved
 155      * using getValues. Otherwise the value already retrieved is returned.
 156      * In case XMultiPropertySet is supported by the XPropertySet and
 157      * bTryMult is set, the XMultiPropertySet is used to get the values.
 158      *
 159      */
 160     const ::com::sun::star::uno::Any& getValue( sal_Int16 nIndex,
 161                         const ::com::sun::star::uno::Reference<
 162                             ::com::sun::star::beans::XPropertySet> &,
 163                         sal_Bool bTryMulti = sal_False );
 164
 165     /**
 166      * Get a value from the XMultiPropertySet on demand.
 167      *
 168      * If neither getValues nor getValueOnDemand has been called already
 169      * after the last call to resetValues, the values are retrieved
 170      * using getValues. Otherwise the value already retrieved is returned.
 171      * In case XMultiPropertySet is supported by the XPropertySet,
 172      * XMultiPropertySet is used to get the values.
 173      *
 174      */
 175     const ::com::sun::star::uno::Any& getValue( sal_Int16 nIndex,
 176                         const ::com::sun::star::uno::Reference<
 177                             ::com::sun::star::beans::XMultiPropertySet> & );
 178
 179     inline void resetValues() { pValues = 0; }
 180 };
 181
 182
 183 // inline implementations of the often-called methods getValue and hasProperty:
 184
 185 const ::com::sun::star::uno::Any& MultiPropertySetHelper::getValue(
 186     sal_Int16 nValueNo )
 187 {
 188     DBG_ASSERT( pValues != NULL,
 189                 "called getValue() without calling getValues() before");
 190     DBG_ASSERT( pSequenceIndex != NULL,
 191                 "called getValue() without calling hasProperties() before" );
 192     DBG_ASSERT( nValueNo < nLength, "index out of range" );
 193
 194     sal_Int16 nIndex = pSequenceIndex[ nValueNo ];
 195     return ( nIndex != -1 ) ? pValues[ nIndex ] : aEmptyAny;
 196 }
 197
 198 sal_Bool MultiPropertySetHelper::hasProperty( sal_Int16 nValueNo )
 199 {
 200     DBG_ASSERT( pSequenceIndex != NULL,
 201                 "called getValue() without calling hasProperties() before" );
 202     DBG_ASSERT( nValueNo < nLength, "index out of range" );
 203
 204     return pSequenceIndex[ nValueNo ] != -1;
 205 }
 206
 207 #endif