1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23#ifndef __com_sun_star_ucb_HierarchyDataSource_idl__
24#define __com_sun_star_ucb_HierarchyDataSource_idl__
25
26#ifndef __com_sun_star_lang_XMultiServiceFactory_idl__
27#include <com/sun/star/lang/XMultiServiceFactory.idl>
28#endif
29#ifndef __com_sun_star_lang_XComponent_idl__
30#include <com/sun/star/lang/XComponent.idl>
31#endif
32
33//=============================================================================
34
35module com { module sun { module star { module ucb {
36
37//=============================================================================
38/** manages one or more complete sets of hierarchy data and serves as a factory
39    for objects that provide access to a subset of the data.
40
41    <p><b>Note:</b> This is an abstract service. This means, that there should
42    never be implementations that can be instanciated using the service name
43    <code>com.sun.star.ucb.HierarchyDataSource</code>. Each implementation must
44    provide its own service name that can be used to create instances of that
45    service implementation. Important for those service specifications is also
46    to specify which of the optional parts are supported by the implementation.
47*/
48published service HierarchyDataSource
49{
50	//-------------------------------------------------------------------------
51    /** allows creating access objects for specific views such as subsets and
52        fragments of the hierrachy data.
53
54        <p>The parameter <var>aServiceSpecifier</var> passed to
55        <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments</member>
56        supports at least the service specifier
57        <code>"com.sun.star.ucb.HierarchyDataReadAccess"</code>, which will
58        create a <b>read-only view</b> to the data. The object that is created
59        implements the service <type>HierarchyDataReadAccess</type>.
60
61        <p><b>Optionally</b> the factory may support <b>writable views</b>. A
62        writable view is requested by passing the service specifier
63        <code>"com.sun.star.ucb.HierarchyDataReadWriteAccess"</code> to
64        <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments</member>
65        The object that is created implements the service
66        <type>HierarchyDataReadWriteAccess</type>.
67
68        <p>The arguments passed to
69        <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments</member>
70        in parameter <var>aArguments</var> specify the view of the data that
71        should be created. That is, they determine the subset of elements that
72        can be accessed starting from the returned object. Each element of the
73        argument sequence should be a
74        <type scope="com::sun::star::beans">PropertyValue</type>, so that the
75        parameters can be identified by name rather than by position.
76
77        <p>With both of the standard service specifiers above, an implementation
78        must accept a property named <code>nodepath</code> of type
79        <atom>string</atom>. This property must contain the absolute path to an
80        element of the data. The view that is selected consists of the named
81        element and all its decendants. A path consists of segments that are
82        separated by a single slash ('/'). There is neither a leading nor a
83        trailing slash allowed. The <b>root</b> of the hierarchy data always
84        has an empty path. Refer to <type>HierarchyDataReadAccess</type> for
85        more informtion on hierarchical names.
86
87        <p>Other arguments can be used to control the behavior of the view.
88        These are different for different implementations. Whether and how they
89        are used may also depend on the configuration store and configuration
90        that were selected when the provider was created.
91
92        <p>An implementation must ignore unknown arguments.
93
94        <p>The implementation of
95        <member scope="com::sun::star::lang">XMultiServiceFactory::createInstance</member>
96        must behave exactly as if
97        <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments</member>
98        were called passing one single property named <code>nodepath</code>
99        where the property value is an empty string. Thus it always creates a
100        view to the root of the hierarchy data.
101	 */
102    interface com::sun::star::lang::XMultiServiceFactory;
103
104	//-------------------------------------------------------------------------
105    /** allows controlling or observing the lifetime of the hierarchy data
106        source and its views.
107	 */
108    interface com::sun::star::lang::XComponent;
109};
110
111//=============================================================================
112
113}; }; }; };
114
115#endif
116