offapi/com/sun/star/ucb/HierarchyDataSource.idl

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