OpenXRI:ClientTutorial

From I-names Development Wiki

This tutorial is intended for developers who are interested in using the OpenXRI client package (an XRI resolver library).

Essential Classes

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

• org.openxri.resolve.Resolver

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

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

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.

Example Code 1

This is a very simple example that initializes the OpenXRI resolver and resolves an XRI to its default service endpoint.

import java.util.List;

import org.openxri.XRI;
import org.openxri.resolve.Resolver;
import org.openxri.resolve.ResolverFlags;
import org.openxri.resolve.ResolverState;


public class Test {

	public static void main (String[] args) throws Exception {
		
        Resolver resolver = new Resolver(null);
        List uris = resolver.resolveSEPToURIList(
                new XRI("@free*earth*moon"),
                null,
                null,
                new ResolverFlags(),
                new ResolverState());

        for (int i=0; i<uris.size(); i++) System.out.println("URI: " + (String) uris.get(i));
	}
}

Example Code 2

This is another example that demonstrates more advances features of the OpenXRI client library, e.g. how to work with XRDS and XRD documents.

import java.net.URI;
import java.util.ArrayList;

import org.openxri.XRI;
import org.openxri.resolve.Resolver;
import org.openxri.resolve.ResolverFlags;
import org.openxri.resolve.ResolverState;
import org.openxri.resolve.exception.PartialResolutionException;
import org.openxri.xml.CanonicalID;
import org.openxri.xml.ContactService;
import org.openxri.xml.Ref;
import org.openxri.xml.Service;
import org.openxri.xml.Status;
import org.openxri.xml.XRD;
import org.openxri.xml.XRDS;

public class Test {

	private static Resolver resolver;
	
	public static void demoSampleXRDS() throws Exception {

		// build a sample XRDS
		
		System.out.println("TEST1: build a sample XRDS");
		
		XRDS xrds = new XRDS();
		XRD xrd = new XRD();

		// set CanonicalID
		
		xrd.setCanonicalID(new CanonicalID("=!1111.2222.3333.4444"));
		
		// add a <Ref>
		
		xrd.addRef(new Ref("=refname"));

		// add a Contact Page SEP
		
		xrd.addService(new ContactService(URI.create("http://contact.myibroker.com/contact/")));
		
		// add a custom SEP

		Service service = new Service();
		service.addType("xri://+i-service*(+myservice)*($v*1.0)");
		service.addURI("http://test.myibroker.com/");
		xrd.addService(service);

		xrds.add(xrd);
		
		System.out.println(xrd.toString());
	}

	public static void demoResolver1() throws Exception {

		// resolve an XRI to an XRDS document

		System.out.println("TEST2: resolve an XRI to an XRDS document");

		try {

			XRI xri = new XRI("@free*earth*moon");
			ResolverFlags resolverFlags = new ResolverFlags();
			ResolverState resolverState = new ResolverState();
			XRDS xrds = resolver.resolveAuthToXRDS(xri, resolverFlags, resolverState);

			System.out.println("XRDS = " + xrds.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());
		}
	}

	public static void demoResolver2() throws Exception {

		// resolve an XRI to a Contact Page service

		System.out.println("TEST3: resolve an XRI to a Contact Page service");

		try {

			XRI xri = new XRI("@inames.net");
			ResolverFlags resolverFlags = new ResolverFlags();
			ResolverState resolverState = new ResolverState();
			ArrayList uris = resolver.resolveSEPToURIList(xri, "xri://+i-service*(+contact)*($v*1.0)", null, resolverFlags, resolverState);

			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());
		}
	}
	
	public static void main (String[] args) throws Exception {

		resolver = new Resolver(null);
		
		demoSampleXRDS();
		demoResolver1();
		demoResolver2();
	}		
}