org.freecompany.brimstone.core
Class DefaultResolver

java.lang.Object
  org.freecompany.brimstone.core.DefaultResolver

All Implemented Interfaces:

Resolver, ResolverService, ResolverService.I2C, ResolverService.I2Cs, ResolverService.I2L, ResolverService.I2Ls, ResolverService.I2N, ResolverService.I2Ns, ResolverService.I2R, ResolverService.I2Rs, ResolverService.IeqI

public class DefaultResolver
extends java.lang.Object
implements Resolver

The "standard" resolver.

This resolver uses Java Service Discovery to locate other ResolverService implementations and delegates requests to them one at a time. The result indicated by the first delegate to show definitive knowledge of the URI is returned from this service.

Nested Class Summary

Nested classes/interfaces inherited from interface org.freecompany.brimstone.core.ResolverService

ResolverService.I2C, ResolverService.I2Cs, ResolverService.I2L, ResolverService.I2Ls, ResolverService.I2N, ResolverService.I2Ns, ResolverService.I2R, ResolverService.I2Rs, ResolverService.IeqI

Constructor Summary

DefaultResolver()

Method Summary

java.lang.Boolean	equal(java.net.URI u1, java.net.URI u2) Test whether two URIs identify the same resource.
java.lang.Object	getCharacteristic(java.net.URI uri) Translate the given URI to a Universal Resource Characteristics (URC) for the resource.
<T> T	getCharacteristic(java.net.URI uri, java.lang.Class<T> cl)
java.util.List<java.lang.Object>	getCharacteristics(java.net.URI uri) Translate the given URI to a list of URCs for the resource.
java.net.URI	getName(java.net.URI uri) Translate the given URI to a URN for the resource.
java.util.List<java.net.URI>	getNames(java.net.URI uri) Translate the given URI to a list of known URNs for the resource.
java.lang.Object	getResource(java.net.URI uri) Retrieve the resource identified by the URI, in its default format.
<T> T	getResource(java.net.URI uri, java.lang.Class<T> cl) Retrieve the resource identified by the URI, in a specified format.
java.util.List<java.lang.Object>	getResources(java.net.URI uri) Translate the given URI to a list of resources for the object.
java.net.URI	getURL(java.net.URI uri) Translate the given URI to a locator (URL) for the resource.
java.util.List<java.net.URI>	getURLs(java.net.URI uri) Translate the given URI to a list of locators for the resource.
boolean	local() This resolver may discover and delegate to resolvers that are remote, so it should be attempted after any known local resolvers.
boolean	resolvable(java.net.URI uri)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultResolver

public DefaultResolver()

Method Detail

local

public boolean local()

This resolver may discover and delegate to resolvers that are remote, so it should be attempted after any known local resolvers.

Specified by:

local in interface ResolverService

Returns:

true if this resolver only looks locally, false if it uses remote resources.

resolvable

public boolean resolvable(java.net.URI uri)

Specified by:

resolvable in interface ResolverService

getURL

public java.net.URI getURL(java.net.URI uri)
                    throws URIResolutionException

Description copied from interface: ResolverService.I2L

Translate the given URI to a locator (URL) for the resource.

The returned locator should be one that "works" for the resoure - that is, aside from authorization issues or network problems, one that can be used to retrieve the resource.

Note that this returns a URI, not a URL. While the return value is intended to be a locator, the resolver system works exclusively with the URI class to avoid issues associated with missing protocol implementations.

Specified by:

getURL in interface ResolverService.I2L

Parameters:

uri - the URI to resolve.

Returns:

a locator for the resource identified by the URI, or null if no locator can be found.

Throws:

NoSuchURIException - if the URI is definitively known not to represent a resource.

URIGoneException - if the URI existed in the past but nothing is currently known about it.

URINotFoundException - URI exists but there is no available output from this operation.

URIResolutionException - If another problem prevents resolution of the URI.

getURLs

public java.util.List<java.net.URI> getURLs(java.net.URI uri)
                                     throws URIResolutionException

Description copied from interface: ResolverService.I2Ls

Translate the given URI to a list of locators for the resource.

Note that not all of the returned locators need work. If a resolver knows a list of locations that, if they exist would have the resource, it may return the corresponding locators. This differs from ResolverService.I2L, which shouldn't return a locator that "might" refer to the resource.

Specified by:

getURLs in interface ResolverService.I2Ls

Parameters:

uri - the URI to resolve.

Returns:

a list of locators for the resource identified by the URI, or null if no locators are known.

Throws:

NoSuchURIException - if the URI is definitively known not to represent a resource.

URIGoneException - if the URI existed in the past but nothing is currently known about it.

URINotFoundException - URI exists but there is no available output from this operation.

URIResolutionException - If another problem prevents resolution of the URI.

getResource

public java.lang.Object getResource(java.net.URI uri)
                             throws URIResolutionException

Description copied from interface: ResolverService.I2R

Retrieve the resource identified by the URI, in its default format.

It's up to the implementation to decide the format in which the resource is returned. Most implementations will return an InputStream with the content of the resource.

Specified by:

getResource in interface ResolverService.I2R

Parameters:

uri - the URI to retrieve.

Returns:

the resource identified by the URI.

Throws:

NoSuchURIException - if the URI is definitively known not to represent a resource.

URIGoneException - if the URI existed in the past but nothing is currently known about it.

URINotFoundException - URI exists but there is no available output from this operation.

URIResolutionException - If another problem prevents resolution of the URI.

getResource

public <T> T getResource(java.net.URI uri,
                         java.lang.Class<T> cl)
              throws URIResolutionException

Description copied from interface: ResolverService.I2R

Retrieve the resource identified by the URI, in a specified format.

If the service cannot provide the resource as an instance of the requested class, it should return null.

Specified by:

getResource in interface ResolverService.I2R

Parameters:

uri - the URI to retrieve.

cl - a Class indicating the type of resource expected.

Returns:

the resource identified by the URI.

Throws:

NoSuchURIException - if the URI is definitively known not to represent a resource.

URIGoneException - if the URI existed in the past but nothing is currently known about it.

URINotFoundException - URI exists but there is no available output from this operation.

URIResolutionException - If another problem prevents resolution of the URI.

getResources

public java.util.List<java.lang.Object> getResources(java.net.URI uri)
                                              throws URIResolutionException

Description copied from interface: ResolverService.I2Rs

Translate the given URI to a list of resources for the object.

Specified by:

getResources in interface ResolverService.I2Rs

Parameters:

uri - the URI to resolve.

Returns:

A list of resources identified by the URI.

Throws:

NoSuchURIException - if the URI is definitively known not to represent a resource.

URIGoneException - if the URI existed in the past but nothing is currently known about it.

URINotFoundException - URI exists but there is no available output from this operation.

URIResolutionException - If another problem prevents resolution of the URI.

getCharacteristic

public java.lang.Object getCharacteristic(java.net.URI uri)
                                   throws URIResolutionException

Description copied from interface: ResolverService.I2C

Translate the given URI to a Universal Resource Characteristics (URC) for the resource.

Specified by:

getCharacteristic in interface ResolverService.I2C

Parameters:

uri - the URI to resolve.

Returns:

the characteristics for the resource identified by the URI.

Throws:

NoSuchURIException - if the URI is definitively known not to represent a resource.

URIGoneException - if the URI existed in the past but nothing is currently known about it.

URINotFoundException - URI exists but there is no available output from this operation.

URIResolutionException - If another problem prevents resolution of the URI.

getCharacteristic

public <T> T getCharacteristic(java.net.URI uri,
                               java.lang.Class<T> cl)
                    throws URIResolutionException

Specified by:

getCharacteristic in interface ResolverService.I2C

Throws:

URIResolutionException

getCharacteristics

public java.util.List<java.lang.Object> getCharacteristics(java.net.URI uri)
                                                    throws URIResolutionException

Description copied from interface: ResolverService.I2Cs

Translate the given URI to a list of URCs for the resource.

Specified by:

getCharacteristics in interface ResolverService.I2Cs

Parameters:

uri - the URI to resolve.

Returns:

a list of characteristics for the resource identified by the URI.

Throws:

NoSuchURIException - if the URI is definitively known not to represent a resource.

URIGoneException - if the URI existed in the past but nothing is currently known about it.

URINotFoundException - URI exists but there is no available output from this operation.

URIResolutionException - If another problem prevents resolution of the URI.

getName

public java.net.URI getName(java.net.URI uri)
                     throws URIResolutionException

Description copied from interface: ResolverService.I2N

Translate the given URI to a URN for the resource.

Specified by:

getName in interface ResolverService.I2N

Parameters:

uri - the URI to resolve.

Returns:

a URN for the resource identified by the URI.

Throws:

NoSuchURIException - if the URI is definitively known not to represent a resource.

URIGoneException - if the URI existed in the past but nothing is currently known about it.

URINotFoundException - URI exists but there is no available output from this operation.

URIResolutionException - If another problem prevents resolution of the URI.

getNames

public java.util.List<java.net.URI> getNames(java.net.URI uri)
                                      throws URIResolutionException

Description copied from interface: ResolverService.I2Ns

Translate the given URI to a list of known URNs for the resource.

Specified by:

getNames in interface ResolverService.I2Ns

Parameters:

uri - the URI to resolve.

Returns:

a list of all names the service knows for the URI.

Throws:

NoSuchURIException - if the URI is definitively known not to represent a resource.

URIGoneException - if the URI existed in the past but nothing is currently known about it.

URINotFoundException - URI exists but there is no available output from this operation.

URIResolutionException - If another problem prevents resolution of the URI.

equal

public java.lang.Boolean equal(java.net.URI u1,
                               java.net.URI u2)
                        throws URIResolutionException

Description copied from interface: ResolverService.IeqI

Test whether two URIs identify the same resource.

Note that this is a more extensive test than URI#equals(). If the service reports two URIs to be equal, then they are definitively known to refer to the same resource - even if they differ syntactically. If the operation returns null, then the service cannot definitively test the equality of the URIs.

Specified by:

equal in interface ResolverService.IeqI

Parameters:

u1 - a URI to compare

u2 - another URI to compare

Returns:

Boolean.TRUE if the two URIs are definitively known to refer to the same resource. Boolean.FALSE if the two URIs are known to refer to different resources. null if the URIs cannot be compared by the service.

Throws:

NoSuchURIException - if the URI is definitively known not to represent a resource.

URIGoneException - if the URI existed in the past but nothing is currently known about it.

URINotFoundException - URI exists but there is no available output from this operation.

URIResolutionException - If another problem prevents resolution of the URI.