/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * The contents of this file are subject to the Netscape Public License
 * Version 1.0 (the "NPL"); you may not use this file except in
 * compliance with the NPL.  You may obtain a copy of the NPL at
 * http://www.mozilla.org/NPL/
 *
 * Software distributed under the NPL is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
 * for the specific language governing rights and limitations under the
 * NPL.
 *
 * The Initial Developer of this code under the NPL is Netscape
 * Communications Corporation.  Portions created by Netscape are
 * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
 * Reserved.
 */

#include "nsISupports.idl"
#include "nsIRDFResource.idl"
#include "nsIRDFNode.idl"
#include "nsIEnumerator.idl"
#include "nsIEnumerator.idl"
#include "nsIRDFObserver.idl"

// XXX Because this isn't really and interface :(
[ptr] native nsISupportsArray(nsISupportsArray);
%{C++
#include "nsISupportsArray.h"
%}

[scriptable, uuid(0F78DA58-8321-11d2-8EAC-00805F29F370)]
interface nsIRDFDataSource : nsISupports
{
    // Specify the URI for the data source: this is the prefix
    // that will be used to register the data source in the
    // data source registry.
    void Init(in string uri);

    // The URI of the data source.
    readonly attribute string URI;

    // Find an RDF resource that points to a given node over the
    // specified arc & truth value
    //
    // @return NS_RDF_NO_VALUE if there is no source that leads
    // to the target with the specified property.
    nsIRDFResource GetSource(in nsIRDFResource aProperty,
                             in nsIRDFNode     aTarget,
                             in boolean        aTruthValue);

    // Find all RDF resources that point to a given node over the
    // specified arc & truth value
    //
    // @return NS_OK unless a catastrophic error occurs. If the
    // method returns NS_OK, you may assume that nsISimpleEnumerator points
    // to a valid (but possibly empty) cursor.
    nsISimpleEnumerator GetSources(in nsIRDFResource aProperty,
                                in nsIRDFNode     aTarget,
                                in boolean        aTruthValue);

    // Find a child of that is related to the source by the given arc
    // arc and truth value
    //
    // @return NS_RDF_NO_VALUE if there is no target accessable from the
    // source via the specified property.
    nsIRDFNode GetTarget(in nsIRDFResource aSource,
                         in nsIRDFResource aProperty,
                         in boolean        aTruthValue);

    // Find all children of that are related to the source by the given arc
    // arc and truth value.
    //
    // @return NS_OK unless a catastrophic error occurs. If the
    // method returns NS_OK, you may assume that nsISimpleEnumerator points
    // to a valid (but possibly empty) cursor.
    nsISimpleEnumerator GetTargets(in nsIRDFResource aSource,
                                in nsIRDFResource aProperty,
                                in boolean aTruthValue);

    // Add an assertion to the graph.
    void Assert(in nsIRDFResource aSource, 
                in nsIRDFResource aProperty, 
                in nsIRDFNode     aTarget,
                in boolean        aTruthValue);

    // Remove an assertion from the graph.
    void Unassert(in nsIRDFResource aSource,
                  in nsIRDFResource aProperty,
                  in nsIRDFNode     aTarget);

    // Query whether an assertion exists in this graph.
    boolean HasAssertion(in nsIRDFResource aSource,
                         in nsIRDFResource aProperty,
                         in nsIRDFNode     aTarget,
                         in boolean        aTruthValue);

    // Add an observer to this data source.
    void AddObserver(in nsIRDFObserver aObserver);

    // Remove an observer from this data source
    void RemoveObserver(in nsIRDFObserver aObserver);

    // Get a cursor to iterate over all the arcs that point into a node.
    //
    // @return NS_OK unless a catastrophic error occurs. If the method
    // returns NS_OK, you may assume that labels points to a valid (but
    // possible empty) nsISimpleEnumerator object.
    nsISimpleEnumerator ArcLabelsIn(in nsIRDFNode aNode);

    // Get a cursor to iterate over all the arcs that originate in
    // a resource.
    //
    // @return NS_OK unless a catastrophic error occurs. If the method
    // returns NS_OK, you may assume that labels points to a valid (but
    // possible empty) nsISimpleEnumerator object.
    nsISimpleEnumerator ArcLabelsOut(in nsIRDFResource aSource);

    // Retrieve all of the resources that the data source currently
    // refers to.
    nsISimpleEnumerator GetAllResources();

    // Request that a data source write it's contents out to 
    // permanent storage if applicable.
    void Flush();

    // Returns the set of all commands defined for a given source.
    nsIEnumerator GetAllCommands(in nsIRDFResource aSource);

    // Returns whether a given command is enabled for a set of sources. 
    boolean IsCommandEnabled(in nsISupportsArray aSources,
                             in nsIRDFResource   aCommand,
                             in nsISupportsArray aArguments);

    // Perform the specified command on set of sources.
    void DoCommand(in nsISupportsArray aSources,
                   in nsIRDFResource   aCommand,
                   in nsISupportsArray aArguments);
};