XDI routing

XDI routing fulfills a similar purpose as routing in an IP network. Given a target XDI peer root such as (+!:uuid:0000), XDI routing can determine the best way to send XDI messages to this target.

The input of XDI routing is an XDI peer root.

The output of XDI routing is an instance of XDIClient, which can be used to send XDI messages.

XDI routing configuration

Through configuration, the XDI routing process can be influenced in various ways:

• Some XDI routes may be very universal and are able to route to any XDI peer root, whereas other XDI routes may work only specifically for a single XDI peer root.
• During the XDI routing process, the target XDI peer root may be overridden in order to force XDI messages to a specific target.
• "Catch-all" XDI routes can route XDI messages in a default way if all other XDI routes fail.
• Besides influencing the XDI routing process itself, the contents of XDI messages may also be altered in various ways through the use of a manipulator, e.g. in order to automatically add signatures, override link contracts, etc.

Usage

XDI routing can be used directly by XDI applications to send XDI messages to a target XDI peer root.

XDI routing is also used internally by various components in XDI2, e.g.:

• The ConnectInterceptor uses XDI routing to obtain link contract templates that are the object of a $connect operation.
• The SendInterceptor uses XDI routing to route nested messages of a $send operation to their target.
• The BasicPushGateway uses XDI routing to deliver $push notifications to the requesting authority of a push link contract.
• The RedirectInterceptor uses XDI routing to "redirect" XDI messages received by a [messaging target](messaging targets).

XDIAgent

The XDIAgent interface and its default XDIBasicAgent implementation are the starting point of XDI routing. They use a configurable list of XDIAgentRouter instances to find routes for a target XDI peer root.

XDIAgentRouter

An XDIAgentRouter represents a specific way of finding a route for a target XDI peer root:

• The XDIHttpDiscoveryAgentRouter uses XDI discovery to find a route to an XDI HTTP endpoint.
• The XDIHttpAgentRouter can route to a single static XDI HTTP endpoint.
• The XDIWebSocketDiscoveryAgentRouter uses XDI discovery to find a route to an XDI WebSocket endpoint.
• The XDIWebSocketAgentRouter can route to a single static XDI WebSocket endpoint.
• The XDIWebSocketTransportAgentRouter can route to a XDI WebSocket session that is currently open on a server.
• The XDILocalAgentRouter can route to a static local XDI graph or [messaging target](messaging targets).
• The XDIBootstrapLocalAgentRouter can route to the well-known static local XDI bootstrap graph.
• The XDIMessagingTargetRegistryRouter can route to a local [messaging target](messaging targets) that is registered in a server's messaging target registry.
• The XDIStaticAgentRouter can route to a static target.

XDIClientRoute

An XDIClientRouter represents the result of a routing process and encapsulates the information necessary to instantiate an XDIClient, which can be used to send XDI messages.

• The XDILocalClientRoute can instantiate an XDILocalClient to send XDI messages to a local XDI graph or messaging target.
• The XDIHttpClientRoute can instantiate an XDIHttpClient to send XDI messages to an XDI HTTP endpoint.
• The XDIWebSocketClientRoute can instantiate an XDIWebSocketClient to send XDI messages to an XDI WebSocket endpoint.

Example Configuration

The following configuration sets up an XDIBasicAgent with a default list of XDIAgentRouter instances. With this configuration, an XDI message will be routed (in this order) to the XDI bootstrap graph, to local messaging targets, to currently open XDI WebSocket sessions, and finally, to an XDI HTTP endpoint using XDI discovery:

<bean id="XdiAgent" class="xdi2.agent.impl.XDIBasicAgent">
	<property name="agentRouters">
		<util:list>
			<bean class="xdi2.agent.routing.impl.bootstrap.XDIBootstrapLocalAgentRouter" />
			<bean class="xdi2.agent.routing.impl.local.XDIMessagingTargetRegistryAgentRouter">
				<property name="messagingTargetRegistry" ref="UriMessagingTargetRegistry" />
			</bean>
			<bean class="xdi2.agent.routing.impl.websocket.XDIWebSocketTransportAgentRouter">
				<property name="webSocketTransport" ref="WebSocketTransport" />
			</bean>
			<bean class="xdi2.agent.routing.impl.http.XDIHttpDiscoveryAgentRouter">
				<property name="xdiDiscoveryClient" ref="XdiDiscoveryClient" />
			</bean>
		</util:list>
	</property>
</bean>

Interfaces and Classes

• xdi2.agent.XDIAgent
• xdi2.agent.routing.XDIAgentRouter
• xdi2.client.XDIClientRoute