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