net.handle.hdllib

Class HandleResolver

java.lang.Object

net.handle.hdllib.HandleResolver

public class HandleResolver
extends java.lang.Object

Responsible for locating and retrieving the value of handles using a caching server, or on the internet.

Field Summary

Fields

Modifier and Type	Field and Description
boolean	delegationEnabled
boolean	traceMessages

Constructor Summary

Constructors

Constructor and Description
HandleResolver()

Method Summary

Methods

Modifier and Type	Method and Description
void	clearCaches() Clear any caches being used by this resolver
SiteInfo[]	findLocalSites(AbstractRequest req) Get the site information for the service that is responsible for this handle while at the same time populating the namespace
SiteInfo[]	findLocalSitesForNA(byte[] naHandle)
Configuration	getConfiguration() Get the resolution configuration
int	getMaxUDPDataSize() Return the maximum size of the data part of a message before it is split into multiple messages when using UDP.
byte[]	getNAHandle(byte[] handle) Find the NA handle for a handle
byte[]	getNAHandle(ResolutionRequest resReq)
NamespaceInfo	getNamespaceInfo(byte[] handle) Find the namespace info for a handle
NamespaceInfo	getNamespaceInfo(ResolutionRequest resReq)
ClientSessionTracker	getSessionTracker() Returns the current default session tracker.
int	getTcpTimeout() Get how long to wait for responses to TCP requests.
int[]	getUdpRetryScheme() Get the array that specifies how long to wait for responses to each UDP request.
AbstractResponse	processRequest(AbstractRequest req) Shortcut to processRequest(req, null);
AbstractResponse	processRequest(AbstractRequest req, ResponseMessageCallback callback) This method sends the given request to the handle system using the currently configured method (global resolution, resolution against a caching server, etc), and returns the response.
AbstractResponse	processRequestGlobally(AbstractRequest req) Shortcut to processRequestGlobally(req, null);
int[]	protocolsByPreference() Return a copy of preferredProtocols[], wherein protocols are listed in order of preference.
HandleValue[]	resolveHandle(java.lang.String sHandle)
HandleValue[]	resolveHandle(java.lang.String sHandle, java.lang.String[] sTypes, int[] indexes) Locate and return the values of the given handle that have the specified types or indexes.
byte[]	retrieveHandleIndexData(byte[] handle, int index) this method will retrieve the handle values by the given handle/index pair Now only used to retrieve public key data in veryfying the session setup data.
AbstractResponse	sendHdlTcpRequest(AbstractRequest req, java.net.InetAddress addr, int port) Shortcut to sendHdlTcpRequest(req, addr, port, null);
AbstractResponse	sendHdlTcpRequest(AbstractRequest req, java.net.InetAddress addr, int port, ResponseMessageCallback callback)
AbstractResponse	sendHdlUdpRequest(AbstractRequest req, java.net.InetAddress addr, int port) Shortcut to sendHdlUdpRequest(req, addr, port, null);
AbstractResponse	sendHdlUdpRequest(AbstractRequest req, java.net.InetAddress addr, int port, ResponseMessageCallback callback)
AbstractResponse	sendHttpRequest(AbstractRequest req, java.net.InetAddress addr, int port) Shortcut to sendHttpRequest(req, addr, port, null);
AbstractResponse	sendHttpRequest(AbstractRequest req, java.net.InetAddress addr, int port, ResponseMessageCallback callback)
AbstractResponse	sendRequestToInterface(AbstractRequest req, ServerInfo server, Interface interfce) Shortcut to sendRequestToInterface(AbstractRequest, ServerInfo, Interface, null);
AbstractResponse	sendRequestToInterface(AbstractRequest req, ServerInfo server, Interface interfce, ResponseMessageCallback callback)
AbstractResponse	sendRequestToServer(AbstractRequest req, ServerInfo server) Shortcut to sendRequestToServer(AbstractRequest, ServerInfo, null);
AbstractResponse	sendRequestToServer(AbstractRequest req, ServerInfo server, ResponseMessageCallback callback) Wrapper around sendRequestToServerByProtocol(), which used to have this name and signature.
AbstractResponse	sendRequestToServer(AbstractRequest req, SiteInfo site, ServerInfo server)
AbstractResponse	sendRequestToServer(AbstractRequest req, SiteInfo site, ServerInfo server, ResponseMessageCallback callback)
AbstractResponse	sendRequestToServerByProtocol(AbstractRequest req, ServerInfo server, int protocolToUse, ResponseMessageCallback callback) Sends the given request to the specified server by the given protocol, if supported.
AbstractResponse	sendRequestToServerInSiteByProtocol(AbstractRequest req, SiteInfo site, ServerInfo server, int protocol, ResponseMessageCallback callback)
AbstractResponse	sendRequestToService(AbstractRequest req, SiteInfo[] sites) Shortcut to sendRequestToService(AbstractRequest, SiteInfo[], null);
AbstractResponse	sendRequestToService(AbstractRequest req, SiteInfo[] sites, ResponseMessageCallback callback)
AbstractResponse	sendRequestToSite(AbstractRequest req, SiteInfo site) Sends the given request to the appropriate server in the given site and returns the response.
AbstractResponse	sendRequestToSite(AbstractRequest req, SiteInfo site, int protocol) Shortcut to sendRequestToSite(AbstractRequest, site, protocol, null);
AbstractResponse	sendRequestToSite(AbstractRequest req, SiteInfo site, int protocol, ResponseMessageCallback callback)
AbstractResponse	sendRequestToSite(AbstractRequest req, SiteInfo site, ResponseMessageCallback callback) Sends the given request to the appropriate server in the given site and returns the response.
void	setCache(Cache cache) Gives the resolver a Cache object to use when resolving.
void	setCertifiedCache(Cache cache) Gives the resolver a Cache object to use for certified resolutions.
void	setCheckSignatures(boolean checkSigs) Set whether or not this object should check the signatures of server responses to certified requests.
void	setConfiguration(Configuration config) Set the configuration used for resolution.
void	setMaxUDPDataSize(int newMaxUDPDataSize) Set the maximum size of the data part of a message before it is split into multiple messages when using UDP.
void	setPreferredProtocols(int[] prefProtocols) Set the protocols and the order of preference used for resolution For every server that this resolver talks to, it attempts to communicate via the given protocols either until it succeeds or all attempts to communicate fail.
void	setSessionTracker(ClientSessionTracker sessionTracker) Gives the resolver a session tracker object to use when resolving.
void	setTcpTimeout(int newTcpTimeout) Set how long to wait for responses to TCP and HTTP requests.
void	setUdpRetryScheme(int[] newudpRetryScheme) Set the array that specifies how long to wait for responses to each UDP request.
ClientSideSessionInfo	setupSessionWithServer(AbstractRequest req, SessionSetupInfo sessionOptions, ServerInfo server, ClientSideSessionInfo currSession, ResponseMessageCallback callback) Initiates and returns a session with the given server for the given request.
ClientSideSessionInfo	setupSessionWithServer(AbstractRequest req, SessionSetupInfo sessionOptions, ServerInfo server, ResponseMessageCallback callback) Create a new session to handle the given request.
ClientSideSessionInfo	setupSessionWithServer(AuthenticationInfo authInfo, SessionSetupInfo sessionOptions, ServerInfo server, ClientSideSessionInfo currSession, ResponseMessageCallback callback, int majorProtocolVersion, int minorProtocolVersion) Initiates and returns a session with the given server using the given authentication information.

Methods inherited from class java.lang.Object

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

Field Detail

traceMessages

public boolean traceMessages

delegationEnabled

public boolean delegationEnabled

Constructor Detail

HandleResolver

public HandleResolver()

Method Detail

protocolsByPreference

public int[] protocolsByPreference()

Return a copy of preferredProtocols[], wherein protocols are listed in order of preference. For use by methods which do not have access to the private int-array.

retrieveHandleIndexData

public byte[] retrieveHandleIndexData(byte[] handle,
                             int index)
                               throws java.lang.Exception

this method will retrieve the handle values by the given handle/index pair Now only used to retrieve public key data in veryfying the session setup data.

Throws:

java.lang.Exception

setCache

public void setCache(Cache cache)

Gives the resolver a Cache object to use when resolving. When sending requests, the cache will be checked for the handle instead of always using the network. Setting the cache object to null will cause the resolver to not use any cache.

setCertifiedCache

public void setCertifiedCache(Cache cache)

Gives the resolver a Cache object to use for certified resolutions. When sening certified resolution requests, this cache will be checked for the handle instead of always using the network. Setting the cache object to null will cause the resolver to not use any cache for certified resolutions. Note: It is important to never use the same cache (or backing storage) for the certified and regular cache. Doing so could poison the certified cache with uncertified values.

clearCaches

public void clearCaches()
                 throws java.lang.Exception

Clear any caches being used by this resolver

Throws:

java.lang.Exception

setSessionTracker

public void setSessionTracker(ClientSessionTracker sessionTracker)

Gives the resolver a session tracker object to use when resolving. When sending administrative requests and the resolver's session tracker is non-null, it is used to establish (or continue) a session with whatever server is being communicated with. Note: If there is a sessionInfo or session tracker already associated with a request, then the resolver's session tracker is ignored. Warning: If this resolver is going to be used in several administrative contexts (ie with several different admin IDs) because authenticated sessions could possibly be used by a different administrator than was intended.

getSessionTracker

public ClientSessionTracker getSessionTracker()

Returns the current default session tracker.

setConfiguration

public void setConfiguration(Configuration config)

Set the configuration used for resolution. This configuration indicates whether requests are processed using a network cache (ala DNS) or if we talk directly to the handle system.

setPreferredProtocols

public void setPreferredProtocols(int[] prefProtocols)

Set the protocols and the order of preference used for resolution For every server that this resolver talks to, it attempts to communicate via the given protocols either until it succeeds or all attempts to communicate fail. If a client is behind a firewall and not using a caching server then it would be best to set the preferred protocols to Interface.SP_HDL_TCP and Interface.SP_HDL_HTTP since the Interface.SP_HDL_UDP will probably just get blocked by firewalls and be a big waste of time.

setMaxUDPDataSize

public void setMaxUDPDataSize(int newMaxUDPDataSize)

Set the maximum size of the data part of a message before it is split into multiple messages when using UDP.

getMaxUDPDataSize

public int getMaxUDPDataSize()

Return the maximum size of the data part of a message before it is split into multiple messages when using UDP.

getConfiguration

public Configuration getConfiguration()

Get the resolution configuration

setTcpTimeout

public void setTcpTimeout(int newTcpTimeout)

Set how long to wait for responses to TCP and HTTP requests.

getTcpTimeout

public int getTcpTimeout()

Get how long to wait for responses to TCP requests.

getUdpRetryScheme

public int[] getUdpRetryScheme()

Get the array that specifies how long to wait for responses to each UDP request. The length of this array will indicate how many UDP requests to send before giving up. The default scheme is something like {1000, 2000, 3000} which is 1 second, 2 seconds, 3 seconds.

setUdpRetryScheme

public void setUdpRetryScheme(int[] newudpRetryScheme)

Set the array that specifies how long to wait for responses to each UDP request. The length of this array will indicate how many UDP requests to send before giving up. The default scheme is something like {1000, 2000, 3000} which is 1 second, 2 seconds, 3 seconds.

setCheckSignatures

public void setCheckSignatures(boolean checkSigs)

Set whether or not this object should check the signatures of server responses to certified requests. The default is to check signatures and throw an exception if a signature to any certified message is missing or invalid.

resolveHandle

public HandleValue[] resolveHandle(java.lang.String sHandle,
                          java.lang.String[] sTypes,
                          int[] indexes)
                            throws HandleException

Locate and return the values of the given handle that have the specified types or indexes. This method simply creates a ResolutionRequest object from the given parameters and calls processRequest with that request object. The requested handle values are then extracted from the response and returned (or an exception is thrown if there was an error). Creating your own ResolutionRequest objects and calling processRequest directly allows more flexibility since you can set the certified, authoritative, and recursive flags of the request. When specifying both a set of types or indexes, a server will return all handle values that have the requested types as well as all handle values that have the requested indexes. Essentially, the union of the set of handles with the requested types and the set of handles with the requested indexes is returned. An empty index or type list indicates that any index or type is acceptable. The following examples describe how the type and index lists are used in resolutions:

  Type-List       Index List       Returns
   [ URL ]         [ 0, 12 ]       Any URL values, as well as values
                                    with indexes 0 and 12 if they exist.
   [ ]             [ 1 ]           The value with index one only
   [ EMAIL ]       [ ]             Any values with type EMAIL
   [ ]             [ ]             All of the values associated with the
                                    given handle

Throws:

HandleException

resolveHandle

public HandleValue[] resolveHandle(java.lang.String sHandle)
                            throws HandleException

Throws:

HandleException

processRequest

public AbstractResponse processRequest(AbstractRequest req,
                              ResponseMessageCallback callback)
                                throws HandleException

This method sends the given request to the handle system using the currently configured method (global resolution, resolution against a caching server, etc), and returns the response. If a Cache object is available it will be used if the request is a ResolutionRequest and the authoritative flag of the request is not set. The AbstractResponse object that is returned can be either an ErrorResponse or a ResolutionResponse object. Check the responseCode of the AbstractResponse (or use the instanceof keyword) to determine if the response can safely be casted to a ResolutionResponse or not. If you determine that the response is a ResolutionResponse then you can cast the response and call getHandleValues() on it. The following is an example that requests all of the URL values associated with the handle 10.1000/12, and prints them to System.out.

 HandleResolver resolver = new HandleResolver();
 AbstractResponse aResponse = resolver.resolveHandle("10.1000/12",
                                                    new String[]{"URL"},
                                                    null);
 if(aResponse.responseCode==AbstractMessage.RC_SUCCESS) {
   ResolutionResponse response = (ResolutionResponse)aResponse;
   HandleValue values[] = response.getHandleValues();
   System.out.println("Received values: ");
   for(int i=0; i

Throws:

HandleException

processRequest

public AbstractResponse processRequest(AbstractRequest req)
                                throws HandleException

Shortcut to processRequest(req, null);

Throws:

HandleException

processRequestGlobally

public AbstractResponse processRequestGlobally(AbstractRequest req)
                                        throws HandleException

Shortcut to processRequestGlobally(req, null);

Throws:

HandleException

findLocalSitesForNA

public SiteInfo[] findLocalSitesForNA(byte[] naHandle)
                               throws HandleException

Throws:

HandleException

findLocalSites

public SiteInfo[] findLocalSites(AbstractRequest req)
                          throws HandleException

Get the site information for the service that is responsible for this handle while at the same time populating the namespace

Throws:

HandleException

getNAHandle

public byte[] getNAHandle(byte[] handle)
                   throws HandleException

Find the NA handle for a handle

Throws:

HandleException

getNAHandle

public byte[] getNAHandle(ResolutionRequest resReq)
                   throws HandleException

Throws:

HandleException

getNamespaceInfo

public NamespaceInfo getNamespaceInfo(byte[] handle)
                               throws HandleException

Find the namespace info for a handle

Throws:

HandleException

getNamespaceInfo

public NamespaceInfo getNamespaceInfo(ResolutionRequest resReq)
                               throws HandleException

Throws:

HandleException

sendRequestToService

public final AbstractResponse sendRequestToService(AbstractRequest req,
                                    SiteInfo[] sites,
                                    ResponseMessageCallback callback)
                                            throws HandleException

Throws:

HandleException

sendRequestToService

public AbstractResponse sendRequestToService(AbstractRequest req,
                                    SiteInfo[] sites)
                                      throws HandleException

Shortcut to sendRequestToService(AbstractRequest, SiteInfo[], null);

Throws:

HandleException

sendRequestToSite

public AbstractResponse sendRequestToSite(AbstractRequest req,
                                 SiteInfo site,
                                 int protocol)
                                   throws HandleException

Shortcut to sendRequestToSite(AbstractRequest, site, protocol, null);

Throws:

HandleException

sendRequestToSite

public AbstractResponse sendRequestToSite(AbstractRequest req,
                                 SiteInfo site,
                                 int protocol,
                                 ResponseMessageCallback callback)
                                   throws HandleException

Throws:

HandleException

sendRequestToServerInSiteByProtocol

public AbstractResponse sendRequestToServerInSiteByProtocol(AbstractRequest req,
                                                   SiteInfo site,
                                                   ServerInfo server,
                                                   int protocol,
                                                   ResponseMessageCallback callback)
                                                     throws HandleException

Throws:

HandleException

sendRequestToServer

public AbstractResponse sendRequestToServer(AbstractRequest req,
                                   ServerInfo server)
                                     throws HandleException

Shortcut to sendRequestToServer(AbstractRequest, ServerInfo, null);

Throws:

HandleException

sendRequestToServer

public AbstractResponse sendRequestToServer(AbstractRequest req,
                                   SiteInfo site,
                                   ServerInfo server)
                                     throws HandleException

Throws:

HandleException

sendRequestToServer

public AbstractResponse sendRequestToServer(AbstractRequest req,
                                   ServerInfo server,
                                   ResponseMessageCallback callback)
                                     throws HandleException

Wrapper around sendRequestToServerByProtocol(), which used to have this name and signature. This is invoked by the code which formerly invoked the older method.

Throws:

HandleException

sendRequestToServer

public AbstractResponse sendRequestToServer(AbstractRequest req,
                                   SiteInfo site,
                                   ServerInfo server,
                                   ResponseMessageCallback callback)
                                     throws HandleException

Throws:

HandleException

sendRequestToSite

public AbstractResponse sendRequestToSite(AbstractRequest req,
                                 SiteInfo site)
                                   throws HandleException

Sends the given request to the appropriate server in the given site and returns the response. This will try to contact the appropriate server by trying each of the preferred protocols, in order.

Throws:

HandleException

sendRequestToSite

public AbstractResponse sendRequestToSite(AbstractRequest req,
                                 SiteInfo site,
                                 ResponseMessageCallback callback)
                                   throws HandleException

Sends the given request to the appropriate server in the given site and returns the response. This will try to contact the appropriate server by trying each of the preferred protocols, in order.

Throws:

HandleException

sendRequestToServerByProtocol

public AbstractResponse sendRequestToServerByProtocol(AbstractRequest req,
                                             ServerInfo server,
                                             int protocolToUse,
                                             ResponseMessageCallback callback)
                                               throws HandleException

Sends the given request to the specified server by the given protocol, if supported. Also, if there is a ClientSideSessionInfo or ClientSessionTracker object associated with the request then a session will be created (if necessary) and used to send the message. This was formerly sendRequestToServer(), with the 3-argument signature of the "wrapper" function above. The "for each protocol" loop has been moved to the wrapper (and replaced with a passed-in specific protocol) so that this function can be called without the loop by methods having the loop themselves.

Throws:

HandleException

setupSessionWithServer

public ClientSideSessionInfo setupSessionWithServer(AbstractRequest req,
                                           SessionSetupInfo sessionOptions,
                                           ServerInfo server,
                                           ResponseMessageCallback callback)
                                             throws java.lang.Exception

Create a new session to handle the given request.

Throws:

java.lang.Exception

setupSessionWithServer

public ClientSideSessionInfo setupSessionWithServer(AbstractRequest req,
                                           SessionSetupInfo sessionOptions,
                                           ServerInfo server,
                                           ClientSideSessionInfo currSession,
                                           ResponseMessageCallback callback)
                                             throws java.lang.Exception

Initiates and returns a session with the given server for the given request.

Parameters:

currSession - If non null, that session will be modified. Note: Security check! Since session information is stored in the handle resolve, users of this code must be _very_ careful not to pass the HandleResolver object around to untrusted code. A better way to do this might be to make the session stuff not happen automatically and have public methods for starting, finishing, and using sessions. AbstractRequest objects should have session objects associated with them just like regular authentication information.

Throws:

java.lang.Exception

setupSessionWithServer

public ClientSideSessionInfo setupSessionWithServer(AuthenticationInfo authInfo,
                                           SessionSetupInfo sessionOptions,
                                           ServerInfo server,
                                           ClientSideSessionInfo currSession,
                                           ResponseMessageCallback callback,
                                           int majorProtocolVersion,
                                           int minorProtocolVersion)
                                             throws java.lang.Exception

Initiates and returns a session with the given server using the given authentication information.

Parameters:

currSession - If non null, that session will be modified. Note: Security check! Since session information is stored in the handle resolve, users of this code must be _very_ careful not to pass the HandleResolver object around to untrusted code. A better way to do this might be to make the session stuff not happen automatically and have public methods for starting, finishing, and using sessions. AbstractRequest objects should have session objects associated with them just like regular authentication information.

Throws:

java.lang.Exception

sendRequestToInterface

public AbstractResponse sendRequestToInterface(AbstractRequest req,
                                      ServerInfo server,
                                      Interface interfce)
                                        throws HandleException

Shortcut to sendRequestToInterface(AbstractRequest, ServerInfo, Interface, null);

Throws:

HandleException

sendRequestToInterface

public AbstractResponse sendRequestToInterface(AbstractRequest req,
                                      ServerInfo server,
                                      Interface interfce,
                                      ResponseMessageCallback callback)
                                        throws HandleException

Throws:

HandleException

sendHdlUdpRequest

public AbstractResponse sendHdlUdpRequest(AbstractRequest req,
                                 java.net.InetAddress addr,
                                 int port)
                                   throws HandleException

Shortcut to sendHdlUdpRequest(req, addr, port, null);

Throws:

HandleException

sendHdlUdpRequest

public AbstractResponse sendHdlUdpRequest(AbstractRequest req,
                                 java.net.InetAddress addr,
                                 int port,
                                 ResponseMessageCallback callback)
                                   throws HandleException

Throws:

HandleException

sendHdlTcpRequest

public AbstractResponse sendHdlTcpRequest(AbstractRequest req,
                                 java.net.InetAddress addr,
                                 int port)
                                   throws HandleException

Shortcut to sendHdlTcpRequest(req, addr, port, null);

Throws:

HandleException

sendHdlTcpRequest

public AbstractResponse sendHdlTcpRequest(AbstractRequest req,
                                 java.net.InetAddress addr,
                                 int port,
                                 ResponseMessageCallback callback)
                                   throws HandleException

Throws:

HandleException

sendHttpRequest

public AbstractResponse sendHttpRequest(AbstractRequest req,
                               java.net.InetAddress addr,
                               int port)
                                 throws HandleException

Shortcut to sendHttpRequest(req, addr, port, null);

Throws:

HandleException

sendHttpRequest

public AbstractResponse sendHttpRequest(AbstractRequest req,
                               java.net.InetAddress addr,
                               int port,
                               ResponseMessageCallback callback)
                                 throws HandleException

Throws:

HandleException