OpenXRI:Tutorial

From I-names Development Wiki

Contents 1 Audience 2 Essential Objects 3 Calling the Resolver 4 More Code

[edit] Audience

This tutorial is intended for application developers who wishes to integrate XRI functionality into their applications using the OpenXRI library.

[edit] Essential Objects

This is a summary of the few prominent classes within the library.

• org.openxri.XRI (module: org.openxri.syntax)

This represents a type-safe parsed XRI. An XRI object can be instantiated by using the XRI(String) constructor if the client is certain that the string is in XRI normal form. XRI normal form is the preferred form for XRI processing but it is not suitable for contexts where an IRI or URI is expected. For those, the the fromIRINormalForm and fromIRINormalForm static methods should be used. URI normal form is by far the most prevalent and compatible way to transport URI in applications that are not aware of XRIs.

Calling any of the three methods above causes the string to be parsed, and the various parts of the XRI may be accessed using a variety of methods. This is similar in spirit to Java's java.net.URI class.

• org.openxri.resolve.Resolver (module: org.openxri.client)

This is the main Resolver class used for resolving an XRI. Applications would generally call one or more of the following instance methods depending on the resolution results desired:

resolveAuthToXRDS

resolveAuthToXRD

resolveSEPToXRDS

resolveSEPToXRD

resolveSEPToURIList

resolveSEPToTextURIList

• org.openxri.xml.XRDS (module: org.openxri.client)

This class represents an XRDS document. It contains methods to build and parse an XRDS document, as well as getters and setters to access various parts of the document.

• org.openxri.xml.XRD (module: org.openxri.client)

This class represents an XRD element within the XRDS document. It contains getters to allow various child elements to be traversed, as well as setters to allow its content to be modified.

[edit] Calling the Resolver

In order to use a OpenXRI resolver, a Resolver object must be instantiated and initialized:

import java.util.ArrayList;
import org.openxri.resolve.*;
import org.openxri.resolve.exception.*;
import org.openxri.xml.*;


// creates an XRD object that contains an authority resolution service endpoint with the given URI
public static XRD createAuthRoot(String uri)
{
  XRD xrd = new XRD();

  // construct an authority resolution service
  Service srv = new Service();
  TrustType tt = new TrustType(); // default trust type
  String authMediaType = Tags.CONTENT_TYPE_XRDS + ";" + tt.getParameterPair();
  srv.addMediaType(authMediaType, SEPElement.MATCH_ATTR_CONTENT, Boolean.FALSE);
  srv.addType(Tags.SERVICE_AUTH_RES);
  srv.addURI(uri);

  // add it to the XRD
  xrd.addService(srv);

  return xrd;
}


public static Resolver setupResolver()
{
  // instantiate a Resolver object
  Resolver resolver = new Resolver();

  // configure roots
  XRD eqRoot = createAuthRoot("http://equal.xri.net");
  resolver.setAuthority("=", eqRoot);
  XRD atRoot = createAuthRoot("http://at.xri.net");
  resolver.setAuthority("@", atRoot);

  return resolver;
}


public static void main (String[] args)
{
  Resolver resolver = setupResolver();

  try {
    // get the XRDS document for =foo with default trust type (none), following Refs if needed
    XRDS xrds = resolver.resolveAuthToXRDS("=foo", new TrustType(), true);

    // resolution completed successfully if we did not catch an exception
    System.out.println("XRDS = " + xrds.toString());

    // select a service using a set of criteria 
    ArrayList uris = resolver.resolveSEPToURIList("=foo/bar", new TrustType(), "xri://+some-type", "some/media-type", true);
    for (int i = 0; i < uris.size(); i++) {
      System.out.println("Resolved URI[" + i + "] = " + uris.get(0).toString());
    }
  }
  catch (PartialResolutionException prex)
  {
    // get the partially resolved results
    XRDS errXRDS = prex.getPartialXRDS();
    XRD errXRD = errXRDS.getFinalXRD();
    Status stat = errXRD.getStatus();
    String statusCode = (stat == null) ? "unknown" : stat.getCode();

    // the resolution did not complete successfully
    System.err.println("Resolution error code: " + statusCode);
    System.err.println("Full error XRDS: " + errXRDS.toString());
  }
}

The above code is also available on the OpenXRI CVS repository, download it here.

[edit] More Code

Code using the Resolver class can be found in the following classes:

• org.openxri.servlet.Proxy
• org.openxri.tools.xrilookup.XRILookup