rdf/base/idl/nsIRDFService.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  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either of the GNU General Public License Version 2 or later (the "GPL"),
  26  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #include "nsISupports.idl"
  39 #include "nsIRDFResource.idl"
  40 #include "nsIRDFLiteral.idl"
  41 #include "nsIRDFDataSource.idl"
  42
  43
  44 /**
  45  * The RDF service interface. This is a singleton object which should be
  46  * obtained from the <code>nsServiceManager</code>.
  47  */
  48 [scriptable, uuid(BFD05261-834C-11d2-8EAC-00805F29F370)]
  49 interface nsIRDFService : nsISupports {
  50     /**
  51      * Construct an RDF resource from a single-byte URI. <code>nsIRDFService</code>
  52      * caches resources that are in-use, so multiple calls to <code>GetResource()</code>
  53      * for the same <code>uri</code> will return identical pointers. FindResource
  54      * is used to find out whether there already exists a resource corresponding to that url.
  55      */
  56     nsIRDFResource GetResource(in AUTF8String aURI);
  57
  58     /**
  59      * Construct an RDF resource from a Unicode URI. This is provided
  60      * as a convenience method, allowing automatic, in-line C++
  61      * conversion from <code>nsString</code> objects. The <code>uri</code> will
  62      * be converted to a single-byte representation internally.
  63      */
  64     nsIRDFResource GetUnicodeResource(in AString aURI);
  65
  66     nsIRDFResource GetAnonymousResource();
  67
  68     /**
  69      * Construct an RDF literal from a Unicode string.
  70      */
  71     nsIRDFLiteral  GetLiteral(in wstring aValue);
  72
  73     /**
  74      * Construct an RDF literal from a PRTime.
  75      */
  76     nsIRDFDate     GetDateLiteral(in long long aValue);
  77
  78     /**
  79      * Construct an RDF literal from an int.
  80      */
  81     nsIRDFInt      GetIntLiteral(in long aValue);
  82
  83     /**
  84      * Construct an RDF literal from a data blob
  85      */
  86     [noscript] nsIRDFBlob getBlobLiteral(in const_octet_ptr aValue, in long aLength);
  87
  88     boolean IsAnonymousResource(in nsIRDFResource aResource);
  89
  90     /**
  91      * Registers a resource with the RDF system, making it unique w.r.t.
  92      * GetResource.
  93      *
  94      * An implementation of nsIRDFResource should call this in its
  95      * Init() method if it wishes the resource to be globally unique
  96      * (which is usually the case).
  97      *
  98      * @note that the resource will <i>not</i> be ref-counted by the
  99      * RDF service: the assumption is that the resource implementation
 100      * will call nsIRDFService::UnregisterResource() when the last
 101      * reference to the resource is released.
 102      *
 103      * @note that the nsIRDFService implementation may choose to
 104      * maintain a reference to the resource's URI; therefore, the
 105      * resource implementation should ensure that the resource's URI
 106      * (accessible via nsIRDFResource::GetValue(const char* *aURI)) is
 107      * valid before calling RegisterResource(). Furthermore, the
 108      * resource implementation should ensure that this pointer
 109      * <i>remains</i> valid for the lifetime of the resource. (The
 110      * implementation of the resource cache in nsIRDFService uses the
 111      * URI maintained "internally" in the resource as a key into the
 112      * cache rather than copying the resource URI itself.)
 113      */
 114     void RegisterResource(in nsIRDFResource aResource, in boolean aReplace);
 115
 116     /**
 117      * Called to notify the resource manager that a resource is no
 118      * longer in use. This method should only be called from the
 119      * destructor of a "custom" resource implementation to notify the
 120      * RDF service that the last reference to the resource has been
 121      * released, so the resource is no longer valid.
 122      *
 123      * @note As mentioned in nsIRDFResourceFactory::CreateResource(),
 124      * the RDF service will use the result of
 125      * nsIRDFResource::GetValue() as a key into its cache. For this
 126      * reason, you must always un-cache the resource <b>before</b>
 127      * releasing the storage for the <code>const char*</code> URI.
 128      */
 129     void UnregisterResource(in nsIRDFResource aResource);
 130
 131     /**
 132      * Register a <i>named data source</i>. The RDF service will call
 133      * <code>nsIRDFDataSource::GetURI()</code> to determine the URI under
 134      * which to register the data source.
 135      *
 136      * @note that the data source will <i>not</i> be refcounted by the
 137      * RDF service! The assumption is that an RDF data source
 138      * registers with the service once it is initialized (via
 139      * <code>nsIRDFDataSource::Init()</code>), and unregisters when the
 140      * last reference to the data source is released.
 141      */
 142     void RegisterDataSource(in nsIRDFDataSource aDataSource,
 143                             in boolean          aReplace);
 144
 145     /**
 146      * Unregister a <i>named data source</i>. The RDF service will call
 147      * <code>nsIRDFDataSource::GetURI()</code> to determine the URI under which the
 148      * data source was registered.
 149      */
 150     void UnregisterDataSource(in nsIRDFDataSource aDataSource);
 151
 152     /**
 153      * Get the <i>named data source</i> corresponding to the URI. If a data
 154      * source has been registered via <code>RegisterDataSource()</code>, that
 155      * data source will be returned.
 156      *
 157      * If no data source is currently
 158      * registered for the specified URI, and a data source <i>constructor</i>
 159      * function has been registered via <code>RegisterDatasourceConstructor()</code>,
 160      * the RDF service will call the constructor to attempt to construct a
 161      * new data source. If construction is successful, the data source will
 162      * be initialized via <code>nsIRDFDataSource::Init()</code>.
 163      */
 164     nsIRDFDataSource GetDataSource(in string aURI);
 165
 166     /**
 167      * Same as GetDataSource, but if a remote/XML data source needs to be
 168      * constructed, then this method will issue a <b>blocking</b> Refresh
 169      * call on that data source.
 170      */
 171     nsIRDFDataSource GetDataSourceBlocking(in string aURI);
 172 };
 173
 174 %{C++
 175 extern nsresult
 176 NS_NewRDFService(nsIRDFService** result);
 177 %}
 178