configmgr/source/registry/cfgregistrykey.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: cfgregistrykey.hxx,v $
  10  * $Revision: 1.9 $
  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
  31 #ifndef _CONFIGMGR_REGISTRY_CFGREGISTRYKEY_HXX_
  32 #define _CONFIGMGR_REGISTRY_CFGREGISTRYKEY_HXX_
  33
  34 #include <cppuhelper/implbase1.hxx>
  35 #include <com/sun/star/container/XNameAccess.hpp>
  36 #include <com/sun/star/container/XHierarchicalNameAccess.hpp>
  37 #include <com/sun/star/registry/XRegistryKey.hpp>
  38 #include <com/sun/star/beans/XPropertySetInfo.hpp>
  39
  40 //..........................................................................
  41 namespace configmgr
  42 {
  43 //..........................................................................
  44
  45 //==========================================================================
  46 //= OConfigurationRegistryKey
  47 //==========================================================================
  48 /** wraps the registry-like access to a single node of a configuration sub tree
  49 */
  50 class OConfigurationRegistryKey
  51         :public cppu::WeakImplHelper1< com::sun::star::registry::XRegistryKey >
  52 {
  53     sal_Bool            m_bReadOnly;            /// is the key readonly ?
  54
  55     ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameAccess >
  56                     m_xNode;            /// the config node object, if it is a container
  57
  58     ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameAccess >
  59                     m_xParentNode;              /// if the key is not the root, this is it's parent.
  60
  61     const ::rtl::OUString       m_sLocalName; /** the name of the element relative to the parent, which is
  62                                             m_xParentNode if that is present
  63                                         */
  64
  65     // TODO : the current concept does not recognize when config keys are disposed (e.g. when the registry is closed)
  66     //
  67     // Possible solutions:
  68     // 1. each registry key is a listener on the component containing its node
  69     //          may be is expensive ?.
  70     //
  71     // At the moment we ignore this restriction, but perhaps we can't do that forever ....
  72
  73 public:
  74     /// when used as ctor parameter, this indicates that the key wraps a config tree subtree root
  75     struct SubtreeRoot { };
  76
  77     /** builds an registry key which wraps the root of a configuration registry
  78     */
  79     OConfigurationRegistryKey(
  80              const ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameAccess >& _rxRootNode
  81             ,sal_Bool _bWriteable
  82             ,SubtreeRoot
  83         );
  84
  85     /** builds an registry key for a configuration node
  86         @param          _rxContainerNode        the node the key should represent
  87         @param          _bWriteable                     should the key be writeable ?
  88     */
  89     OConfigurationRegistryKey(
  90              const ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameAccess >& _rxNode
  91             ,sal_Bool _bWriteable
  92         );
  93
  94     /** builds an registry key for a configuration value container node.
  95         @param          _rCurrentValue  the current value of the node. Must be the same as _rxParentNode->getByName(_rRelativeName) would provide
  96         @param          _rxParentNode   the parent of the value node. Used for update access and for obtaining the initial value.
  97         @param          _rRelativeName  te relative name within the parent
  98         @param          _bWriteable             should the key be writeable ?
  99     */
 100     OConfigurationRegistryKey(
 101              ::com::sun::star::uno::Any _rCurrentValue
 102             ,const ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameAccess >& _rxParentNode
 103             ,const ::rtl::OUString& _rRelativeName
 104             ,sal_Bool _bWriteable
 105         );
 106
 107     // XRegistryKey
 108     virtual ::rtl::OUString SAL_CALL getKeyName() throw(::com::sun::star::uno::RuntimeException);
 109     virtual sal_Bool SAL_CALL isReadOnly(  ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 110     virtual sal_Bool SAL_CALL isValid(  ) throw(::com::sun::star::uno::RuntimeException);
 111     virtual ::com::sun::star::registry::RegistryKeyType SAL_CALL getKeyType( const ::rtl::OUString& rKeyName ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 112     virtual ::com::sun::star::registry::RegistryValueType SAL_CALL getValueType(  ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 113     virtual sal_Int32 SAL_CALL getLongValue(  ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::registry::InvalidValueException, ::com::sun::star::uno::RuntimeException);
 114     virtual void SAL_CALL setLongValue( sal_Int32 value ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 115     virtual ::com::sun::star::uno::Sequence< sal_Int32 > SAL_CALL getLongListValue(  ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::registry::InvalidValueException, ::com::sun::star::uno::RuntimeException);
 116     virtual void SAL_CALL setLongListValue( const ::com::sun::star::uno::Sequence< sal_Int32 >& seqValue ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 117     virtual ::rtl::OUString SAL_CALL getAsciiValue(  ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::registry::InvalidValueException, ::com::sun::star::uno::RuntimeException);
 118     virtual void SAL_CALL setAsciiValue( const ::rtl::OUString& value ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 119     virtual ::com::sun::star::uno::Sequence< ::rtl::OUString > SAL_CALL getAsciiListValue(  ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::registry::InvalidValueException, ::com::sun::star::uno::RuntimeException);
 120     virtual void SAL_CALL setAsciiListValue( const ::com::sun::star::uno::Sequence< ::rtl::OUString >& seqValue ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 121     virtual ::rtl::OUString SAL_CALL getStringValue(  ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::registry::InvalidValueException, ::com::sun::star::uno::RuntimeException);
 122     virtual void SAL_CALL setStringValue( const ::rtl::OUString& value ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 123     virtual ::com::sun::star::uno::Sequence< ::rtl::OUString > SAL_CALL getStringListValue(  ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::registry::InvalidValueException, ::com::sun::star::uno::RuntimeException);
 124     virtual void SAL_CALL setStringListValue( const ::com::sun::star::uno::Sequence< ::rtl::OUString >& seqValue ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 125     virtual ::com::sun::star::uno::Sequence< sal_Int8 > SAL_CALL getBinaryValue(  ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::registry::InvalidValueException, ::com::sun::star::uno::RuntimeException);
 126     virtual void SAL_CALL setBinaryValue( const ::com::sun::star::uno::Sequence< sal_Int8 >& value ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 127     virtual ::com::sun::star::uno::Reference< ::com::sun::star::registry::XRegistryKey > SAL_CALL openKey( const ::rtl::OUString& aKeyName ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 128     virtual ::com::sun::star::uno::Reference< ::com::sun::star::registry::XRegistryKey > SAL_CALL createKey( const ::rtl::OUString& aKeyName ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 129     virtual void SAL_CALL closeKey(  ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 130     virtual void SAL_CALL deleteKey( const ::rtl::OUString& rKeyName ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 131     virtual ::com::sun::star::uno::Sequence< ::com::sun::star::uno::Reference< ::com::sun::star::registry::XRegistryKey > > SAL_CALL openKeys(  ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 132     virtual ::com::sun::star::uno::Sequence< ::rtl::OUString > SAL_CALL getKeyNames(  ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 133     virtual sal_Bool SAL_CALL createLink( const ::rtl::OUString& aLinkName, const ::rtl::OUString& aLinkTarget ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 134     virtual void SAL_CALL deleteLink( const ::rtl::OUString& rLinkName ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 135     virtual ::rtl::OUString SAL_CALL getLinkTarget( const ::rtl::OUString& rLinkName ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 136     virtual ::rtl::OUString SAL_CALL getResolvedName( const ::rtl::OUString& aKeyName ) throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 137
 138 protected:
 139     /** specifies the kind of access to the key.
 140     */
 141     enum KEY_ACCESS_TYPE
 142     {
 143         KAT_META,                       /// access on a meta level, e.g. asking for the read-onyl flag
 144         KAT_VALUE,                      /// read access to the value the node represents
 145         KAT_VALUE_WRITE,        /// write access to the value the node represents
 146         KAT_CHILD                       /// access to one of the (grand-)children of the node
 147     };
 148
 149     ::com::sun::star::uno::Reference< ::com::sun::star::beans::XPropertySetInfo >
 150         implGetParentPropertyInfo()
 151             throw(::com::sun::star::uno::RuntimeException);
 152
 153     sal_Bool implIsReadOnly()
 154             throw(::com::sun::star::uno::RuntimeException);
 155
 156     sal_Bool implEnsureNode()
 157             throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 158
 159     ::com::sun::star::uno::Type implGetUnoType()
 160             throw(::com::sun::star::uno::RuntimeException);
 161
 162     sal_Bool implEnsureValue()
 163             throw(::com::sun::star::uno::RuntimeException);
 164
 165     sal_Bool implIsValid() throw ();
 166
 167     /** check if the registry key is valid
 168         @param          _eIntentedAccess        type of access which the caller wants to perform on the object
 169         @throws                         <type scope="com.sun.star.registry">InvalidRegistryException</type> if the key is invalid
 170     */
 171     void checkValid(KEY_ACCESS_TYPE _eIntentedAccess)
 172         throw (::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 173
 174     /** return an child element.
 175         @param          _rDescendantName        the name of the descendant to open. May have a depth of more than 1, if
 176                                         the node container support XHierarchicalNameAccess
 177         @return                         the requested element. The caller can assume that the returned
 178                             <type scope="com.sun.star.uno">Any</type> always contains an object, all other cases are
 179                             handled with exceptions
 180         @throws                         <type scope="com.sun.star.registry">InvalidRegistryException</type> if the key is invalid,
 181                             the element refered by _rName does not exist, the configuration node threw an exception, or
 182                             the name has a depth of more than one and the config node does not support this.
 183     */
 184     ::com::sun::star::uno::Any
 185         implGetDescendant(const ::rtl::OUString& _rDescendantName)
 186             throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 187
 188     /** write the given value into the configuration node the object represents.
 189         @throws                         <type scope="com.sun.star.registry">InvalidRegistryException</type> if the key is invalid,
 190                             not opened for write access or the configurations parent is not able to provide a value access
 191         @throws                         <type scope="com.sun.star.uno">RuntimeException</type> if a fatal runtime error occurs
 192     */
 193     void implSetValue(const ::com::sun::star::uno::Any& _rValue)
 194             throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 195
 196     ::com::sun::star::uno::Any implGetValue()
 197             throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 198
 199     /** open the sub key (depth 1 or more) determined by the given name
 200         @param          _rKeyName               the name of the descendant node
 201         @return                         a XRegistryKey wrapper for the requested configuration node
 202         @throws                         <type scope="com.sun.star.registry">InvalidRegistryException</type> if the key is invalid,
 203                             the element refered by _rName does not exist, the configuration node threw an exception, or
 204                             the name has a depth of more than one and the config node does not support this.
 205     */
 206     ::com::sun::star::uno::Reference< ::com::sun::star::registry::XRegistryKey >
 207         implGetKey( const ::rtl::OUString& _rKeyName )
 208             throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 209
 210     /** check the given (relative) key name syntactically.
 211
 212         <p>In particular, this means that no checks are made if a node with the given name exists or something like
 213         that ...<br/>
 214         In addition, the given name will be normalized. Basically, this means that it does not contain trailing slashes.
 215         </p>
 216         @returns
 217             <TRUE/>     if the name is a valid relative path
 218             <FALSE/>    if the name is a local name only
 219         @throws InvalidRegistryException
 220             if the name is invalid or not relative (i.e. if it starts with an slash)
 221     */
 222     bool checkRelativeKeyName(::rtl::OUString& _rKeyName)
 223             throw(::com::sun::star::registry::InvalidRegistryException, ::com::sun::star::uno::RuntimeException);
 224
 225     /** get a default value for a value of a given type
 226
 227         <p>Creates an Any with an empty or zero value of the given type.</p>
 228
 229         @param  _rType                  the type of the element to create
 230         @return
 231             an <type scope="com::sun::star::uno">Any</type> representing a default for the node value type. If the
 232             return value is still VOID, the node has a nullable type (e.g. any) or is of unsupported type
 233
 234     */
 235     ::com::sun::star::uno::Any
 236         implCreateDefaultElement(::com::sun::star::uno::Type const& _rType)
 237             throw(::com::sun::star::uno::RuntimeException);
 238 };
 239
 240
 241 //..........................................................................
 242 }       // namespace configmgr
 243 //..........................................................................
 244
 245 #endif // _CONFIGMGR_REGISTRY_CFGREGISTRYKEY_HXX_
 246
 247