Package net.handle.hdllib

Class HandleResolver

  • All Implemented Interfaces:
    RequestProcessor
    public class HandleResolver
extends java.lang.Object
implements RequestProcessor
    Responsible for locating and retrieving the value of handles using a caching server, or on the internet.

    • Field Detail

      • traceMessages

        public boolean traceMessages

    • Constructor Detail

      • HandleResolver

        public HandleResolver()

    • Method Detail

      • getExecutorService

        public java.util.concurrent.ExecutorService getExecutorService()

      • setExecutorService

        public void setExecutorService​(java.util.concurrent.ExecutorService execServ)

      • 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 determine the appropriate server via global.

      • 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.

      • isUseIPv6FastFallback

        public boolean isUseIPv6FastFallback()

      • setUseIPv6FastFallback

        public void setUseIPv6FastFallback​(boolean useIPv6FastFallback)

      • getSiteFilter

        public SiteFilter getSiteFilter()

      • setSiteFilter

        public void setSiteFilter​(SiteFilter siteFilter)

      • 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

      • processRequest

        public AbstractResponse processRequest​(AbstractRequest req,
                                       ResponseMessageCallback callback)
                                throws HandleException
        This method processes the given request 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 123/abc, and prints them to System.out. 
        
 HandleResolver resolver = new HandleResolver();
 AbstractResponse aResponse = resolver.resolveHandle("123/abc",
                                                    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<values.length; i++) {
     System.out.println(String.valueOf(values[i]));
   }
 }
        Throws:
        HandleException

      • getNAHandle

        @Deprecated
public byte[] getNAHandle​(byte[] handle)
        Deprecated.
        Legacy of slash-based delegation; use Util.getZeroNAHandle
        Find the prefix handle for a handle

      • getNAHandle

        @Deprecated
public byte[] getNAHandle​(ResolutionRequest resReq)
        Deprecated.

      • 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

      • 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​(AuthenticationInfo authInfo,
                                                    SessionSetupInfo sessionOptions,
                                                    ServerInfo server,
                                                    ClientSideSessionInfo currSession,
                                                    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.
        Throws:
        java.lang.Exception