rdf/base/idl/nsIRDFDataSource.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is mozilla.org code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *   Jan Varga <varga@ku.sk>
  24  *
  25  * Alternatively, the contents of this file may be used under the terms of
  26  * either of the GNU General Public License Version 2 or later (the "GPL"),
  27  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  28  * in which case the provisions of the GPL or the LGPL are applicable instead
  29  * of those above. If you wish to allow use of your version of this file only
  30  * under the terms of either the GPL or the LGPL, and not to allow others to
  31  * use your version of this file under the terms of the MPL, indicate your
  32  * decision by deleting the provisions above and replace them with the notice
  33  * and other provisions required by the GPL or the LGPL. If you do not delete
  34  * the provisions above, a recipient may use your version of this file under
  35  * the terms of any one of the MPL, the GPL or the LGPL.
  36  *
  37  * ***** END LICENSE BLOCK ***** */
  38
  39 #include "nsISupports.idl"
  40 #include "nsISupportsArray.idl"
  41 #include "nsIRDFResource.idl"
  42 #include "nsIRDFNode.idl"
  43 #include "nsISimpleEnumerator.idl"
  44 #include "nsIRDFObserver.idl"
  45
  46 %{C++
  47 #include "nsISupportsArray.h"
  48 %}
  49
  50 [scriptable, uuid(0F78DA58-8321-11d2-8EAC-00805F29F370)]
  51 interface nsIRDFDataSource : nsISupports
  52 {
  53     /** The "URI" of the data source. This used by the RDF service's
  54      * |GetDataSource()| method to cache datasources.
  55      */
  56     readonly attribute string URI;
  57
  58     /** Find an RDF resource that points to a given node over the
  59      * specified arc & truth value
  60      *
  61      * @return NS_RDF_NO_VALUE if there is no source that leads
  62      * to the target with the specified property.
  63      */
  64     nsIRDFResource GetSource(in nsIRDFResource aProperty,
  65                              in nsIRDFNode     aTarget,
  66                              in boolean        aTruthValue);
  67
  68     /**
  69      * Find all RDF resources that point to a given node over the
  70      * specified arc & truth value
  71      *
  72      * @return NS_OK unless a catastrophic error occurs. If the
  73      * method returns NS_OK, you may assume that nsISimpleEnumerator points
  74      * to a valid (but possibly empty) cursor.
  75      */
  76     nsISimpleEnumerator GetSources(in nsIRDFResource aProperty,
  77                                    in nsIRDFNode     aTarget,
  78                                    in boolean        aTruthValue);
  79
  80     /**
  81      * Find a child of that is related to the source by the given arc
  82      * arc and truth value
  83      *
  84      * @return NS_RDF_NO_VALUE if there is no target accessible from the
  85      * source via the specified property.
  86      */
  87     nsIRDFNode GetTarget(in nsIRDFResource aSource,
  88                          in nsIRDFResource aProperty,
  89                          in boolean        aTruthValue);
  90
  91     /**
  92      * Find all children of that are related to the source by the given arc
  93      * arc and truth value.
  94      *
  95      * @return NS_OK unless a catastrophic error occurs. If the
  96      * method returns NS_OK, you may assume that nsISimpleEnumerator points
  97      * to a valid (but possibly empty) cursor.
  98      */
  99     nsISimpleEnumerator GetTargets(in nsIRDFResource aSource,
 100                                    in nsIRDFResource aProperty,
 101                                    in boolean aTruthValue);
 102
 103     /**
 104      * Add an assertion to the graph.
 105      */
 106     void Assert(in nsIRDFResource aSource,
 107                 in nsIRDFResource aProperty,
 108                 in nsIRDFNode     aTarget,
 109                 in boolean        aTruthValue);
 110
 111     /**
 112      * Remove an assertion from the graph.
 113      */
 114     void Unassert(in nsIRDFResource aSource,
 115                   in nsIRDFResource aProperty,
 116                   in nsIRDFNode     aTarget);
 117
 118     /**
 119      * Change an assertion from
 120      *
 121      *   [aSource]--[aProperty]-->[aOldTarget]
 122      *
 123      * to
 124      *
 125      *   [aSource]--[aProperty]-->[aNewTarget]
 126      */
 127     void Change(in nsIRDFResource aSource,
 128                 in nsIRDFResource aProperty,
 129                 in nsIRDFNode     aOldTarget,
 130                 in nsIRDFNode     aNewTarget);
 131
 132     /**
 133      * 'Move' an assertion from
 134      *
 135      *   [aOldSource]--[aProperty]-->[aTarget]
 136      *
 137      * to
 138      *
 139      *   [aNewSource]--[aProperty]-->[aTarget]
 140      */
 141     void Move(in nsIRDFResource aOldSource,
 142               in nsIRDFResource aNewSource,
 143               in nsIRDFResource aProperty,
 144               in nsIRDFNode     aTarget);
 145
 146     /**
 147      * Query whether an assertion exists in this graph.
 148      */
 149     boolean HasAssertion(in nsIRDFResource aSource,
 150                          in nsIRDFResource aProperty,
 151                          in nsIRDFNode     aTarget,
 152                          in boolean        aTruthValue);
 153
 154     /**
 155      * Add an observer to this data source. If the datasource
 156      * supports observers, the datasource source should hold a strong
 157      * reference to the observer.
 158      */
 159     void AddObserver(in nsIRDFObserver aObserver);
 160
 161     /**
 162      * Remove an observer from this data source.
 163      */
 164     void RemoveObserver(in nsIRDFObserver aObserver);
 165
 166     /**
 167      * Get a cursor to iterate over all the arcs that point into a node.
 168      *
 169      * @return NS_OK unless a catastrophic error occurs. If the method
 170      * returns NS_OK, you may assume that labels points to a valid (but
 171      * possible empty) nsISimpleEnumerator object.
 172      */
 173     nsISimpleEnumerator ArcLabelsIn(in nsIRDFNode aNode);
 174
 175     /**
 176      * Get a cursor to iterate over all the arcs that originate in
 177      * a resource.
 178      *
 179      * @return NS_OK unless a catastrophic error occurs. If the method
 180      * returns NS_OK, you may assume that labels points to a valid (but
 181      * possible empty) nsISimpleEnumerator object.
 182      */
 183     nsISimpleEnumerator ArcLabelsOut(in nsIRDFResource aSource);
 184
 185     /**
 186      * Retrieve all of the resources that the data source currently
 187      * refers to.
 188      */
 189     nsISimpleEnumerator GetAllResources();
 190
 191     /**
 192      * Returns whether a given command is enabled for a set of sources.
 193      */
 194     boolean IsCommandEnabled(in nsISupportsArray aSources,
 195                              in nsIRDFResource   aCommand,
 196                              in nsISupportsArray aArguments);
 197
 198     /**
 199      * Perform the specified command on set of sources.
 200      */
 201     void DoCommand(in nsISupportsArray aSources,
 202                    in nsIRDFResource   aCommand,
 203                    in nsISupportsArray aArguments);
 204
 205     /**
 206      * Returns the set of all commands defined for a given source.
 207      */
 208     nsISimpleEnumerator GetAllCmds(in nsIRDFResource aSource);
 209
 210     /**
 211      * Returns true if the specified node is pointed to by the specified arc.
 212      * Equivalent to enumerating ArcLabelsIn and comparing for the specified arc.
 213      */
 214     boolean hasArcIn(in nsIRDFNode aNode, in nsIRDFResource aArc);
 215
 216     /**
 217      * Returns true if the specified node has the specified outward arc.
 218      * Equivalent to enumerating ArcLabelsOut and comparing for the specified arc.
 219      */
 220     boolean hasArcOut(in nsIRDFResource aSource, in nsIRDFResource aArc);
 221
 222     /**
 223      * Notify observers that the datasource is about to send several
 224      * notifications at once.
 225      * This must be followed by calling endUpdateBatch(), otherwise
 226      * viewers will get out of sync.
 227      */
 228     void beginUpdateBatch();
 229
 230     /**
 231      * Notify observers that the datasource has completed issuing
 232      * a notification group.
 233      */
 234     void endUpdateBatch();
 235 };