offapi/com/sun/star/ucb/HierarchyDataReadAccess.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: HierarchyDataReadAccess.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_HierarchyDataReadAccess_idl__
  31 #define __com_sun_star_ucb_HierarchyDataReadAccess_idl__
  32
  33 #ifndef __com_sun_star_container_XNameAccess_idl__
  34 #include <com/sun/star/container/XNameAccess.idl>
  35 #endif
  36 #ifndef __com_sun_star_container_XHierarchicalNameAccess_idl__
  37 #include <com/sun/star/container/XHierarchicalNameAccess.idl>
  38 #endif
  39 #ifndef __com_sun_star_util_XChangesNotifier_idl__
  40 #include <com/sun/star/util/XChangesNotifier.idl>
  41 #endif
  42 #ifndef __com_sun_star_lang_XComponent_idl__
  43 #include <com/sun/star/lang/XComponent.idl>
  44 #endif
  45
  46 //=============================================================================
  47
  48 module com { module sun { module star { module ucb {
  49
  50 //=============================================================================
  51 /** provides read access to a fragment of the hierarchy data.
  52
  53     <p>A hierarchy data source provides access to a tree of hierarchy data
  54     nodes. Each hierarchy data node, except the root node, has a parent that
  55     is a hierarchy data node too. A hierarchy data node has a name.
  56
  57     <p>Each hierarchy data node has three data members:
  58
  59     <ul>
  60     <li>"Title", which is of type <atom>string</atom>. It contains a title
  61     for the node. This value must not be empty.
  62     <li>"TargetURL", which is of type <atom>string</atom></li> It may contain
  63     any URL, which will be treated as the target of a hierarchy link.
  64     <li>"Children", which is of type <type>HierarchyDataReadAccess</type> or
  65     of type <type>HierarchyDataReadWriteAccess</type></li>, depending on the
  66     type of the node. This member provides access to the children of a node.
  67     </ul>
  68 */
  69 published service HierarchyDataReadAccess
  70 {
  71     //-------------------------------------------------------------------------
  72     /** gives access to the data members of a hierarchy data node.
  73
  74         <p>Examples:
  75         <ul>
  76         <li><code>getByName( "Title" )</code> will return an <atom>any</atom>
  77         containing a string containing the title of the node.
  78         </li>
  79         <li><code>getByName( "Children" )</code> will return an <atom>any</atom>
  80         containing an implementation of service
  81         <type>HierarchyDataReadAccess</type>, if it was called on a read-only
  82         node. It will return an implementation of service
  83         <type>HierarchyDataReadWriteAccess</type> if it was called on a
  84         writable node.
  85         </li>
  86         </ul>
  87      */
  88     interface com::sun::star::container::XNameAccess;
  89
  90     //-------------------------------------------------------------------------
  91     /** gives access to the data members of a hierarchy data node as well
  92         as to any child nodes or to the data members of child nodes using a
  93         hierarchical name.
  94
  95         <p>A hierarchical name consists of segments that are separated by a
  96         single slash ('/'). There is neither a leading nor a trailing slash
  97         allowed.
  98
  99         <ul>
 100         <li>
 101         path = segment ( '/' segement )*
 102         </li>
 103         <li>
 104         segment = '[' quoted-string ']'
 105         </li>
 106         <li>
 107         quoted-string = "'" escaped-string "'"
 108         </li>
 109         <li>
 110         escaped-string = escaped accoding to XML attribute naming conventions
 111         </li>
 112         </ul>
 113
 114         <p>Examples:
 115         <ul>
 116         <li>
 117         <code>getByHierarchicalName( "Title" )</code> will return an
 118         <atom>any</atom> containing a string containing the title of the node
 119         itself.
 120         </li>
 121         <li>
 122         <code>getByHierarchicalName( "Children/['subnode1']" )</code> will give
 123         access to the child node named "subnode1" of the node. It will return
 124         an <atom>any</atom> containing an implementation of service
 125         <type>HierarchyDataReadAccess</type>, if it was called on a read-only
 126         node. It will return an implementation of service
 127         <type>HierarchyDataReadWriteAccess</type> if it was called on a
 128         writable node.
 129         </li>
 130         <li>
 131         <code>getByHierarchicalName( "Children/['subnode2']/TargetURL" )</code>
 132         will give direct access to the "TargetURL" data member of the child node
 133         named "subnode2" of the node. It will return an <atom>any</atom>
 134         containing a <atom>string</atom> containing the target URL of the node.
 135         </li>
 136         <li>
 137         <code>getByHierarchicalName( "Children/['subnode3']/Children" )</code>
 138         will give direct access to the "Children" data member of the child node
 139         named "subnode3" of the node. It will return an <atom>any</atom>
 140         conntaining an implementation of service
 141         <type>HierarchyDataReadAccess</type>, if it was called on a read-only
 142         node. It will return an implementation of service
 143         <type>HierarchyDataReadWriteAccess</type> if it was called on a
 144         writable node.
 145         </li>
 146         </ul>
 147      */
 148     interface com::sun::star::container::XHierarchicalNameAccess;
 149
 150     //-------------------------------------------------------------------------
 151     /** allows registering listeners that observe the hierarchy data source.
 152
 153         <p>A client can register an
 154         <type scope="com::sun::star::util">XChangesListener</type>, which will
 155         receive notifications for any changes within the hierarchy (fragment)
 156         this object represents.
 157
 158         <p>An implementation should collect as many changes as possible into a
 159         single <type scope="com::sun::star::util">ChangesEvent</type>.
 160     */
 161     interface com::sun::star::util::XChangesNotifier;
 162
 163     //-------------------------------------------------------------------------
 164     /** allows controlling or observing the lifetime of the hierarchy data
 165         access object.
 166      */
 167     interface com::sun::star::lang::XComponent;
 168 };
 169
 170 //=============================================================================
 171
 172 }; }; }; };
 173
 174 #endif