XDI4j Tutorial 7

{{#eclipseproject:technology.higgins|eclipse_custom_style.css}}

This tutorial explains how to set up an XDI endpoint with XDI4j.

EndpointServlet and MessagingTarget

XDI4j includes a single Java servlet. It can be deployed in servlet containers such as Tomcat, Jetty, etc.:

org.eclipse.higgins.xdi4j.messaging.server.EndpointServlet

This servlet can run one or more XDI endpoints, which can receive and process XDI messages.

For each XDI endpoint, a so-called MessagingTarget (a module in the XDI4j server) is deployed to take care of processing the XDI message and constructing an XDI response.

public interface MessagingTarget {
	public void init(EndpointRegistry endpointRegistry) throws Exception;
	public void shutdown() throws Exception;
	public boolean execute(MessageEnvelope messageEnvelope, MessageResult messageResult) throws MessagingException;
}

Before and after control is handed to the MessagingTarget, the XDI4j server performs several common tasks (e.g. parsing the incoming XDI message, processing HTTP headers, etc).

MessagingTargets can be very diverse, depending on what functionality the XDI endpoint is expected to provide. In simple cases, a MessagingTarget exposes a native XDI graph (i.e. an instance of the Graph interface). In more complex cases, a MessagingTarget can dynamically map legacy data to/from XDI.

XDI4j contains several ready-to-use MessagingTarget implementations and also makes it possible to write custom MessagingTargets by implementing a Java interface or by extending a Java abstract base class.

For example, the GraphMessagingTarget is a MessagingTarget that can expose an instance of the Graph interface at an XDI endpoint.

The Spring framework is used for configuring the XDI4j server and its MessagingTargets.

Configuring the XDI4j server

Two files are necessary to configure the XDI4j server:

• WEB-INF/web.xml: The web application's context descriptor
• WEB-INF/applicationContext.xml: Spring configuration file containing MessagingTargets

WEB-INF/web.xml

The WEB-INF/web.xml file should not need any changes:

<?xml version="1.0" encoding="UTF-8"?>
<web-app id="WebApp_ID" version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee">

	<display-name>XDI4j server</display-name>

	<!-- XDI ENDPOINT SERVLET -->

	<servlet>
		<servlet-name>XDIEndpoint</servlet-name>
		<servlet-class>org.eclipse.higgins.xdi4j.messaging.server.EndpointServlet</servlet-class>
		<load-on-startup>20</load-on-startup>
	</servlet>

	<servlet-mapping>
		<servlet-name>XDIEndpoint</servlet-name>
		<url-pattern>/*</url-pattern>
		<url-pattern>/</url-pattern>
	</servlet-mapping>

	<!-- SPRING -->

	<listener>
		<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
	</listener>

</web-app>

WEB-INF/applicationContext.xml

The WEB-INF/applicationContext.xml file contains a list of MessagingTarget beans as well as support objects that may be required.

A MessagingTarget bean's name becomes the URL path at which it is mounted by the XDI4j server. This way, multiple XDI endpoints can be run by a single server. If only a single XDI endpoint should be run at the server's root, then the bean's name should be /.

For example, in order to expose a simple in-memory XDI graph at an XDI endpoint at path /myendpoint, one would use the MemoryGraphFactory and the GraphMessagingTarget like this:

<?xml version="1.0" encoding="UTF-8" ?>
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:util="http://www.springframework.org/schema/util" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-2.0.xsd">

	<bean id="graphfactory" class="org.eclipse.higgins.xdi4j.impl.memory.MemoryGraphFactory" />

	<bean id="mygraph" factory-bean="graphfactory" factory-method="openGraph" />

	<bean name="/myendpoint" class="org.eclipse.higgins.xdi4j.messaging.server.impl.graph.GraphMessagingTarget">
		<property name="graph" ref="mygraph" />
	</bean>
	
</beans>