xref: /aoo41x/main/unotools/inc/unotools/confignode.hxx (revision bae3752e)

/**************************************************************
 *
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 *
 *************************************************************/


#ifndef _UNOTOOLS_CONFIGNODE_HXX_
#define _UNOTOOLS_CONFIGNODE_HXX_

#include "unotools/unotoolsdllapi.h"
#include <com/sun/star/container/XHierarchicalNameAccess.hpp>
#include <com/sun/star/container/XNameAccess.hpp>
#include <com/sun/star/container/XNameContainer.hpp>
#include <com/sun/star/lang/XMultiServiceFactory.hpp>
#include <com/sun/star/util/XChangesBatch.hpp>
#include <unotools/eventlisteneradapter.hxx>

namespace comphelper
{
    class ComponentContext;
}

//........................................................................
namespace utl
{
//........................................................................

	//========================================================================
	//= OConfigurationNode
	//========================================================================
	class OConfigurationTreeRoot;
	/** a small wrapper around a configuration node.<p/>
		Nodes in the terminology used herein are <em>inner</em> nodes of a configuration
		tree, which means <em>no leafs</em>.
	*/
	class UNOTOOLS_DLLPUBLIC OConfigurationNode : public ::utl::OEventListenerAdapter
	{
	private:
		::com::sun::star::uno::Reference< ::com::sun::star::container::XHierarchicalNameAccess >
					m_xHierarchyAccess;		/// accessing children grandchildren (mandatory interface of our UNO object)
		::com::sun::star::uno::Reference< ::com::sun::star::container::XNameAccess >
					m_xDirectAccess;		/// accessing children  (mandatory interface of our UNO object)
		::com::sun::star::uno::Reference< ::com::sun::star::container::XNameReplace >
					m_xReplaceAccess;		/// replacing child values
		::com::sun::star::uno::Reference< ::com::sun::star::container::XNameContainer >
					m_xContainerAccess;		/// modifying set nodes  (optional interface of our UNO object)
		::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >
					m_xDummy;
		sal_Bool	m_bEscapeNames;			/// escape names before accessing children ?

		::rtl::OUString
					m_sCompletePath;

		OConfigurationNode  insertNode(const ::rtl::OUString& _rName,const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _xNode) const throw();

    protected:
		/// constructs a node object with an interface representing a node
		OConfigurationNode(
			const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxNode
        );

        const ::com::sun::star::uno::Reference< ::com::sun::star::container::XNameAccess >&
            getUNONode() const { return m_xDirectAccess; }

	public:
		/// constructs an empty and invalid node object
		OConfigurationNode() :m_bEscapeNames(sal_False) { }
		/// copy ctor
		OConfigurationNode(const OConfigurationNode& _rSource);

		/// assigment
		const OConfigurationNode& operator=(const OConfigurationNode& _rSource);

		/// dtor
		~OConfigurationNode() {}

        /// returns the local name of the node
        ::rtl::OUString     getLocalName() const;

        /// returns the fully qualified path of the node
        ::rtl::OUString     getNodePath() const;

		/** open a sub node
			@param		_rPath		access path of the to-be-opened sub node. May be a hierarchical path.
		*/
		OConfigurationNode	openNode(const ::rtl::OUString& _rPath) const throw();

        OConfigurationNode	openNode( const sal_Char* _pAsciiPath ) const
        {
            return openNode( ::rtl::OUString::createFromAscii( _pAsciiPath ) );
        }

		/** create a new child node

			If the object represents a set node, this method may be used to create a new child. For non-set-nodes, the
			method will fail.<br/>
			Unless the respective operations on the pure configuration API, the to-be-created node immediately
			becomes a part of it's hierarchy, no explicit insertion is necessary.
			@param		_rName		name for the new child. Must be level-1-depth.
		*/
		OConfigurationNode	createNode(const ::rtl::OUString& _rName) const throw();

		OConfigurationNode	createNode( const sal_Char* _pAsciiName ) const
        {
            return createNode( ::rtl::OUString::createFromAscii( _pAsciiName ) );
        }

        /** appends a node under a new name

			If the object represents a set node, this method may be used to create a new child. For non-set-nodes, the
			method will fail.<br/>
			Unless the respective operations on the pure configuration API, the to-be-created node immediately
			becomes a part of it's hierarchy, no explicit insertion is necessary.
			@param		_rName		name for the new child. Must be level-1-depth.
			@param		_aNewNode	the node which should be appended
		*/
		OConfigurationNode  appendNode(const ::rtl::OUString& _rName,const OConfigurationNode& _aNewNode) const throw();

		OConfigurationNode  appendNode( const sal_Char* _pAsciiName, const OConfigurationNode& _aNewNode ) const
        {
            return appendNode( ::rtl::OUString::createFromAscii( _pAsciiName ), _aNewNode );
        }

		/** remove an existent child nod

            If the object represents a set node, this method may be used to delete an existent child. For non-set-nodes,
			the method will fail.
		*/
		sal_Bool			removeNode(const ::rtl::OUString& _rName) const throw();

		sal_Bool			removeNode( const sal_Char* _pAsciiName ) const
        {
            return removeNode( ::rtl::OUString::createFromAscii( _pAsciiName ) );
        }

		/** retrieves the content of a descendant

            the returned value may contain anything from an interface (if <arg>_rPath</arg> refers to inner node of
			the configuration tree) to any explicit value (e.g. string, integer) or even void.<br/>
			Unfortunately, this implies that if a void value is returned, you won't have a clue if this means
			"the path does not exist" (besides the assertion made :), or if the value is really void.
		*/
		::com::sun::star::uno::Any
							getNodeValue(const ::rtl::OUString& _rPath) const throw();

        ::com::sun::star::uno::Any
                            getNodeValue( const sal_Char* _pAsciiPath ) const
        {
            return getNodeValue( ::rtl::OUString::createFromAscii( _pAsciiPath ) );
        }

		/** write a node value<p/>
			The value given is written into the node specified by the given relative path.<br/>
			In opposite to <method>getNodeValue</method>, _rName must refer to a leaf in the configuration tree, not an inner
			node.
			@return		sal_True if and only if the write was successfull.
		*/
		sal_Bool			setNodeValue(const ::rtl::OUString& _rPath, const ::com::sun::star::uno::Any& _rValue) const throw();

		sal_Bool			setNodeValue( const sal_Char* _pAsciiPath, const ::com::sun::star::uno::Any& _rValue ) const
        {
            return setNodeValue( ::rtl::OUString::createFromAscii( _pAsciiPath ), _rValue );
        }

		/// return the names of the existing children
		::com::sun::star::uno::Sequence< ::rtl::OUString >
							getNodeNames() const throw();

		/** enables or disables name escaping when accessing direct children<p/>
			Escaping is disabled by default, usually you enable it for set nodes (e.g. with calling setEscape(isSetNode)).
			Once escaping is enabled, you should not access indirect children (e.g. openNode("child/grandchild"), 'cause
			escaping for such names may not be supported by the underlying API objects.
			@see getEscape
		*/
		void		setEscape(sal_Bool _bEnable = sal_True);
		/** get the flag specifying the current escape behaviour
			@see setEscape
		*/
		sal_Bool	getEscape() const { return m_bEscapeNames; }

		/// invalidate the object
		virtual void clear() throw();

	    // -----------------------
	    // meta informations about the node

        /// checks whether or not the object represents a set node.
		sal_Bool isSetNode() const;

        /// checks whether or not a direct child with a given name exists
		sal_Bool hasByName(const ::rtl::OUString& _rName) const throw();
        sal_Bool hasByName( const sal_Char* _pAsciiName ) const { return hasByName( ::rtl::OUString::createFromAscii( _pAsciiName ) ); }

        /// checks whether or not a descendent (no matter if direct or indirect) with the given name exists
		sal_Bool hasByHierarchicalName( const ::rtl::OUString& _rName ) const throw();
        sal_Bool hasByHierarchicalName( const sal_Char* _pAsciiName ) const { return hasByHierarchicalName( ::rtl::OUString::createFromAscii( _pAsciiName ) ); }

        /// check if the objects represents a valid configuration node
		sal_Bool isValid() const { return m_xHierarchyAccess.is(); }

        /// check whether the object is read-only of updatable
		sal_Bool isReadonly() const { return !m_xReplaceAccess.is(); }

	protected:
		// OEventListenerAdapter
		virtual void _disposing( const ::com::sun::star::lang::EventObject& _rSource );

	protected:
		enum NAMEORIGIN
		{
			NO_CONFIGURATION,		/// the name came from a configuration node
			NO_CALLER				/// the name came from a client of this class
		};
		::rtl::OUString normalizeName(const ::rtl::OUString& _rName, NAMEORIGIN _eOrigin) const;
	};

	//========================================================================
	//= OConfigurationTreeRoot
	//========================================================================
	/** a specialized version of a OConfigurationNode, representing the root
		of a configuration sub tree<p/>
		Only this class is able to commit any changes made any any OConfigurationNode
		objects.
	*/
	class UNOTOOLS_DLLPUBLIC OConfigurationTreeRoot : public OConfigurationNode
	{
		::com::sun::star::uno::Reference< ::com::sun::star::util::XChangesBatch >
								m_xCommitter;
	protected:
		/** ctor<p/>
		*/
		OConfigurationTreeRoot(
			const ::com::sun::star::uno::Reference< ::com::sun::star::util::XChangesBatch >& _rxRootNode
        );

		/** ctor for a readonly node
		*/
		OConfigurationTreeRoot(
			const ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >& _rxRootNode
        );

	public:
		/// modes to use when creating a top-level node object
		enum CREATION_MODE
		{
            /// open the node (i.e. sub tree) for read access only
            CM_READONLY,
            /// open the node (i.e. sub tree) for read and write access, fall back to read-only if write access is not possible
            CM_UPDATABLE
		};

	public:
		/** default ctor<p/>
			The object constructed here is invalid (i.e. <method>isValid</method> will return sal_False).
		*/
		OConfigurationTreeRoot() :OConfigurationNode() { }

        /** creates a configuration tree for the given path in the given mode
        */
        OConfigurationTreeRoot(
            const ::comphelper::ComponentContext& i_rContext,
            const sal_Char* i_pAsciiNodePath,
            const bool i_bUpdatable
        );

        /** creates a configuration tree for the given path in the given mode
        */
        OConfigurationTreeRoot(
            const ::comphelper::ComponentContext& i_rContext,
            const ::rtl::OUString& i_rNodePath,
            const bool i_bUpdatable
        );

		/// copy ctor
		OConfigurationTreeRoot(const OConfigurationTreeRoot& _rSource)
			:OConfigurationNode(_rSource), m_xCommitter(_rSource.m_xCommitter) { }

		/** open a new top-level configuration node

			opens a new node which is the root if an own configuration sub tree. This is what "top level" means: The
			node does not have a parent. It does not mean that the node represents a module tree (like org.openoffice.Office.Writer
			or such).<br/>
			In opposite to <method>createWithServiceFactory</method>, createWithProvider expects a configuration provider
			to work with.

            @param		_rxConfProvider	configuration provider to use when retrieving the node.
			@param		_rPath			path to the node the object should represent
			@param		_nDepth			depth for node retrieval
			@param		_eMode			specifies which privileges should be applied when retrieving the node

            @see	createWithServiceFactory
		*/
		static OConfigurationTreeRoot createWithProvider(
                const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >& _rxConfProvider,
			    const ::rtl::OUString& _rPath,
                sal_Int32 _nDepth = -1,
                CREATION_MODE _eMode = CM_UPDATABLE,
                sal_Bool _bLazyWrite = sal_True
            );

		/** open a new top-level configuration node<p/>
			opens a new node which is the root if an own configuration sub tree. This is what "top level" means: The
			node does not have a parent. It does not mean that the node represents a module tree (like org.openoffice.Office.Writer
			or such).<br/>
			In opposite to <method>createWithProvider</method>, createWithProvider expects a service factory. This factory
			is used to create a configuration provider, and this provider is used to retrieve the node
			@see	createWithProvider
			@param		_rxORB			service factory to use to create the configuration provider.
			@param		_rPath			path to the node the object should represent
			@param		_nDepth			depth for node retrieval
			@param		_eMode			specifies which privileges should be applied when retrieving the node
		*/
		static OConfigurationTreeRoot createWithServiceFactory(const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >& _rxORB,
			const ::rtl::OUString& _rPath, sal_Int32 _nDepth = -1, CREATION_MODE _eMode = CM_UPDATABLE, sal_Bool _bLazyWrite = sal_True);

		/** tolerant version of the <member>createWithServiceFactory</member>

			<p>No assertions are thrown in case of an failure to initialize the configuration service, but once
			the configuration could be initialized, errors in the creation of the specific node (e.g. because the
			given node path does not exist) are still asserted.</p>
		*/
		static OConfigurationTreeRoot tryCreateWithServiceFactory( const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory >& _rxORB,
			const ::rtl::OUString& _rPath, sal_Int32 _nDepth = -1, CREATION_MODE _eMode = CM_UPDATABLE, sal_Bool _bLazyWrite = sal_True );

		/** commit all changes made on the subtree the object is the root for<p/>
			All changes made on any <type>OConfigurationNode</type> object retrieved (maybe indirect) from this root
			object are committed when calling this method.
			@return		sal_True if and only if the commit was successfull
		*/
		sal_Bool commit() const throw();

		/// invalidate the object
		virtual void clear() throw();
	};

//........................................................................
}	// namespace utl
//........................................................................

#endif // _UNOTOOLS_CONFIGNODE_HXX_