NAME
    XPointerHttpRequest.js - XPointerHttpRequest is a JavaScript library to
    request XML fragments using XPointer

SYNOPSIS
       # you'll need to do this under Mozilla/Gecko (but not Safari) 
       # netscape.security.PrivilegeManager.enablePrivilege("UniversalBrowserRead");

       var doc = "http://127.0.0.1/recipes/beans/baked_beans.xml";

       var xpath = new XPointerXPath ();
       xpath.add_namespace("e","http://www.eatdrinkfeelgood.org/1.1/ns");
       xpath.range("e:ing");

       var xpointer = new XPointerHttpRequest (url);
       xpointer.range(xpath);
       xpointer.accept("multipart/mixed");
 
       var res = xpointer.send();

       if (res.is_success()) {
          alert(res.err() + ":" + res.errstr());
          return false;
       }

       if (res.content_type() == "application/xml") {
          // res is an XMLDocument object
       }

       else {
         // res is a string, which we process locally
       }

DESCRIPTION
    XPointerHttpRequest is a JavaScript library to request XML fragments
    using XPointer and the HTTP 1.1 Range and Accept headers, as described
    in the paper : A Semantic Web Resource Protocol: XPointer and HTTP.

XPointerHttpRequest CLASS METHODS
  new XPointerHttpRequest (url)
    *url* is a string representing the URL of the document you are
    requesting.

    Returns an *XPointerHttpRequest* object.

XPointerHttpRequest OBJECT METHODS
  xpointer.range(query)
    Set the search criteria used to prune the document you are requesting.

    String.

    (Note that the *toString* method for XPointer(XPath|RDQL) objects are
    set up to return a valid string representation so they may be passed, as
    is, to this method.)

  xpointer.accept(list)
    Set the list of acceptable content-types that may be returned by the
    remote server.

    String.

  xpointer.send(callback)
    Send the request.

    *callback* is an optional function reference to be executed if you want
    the request to be processed asynchronously. If defined, the method will
    always return true and it's up to you to process the HTTP response.

    Otherwise, returns a *XPointerResult* or *XPointerError* object.

XPointerXPath CLASS METHODS
  new XPointerXPath()
    Returns a *XPointerXPath* object.

XPointerXPath OBJECT METHODS
    A *XPointerXPath* object's toString() method is set up to return a a
    complete XPointer statement, based on the input passed to the *range*
    and *add_namespace* method. For example :

      var xpath = new XPointerXPath ();
      xpath.add_namespace("e","http://www.eatdrinkfeelgood.org/1.1/ns");
      xpath.range("e:ing");

      alert(xpath);

      # prints 'xmlns(e=http://www.eatdrinkfeelgood.org/1.1/ns)xpointer(e:ing)'

  xpath.add_namespace(prefix,namespaceurl)
    Add a new namespace to your XPath query.

  xpath.range(query)
    Set the XPath sent to the remote server.

    String.

XPointerRDQL CLASS METHODS
  new XPointerRDQL()
    Returns a *XPointerRDQL* object.

XPointerRDQL OBJECT METHODS
    A *XPointerRDQL* object's toString() method is set up to return a a
    complete RDQL statement, based on the input passed to the *range* and
    *add_namespace* method. For example :

      var rdql = new XPointerRDQL ();
      rdql.add_namespace("rdf","http://www.w3.org/1999/02/22-rdf-syntax-ns#");
      rdql.add_namespace("rss","http://purl.org/rss/1.0/");

      rdql.range("SELECT ?title, ?link WHERE "        + 
                 "(?item, <rdf:type>,   <rss:item>)," +
                 "(?item, <rss::title>, ?title),"     +
                 "(?item, <rss::link>,  ?link)");

      alert(rdql);

      # prints SELECT ?title, ?link
      #        WHERE
      #        (?item, <rdf:type>, <rss:item>),
      #        (?item, <rss::title>, ?title),
      #        (?item, <rss::link>, ?link)
      #        USING
      #        rdf for <http://www.w3.org/1999/02/22-rdf-syntax-ns#>,
      #        rss for <http://purl.org/rss/1.0/>;

  rdql.add_namespace(prefix,namespaceurl)
    Add a new namespace to your RDQL query.

  rdql.range(query)
    Set the RDQL sent to the remote server.

    String.

XPointerResult OBJECT METHODS
    A *XPointerResults* object's toString() method is set up to return
    either an *XMLDocument* object if its content-type is either :

    * text/xml
    * application/xml
    * application/rdf+xml

    Otherwise it return a string, containing the content of the server's
    response.

  result.is_success()
    Returns true or false.

  result.content_type()
    Returns a string containing the value of the HTTP Content-type header.

XPointerError OBJECT METHODS
  error.is_success()
    Returns true or false.

  error.err ()
    Returns the code associated with the error.

  error.errstr ()
    Returns the optional message associated with the error.

VERSION
    1.0

DATE
    $Date: 2004/11/18 20:13:22 $

AUTHOR
    Aaron Straup Cope <http://www.aaronstraupcope.com>

SEE ALSO
    http://www.mindswap.org/papers/swrp-iswc04.pdf

    http://www.w3.org/TR/WD-xptr

    http://www.w3.org/Submission/2004/SUBM-RDQL-20040109/

LICENSE
    Copyright (c) 2004 Aaron Straup Cope. All Rights Reserved.

    This is free software, you may use it and distribute it under the same
    terms as the Perl Artistic License.