org.freecompany.brimstone.core
Class DefaultResolver

java.lang.Object
  extended by 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.