content: package gov2.nist.javax2.sip.clientauthutils;
  
  import java.text.ParseException;
  import java.util.Collection;
  
  import javax2.sip.ClientTransaction;
  import javax2.sip.InvalidArgumentException;
  import javax2.sip.SipException;
  import javax2.sip.SipProvider;
  import javax2.sip.header.AuthorizationHeader;
  import javax2.sip.message.Request;
  import javax2.sip.message.Response;
  
  /**
   * A helper interface that provides useful functionality for clients that need to authenticate
   * with servers.
   *
   * @author Emil Ivov
   * @author Jeroen van Bemmel
   * @author M. Ranganathan
   *
   * @since 2.0
   *
   *
   */
  public interface AuthenticationHelper {
  
      /**
       * Uses securityAuthority to determinie a set of valid user credentials for
       * the specified Response (Challenge) and appends it to the challenged
       * request so that it could be retransmitted.
       *
       *
       *
       * @param challenge
       *            the 401/407 challenge response
       * @param challengedTransaction
       *            the transaction established by the challenged request
       * @param transactionCreator
       *            the JAIN SipProvider that we should use to create the new
       *            transaction.
       * @param cacheTime The amount of time (seconds ) for which the authentication helper
       *      will keep a reference to the generated credentials in a cache.
       *      If you specify -1, then the authentication credentials are cached
       *      until you remove them from the cache. If you choose this option, make sure
       *      you remove the cached headers or you will have a memory leak.
       *
       * @return a transaction containing a re-originated request with the
       *         necessary authorization header.
       * @throws SipException
       *             if we get an exception white creating the new transaction
       * @throws NullPointerException
       *             if an argument or a header is null.
       */
      public abstract ClientTransaction handleChallenge(Response challenge,
              ClientTransaction challengedTransaction,
              SipProvider transactionCreator, int cacheTime ) throws SipException,
               NullPointerException;
  
      /**
       * Attach authentication headers to the given request. This looks up
       * the credential cache and picks up any stored authentication headers
       * for the given call ID and attaches it to the request.
       * @param request - the request for which we attach the authentication headers.
       */
      public abstract void setAuthenticationHeaders(Request request) ;
  
      /**
       * Remove cached entry.
       *
       * @param callId -- the call Id for which we want to remove the cached headers.
       *
       */
      public abstract void removeCachedAuthenticationHeaders(String callId);
  }
  