xmloff/inc/MultiPropertySetHelper.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef INCLUDED_XMLOFF_INC_MULTIPROPERTYSETHELPER_HXX
  20 #define INCLUDED_XMLOFF_INC_MULTIPROPERTYSETHELPER_HXX
  21
  22 #include <rtl/ustring.hxx>
  23 #include <com/sun/star/uno/Sequence.hxx>
  24 #include <tools/debug.hxx>
  25
  26
  27 namespace com { namespace sun { namespace star {
  28     namespace beans { class XMultiPropertySet; }
  29     namespace beans { class XPropertySet; }
  30     namespace beans { class XPropertySetInfo; }
  31 } } }
  32
  33
  34 /**
  35  * The MultiPropertySetHelper performs the following functions:
  36  *
  37  * Given a list of property names (as sal_Char** or OUString*), it can
  38  * query an XMultiPropertySet (or XPropertySet) which of these properties
  39  * it supports (method hasProperties(...)). The properties *MUST* be
  40  * sorted alphabetically.
  41  *
  42  * Then, the X(Multi)PropertySet can be queried for values, and only
  43  * the supported properties are queried. (method getValues(...)) The
  44  * values are stored in the helper itself.
  45  *
  46  * Finally, each property can be queried for existence
  47  * (method hasProperty(...)) or its value (method (getValue(...))).
  48  *
  49  * After some initial preparation (hasProperties, getValues) the
  50  * MultiPropertySetHelper can be used similarly to an
  51  * XPropertySet in that you can query the values in the places where you
  52  * need them. However, if an XMultiPropertySet is supplied, the queries
  53  * are more efficient, often significantly so.
  54  */
  55 class MultiPropertySetHelper
  56 {
  57     /// names of all properties
  58     OUString* pPropertyNames;
  59
  60     /// length of pPropertyNames array
  61     sal_Int16 nLength;
  62
  63     /// the sequence of property names that the current (multi)
  64     /// property set implementation supports
  65     css::uno::Sequence< OUString > aPropertySequence;
  66
  67     /// an array of indices that maps from pPropertyNames indices to
  68     /// aPropertySequence indices
  69     sal_Int16* pSequenceIndex;
  70
  71     /// the last set of values retrieved by getValues
  72     css::uno::Sequence< css::uno::Any > aValues;
  73
  74     /// result of aValues.getConstArray()
  75     const css::uno::Any* pValues;
  76
  77     /// an empty Any
  78     css::uno::Any aEmptyAny;
  79
  80 public:
  81
  82     MultiPropertySetHelper( const sal_Char** pNames );
  83
  84     ~MultiPropertySetHelper();
  85
  86
  87     /**
  88      * Call hasPropertiesByName for the provided XPropertySetInfo and build
  89      * list of allowed properties.
  90      */
  91     void hasProperties( const css::uno::Reference<css::beans::XPropertySetInfo> & );
  92
  93
  94     /**
  95      * Return whether hasProperties was called
  96      * (i.e. if we are ready to call getValues)
  97      */
  98     bool checkedProperties();
  99
 100     /**
 101      * Get values from the XMultiPropertySet.
 102      *
 103      * May only be called after hasProperties() was called for the
 104      * appropriate XPropertySetInfo.
 105      */
 106     void getValues( const css::uno::Reference<css::beans::XMultiPropertySet> & );
 107
 108     /**
 109      * Get values from the XPropertySet. This can be much slower than
 110      * getValues( const Reference<XMultiPropertySet& ) and hence
 111      * should be avoided.
 112      *
 113      * May only be called after hasProperties() was called for the
 114      * appropriate XPropertySetInfo.
 115      */
 116     void getValues( const css::uno::Reference<css::beans::XPropertySet> & );
 117
 118
 119     /**
 120      * Get a value from the values array.
 121      *
 122      * May only be called after getValues() was called.
 123      */
 124     inline const css::uno::Any& getValue( sal_Int16 nIndex );
 125
 126     /**
 127      * Find out if this property is supported.
 128      *
 129      * May only be called after hasProperties() was called.
 130      */
 131     inline bool hasProperty( sal_Int16 nIndex );
 132
 133     /**
 134      * Get a value from the XPropertySet on demand.
 135      *
 136      * If neither getValues nor getValueOnDemand has been called already
 137      * after the last call to resetValues, the values are retrieved
 138      * using getValues. Otherwise the value already retrieved is returned.
 139      * In case XMultiPropertySet is supported by the XPropertySet and
 140      * bTryMult is set, the XMultiPropertySet is used to get the values.
 141      *
 142      */
 143     const css::uno::Any& getValue( sal_Int16 nIndex,
 144                         const css::uno::Reference<css::beans::XPropertySet> &,
 145                         bool bTryMulti = false );
 146
 147     /**
 148      * Get a value from the XMultiPropertySet on demand.
 149      *
 150      * If neither getValues nor getValueOnDemand has been called already
 151      * after the last call to resetValues, the values are retrieved
 152      * using getValues. Otherwise the value already retrieved is returned.
 153      * In case XMultiPropertySet is supported by the XPropertySet,
 154      * XMultiPropertySet is used to get the values.
 155      *
 156      */
 157     const css::uno::Any& getValue( sal_Int16 nIndex,
 158                         const css::uno::Reference<css::beans::XMultiPropertySet> & );
 159
 160     inline void resetValues() { pValues = nullptr; }
 161 };
 162
 163
 164 // inline implementations of the often-called methods getValue and hasProperty:
 165
 166 const css::uno::Any& MultiPropertySetHelper::getValue(
 167     sal_Int16 nValueNo )
 168 {
 169     assert(pValues && "called getValue() without calling getValues()");
 170     assert(pSequenceIndex && "called getValue() without calling hasProperties()");
 171     assert(nValueNo < nLength);
 172
 173     sal_Int16 nIndex = pSequenceIndex[ nValueNo ];
 174     return ( nIndex != -1 ) ? pValues[ nIndex ] : aEmptyAny;
 175 }
 176
 177 bool MultiPropertySetHelper::hasProperty( sal_Int16 nValueNo )
 178 {
 179     assert(pSequenceIndex && "called hasProperty() without calling hasProperties()");
 180     assert(nValueNo < nLength);
 181
 182     return pSequenceIndex[ nValueNo ] != -1;
 183 }
 184
 185 #endif
 186
 187 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */