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     ::com::sun::star::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     ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Any > aValues;
  73
  74     /// result of aValues.getConstArray()
  75     const ::com::sun::star::uno::Any* pValues;
  76
  77     /// an empty Any
  78     ::com::sun::star::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 ::com::sun::star::uno::Reference<
  92                             ::com::sun::star::beans::XPropertySetInfo> & );
  93
  94
  95     /**
  96      * Return whether hasProperties was called
  97      * (i.e. if we are ready to call getValues)
  98      */
  99     bool checkedProperties();
 100
 101     /**
 102      * Get values from the XMultiPropertySet.
 103      *
 104      * May only be called after hasProperties() was called for the
 105      * appropriate XPropertySetInfo.
 106      */
 107     void getValues( const ::com::sun::star::uno::Reference<
 108                             ::com::sun::star::beans::XMultiPropertySet> & );
 109
 110     /**
 111      * Get values from the XPropertySet. This can be much slower than
 112      * getValues( const Reference<XMultiPropertySet& ) and hence
 113      * should be avoided.
 114      *
 115      * May only be called after hasProperties() was called for the
 116      * appropriate XPropertySetInfo.
 117      */
 118     void getValues( const ::com::sun::star::uno::Reference<
 119                             ::com::sun::star::beans::XPropertySet> & );
 120
 121
 122
 123     /**
 124      * Get a value from the values array.
 125      *
 126      * May only be called after getValues() was called.
 127      */
 128     inline const ::com::sun::star::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 ::com::sun::star::uno::Any& getValue( sal_Int16 nIndex,
 148                         const ::com::sun::star::uno::Reference<
 149                             ::com::sun::star::beans::XPropertySet> &,
 150                         bool bTryMulti = false );
 151
 152     /**
 153      * Get a value from the XMultiPropertySet on demand.
 154      *
 155      * If neither getValues nor getValueOnDemand has been called already
 156      * after the last call to resetValues, the values are retrieved
 157      * using getValues. Otherwise the value already retrieved is returned.
 158      * In case XMultiPropertySet is supported by the XPropertySet,
 159      * XMultiPropertySet is used to get the values.
 160      *
 161      */
 162     const ::com::sun::star::uno::Any& getValue( sal_Int16 nIndex,
 163                         const ::com::sun::star::uno::Reference<
 164                             ::com::sun::star::beans::XMultiPropertySet> & );
 165
 166     inline void resetValues() { pValues = 0; }
 167 };
 168
 169
 170 // inline implementations of the often-called methods getValue and hasProperty:
 171
 172 const ::com::sun::star::uno::Any& MultiPropertySetHelper::getValue(
 173     sal_Int16 nValueNo )
 174 {
 175     assert(pValues && "called getValue() without calling getValues()");
 176     assert(pSequenceIndex && "called getValue() without calling hasProperties()");
 177     assert(nValueNo < nLength);
 178
 179     sal_Int16 nIndex = pSequenceIndex[ nValueNo ];
 180     return ( nIndex != -1 ) ? pValues[ nIndex ] : aEmptyAny;
 181 }
 182
 183 bool MultiPropertySetHelper::hasProperty( sal_Int16 nValueNo )
 184 {
 185     assert(pSequenceIndex && "called hasProperty() without calling hasProperties()");
 186     assert(nValueNo < nLength);
 187
 188     return pSequenceIndex[ nValueNo ] != -1;
 189 }
 190
 191 #endif
 192
 193 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */