1/*************************************************************************
2 *
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * Copyright 2000, 2010 Oracle and/or its affiliates.
6 *
7 * OpenOffice.org - a multi-platform office productivity suite
8 *
9 * This file is part of OpenOffice.org.
10 *
11 * OpenOffice.org is free software: you can redistribute it and/or modify
12 * it under the terms of the GNU Lesser General Public License version 3
13 * only, as published by the Free Software Foundation.
14 *
15 * OpenOffice.org is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18 * GNU Lesser General Public License version 3 for more details
19 * (a copy is included in the LICENSE file that accompanied this code).
20 *
21 * You should have received a copy of the GNU Lesser General Public License
22 * version 3 along with OpenOffice.org.  If not, see
23 * <http://www.openoffice.org/license.html>
24 * for a copy of the LGPLv3 License.
25 *
26 ************************************************************************/
27#ifndef __com_sun_star_ucb_HierarchyDataSource_idl__
28#define __com_sun_star_ucb_HierarchyDataSource_idl__
29
30#ifndef __com_sun_star_lang_XMultiServiceFactory_idl__
31#include <com/sun/star/lang/XMultiServiceFactory.idl>
32#endif
33#ifndef __com_sun_star_lang_XComponent_idl__
34#include <com/sun/star/lang/XComponent.idl>
35#endif
36
37//=============================================================================
38
39module com { module sun { module star { module ucb {
40
41//=============================================================================
42/** manages one or more complete sets of hierarchy data and serves as a factory
43    for objects that provide access to a subset of the data.
44
45    <p><b>Note:</b> This is an abstract service. This means, that there should
46    never be implementations that can be instanciated using the service name
47    <code>com.sun.star.ucb.HierarchyDataSource</code>. Each implementation must
48    provide its own service name that can be used to create instances of that
49    service implementation. Important for those service specifications is also
50    to specify which of the optional parts are supported by the implementation.
51*/
52published service HierarchyDataSource
53{
54	//-------------------------------------------------------------------------
55    /** allows creating access objects for specific views such as subsets and
56        fragments of the hierrachy data.
57
58        <p>The parameter <var>aServiceSpecifier</var> passed to
59        <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments</member>
60        supports at least the service specifier
61        <code>"com.sun.star.ucb.HierarchyDataReadAccess"</code>, which will
62        create a <b>read-only view</b> to the data. The object that is created
63        implements the service <type>HierarchyDataReadAccess</type>.
64
65        <p><b>Optionally</b> the factory may support <b>writable views</b>. A
66        writable view is requested by passing the service specifier
67        <code>"com.sun.star.ucb.HierarchyDataReadWriteAccess"</code> to
68        <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments</member>
69        The object that is created implements the service
70        <type>HierarchyDataReadWriteAccess</type>.
71
72        <p>The arguments passed to
73        <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments</member>
74        in parameter <var>aArguments</var> specify the view of the data that
75        should be created. That is, they determine the subset of elements that
76        can be accessed starting from the returned object. Each element of the
77        argument sequence should be a
78        <type scope="com::sun::star::beans">PropertyValue</type>, so that the
79        parameters can be identified by name rather than by position.
80
81        <p>With both of the standard service specifiers above, an implementation
82        must accept a property named <code>nodepath</code> of type
83        <atom>string</atom>. This property must contain the absolute path to an
84        element of the data. The view that is selected consists of the named
85        element and all its decendants. A path consists of segments that are
86        separated by a single slash ('/'). There is neither a leading nor a
87        trailing slash allowed. The <b>root</b> of the hierarchy data always
88        has an empty path. Refer to <type>HierarchyDataReadAccess</type> for
89        more informtion on hierarchical names.
90
91        <p>Other arguments can be used to control the behavior of the view.
92        These are different for different implementations. Whether and how they
93        are used may also depend on the configuration store and configuration
94        that were selected when the provider was created.
95
96        <p>An implementation must ignore unknown arguments.
97
98        <p>The implementation of
99        <member scope="com::sun::star::lang">XMultiServiceFactory::createInstance</member>
100        must behave exactly as if
101        <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments</member>
102        were called passing one single property named <code>nodepath</code>
103        where the property value is an empty string. Thus it always creates a
104        view to the root of the hierarchy data.
105	 */
106    interface com::sun::star::lang::XMultiServiceFactory;
107
108	//-------------------------------------------------------------------------
109    /** allows controlling or observing the lifetime of the hierarchy data
110        source and its views.
111	 */
112    interface com::sun::star::lang::XComponent;
113};
114
115//=============================================================================
116
117}; }; }; };
118
119#endif
120