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