/**************************************************************
 * 
 * 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 __com_sun_star_ucb_HierarchyDataSource_idl__
#define __com_sun_star_ucb_HierarchyDataSource_idl__

#ifndef __com_sun_star_lang_XMultiServiceFactory_idl__
#include <com/sun/star/lang/XMultiServiceFactory.idl>
#endif
#ifndef __com_sun_star_lang_XComponent_idl__
#include <com/sun/star/lang/XComponent.idl>
#endif

//=============================================================================

module com { module sun { module star { module ucb {

//=============================================================================
/** manages one or more complete sets of hierarchy data and serves as a factory
    for objects that provide access to a subset of the data.

    <p><b>Note:</b> This is an abstract service. This means, that there should
    never be implementations that can be instanciated using the service name
    <code>com.sun.star.ucb.HierarchyDataSource</code>. Each implementation must
    provide its own service name that can be used to create instances of that
    service implementation. Important for those service specifications is also
    to specify which of the optional parts are supported by the implementation.
*/
published service HierarchyDataSource
{
	//-------------------------------------------------------------------------
    /** allows creating access objects for specific views such as subsets and
        fragments of the hierrachy data.

        <p>The parameter <var>aServiceSpecifier</var> passed to
        <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments</member>
        supports at least the service specifier
        <code>"com.sun.star.ucb.HierarchyDataReadAccess"</code>, which will
        create a <b>read-only view</b> to the data. The object that is created
        implements the service <type>HierarchyDataReadAccess</type>.

        <p><b>Optionally</b> the factory may support <b>writable views</b>. A
        writable view is requested by passing the service specifier
        <code>"com.sun.star.ucb.HierarchyDataReadWriteAccess"</code> to
        <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments</member>
        The object that is created implements the service
        <type>HierarchyDataReadWriteAccess</type>.

        <p>The arguments passed to
        <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments</member>
        in parameter <var>aArguments</var> specify the view of the data that
        should be created. That is, they determine the subset of elements that
        can be accessed starting from the returned object. Each element of the
        argument sequence should be a
        <type scope="com::sun::star::beans">PropertyValue</type>, so that the
        parameters can be identified by name rather than by position.

        <p>With both of the standard service specifiers above, an implementation
        must accept a property named <code>nodepath</code> of type
        <atom>string</atom>. This property must contain the absolute path to an
        element of the data. The view that is selected consists of the named
        element and all its decendants. A path consists of segments that are
        separated by a single slash ('/'). There is neither a leading nor a
        trailing slash allowed. The <b>root</b> of the hierarchy data always
        has an empty path. Refer to <type>HierarchyDataReadAccess</type> for
        more informtion on hierarchical names.

        <p>Other arguments can be used to control the behavior of the view.
        These are different for different implementations. Whether and how they
        are used may also depend on the configuration store and configuration
        that were selected when the provider was created.

        <p>An implementation must ignore unknown arguments.

        <p>The implementation of
        <member scope="com::sun::star::lang">XMultiServiceFactory::createInstance</member>
        must behave exactly as if
        <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments</member>
        were called passing one single property named <code>nodepath</code>
        where the property value is an empty string. Thus it always creates a
        view to the root of the hierarchy data.
	 */
    interface com::sun::star::lang::XMultiServiceFactory;

	//-------------------------------------------------------------------------
    /** allows controlling or observing the lifetime of the hierarchy data
        source and its views.
	 */
    interface com::sun::star::lang::XComponent;
};

//=============================================================================

}; }; }; };

#endif