001: /*
002: * @(#)AuthorizationHandler.java 0.3-2 18/06/1999
003: *
004: * This file is part of the HTTPClient package
005: * Copyright (C) 1996-1999 Ronald Tschalär
006: *
007: * This library is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU Lesser General Public
009: * License as published by the Free Software Foundation; either
010: * version 2 of the License, or (at your option) any later version.
011: *
012: * This library is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this library; if not, write to the Free
019: * Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
020: * MA 02111-1307, USA
021: *
022: * For questions, suggestions, bug-reports, enhancement-requests etc.
023: * I may be contacted at:
024: *
025: * ronald@innovation.ch
026: *
027: */
028:
029: package HTTPClient;
030:
031: import java.io.IOException;
032:
033: /**
034: * This is the interface that an Authorization handler must implement. You
035: * can implement your own auth handler to add support for auth schemes other
036: * than the ones handled by the default handler, to use a different UI for
037: * soliciting usernames and passwords, or for using an altogether different
038: * way of getting the necessary auth info.
039: *
040: * @see AuthorizationInfo#setAuthHandler(HTTPClient.AuthorizationHandler)
041: * @version 0.3-2 18/06/1999
042: * @author Ronald Tschalär
043: */
044:
045: public interface AuthorizationHandler {
046: /**
047: * This method is called whenever a 401 or 407 response is received and
048: * no candidate info is found in the list of known auth info. Usually
049: * this method will query the user for the necessary info.
050: *
051: * <P>If the returned info is not null it will be added to the list of
052: * known info. If the info is valid for more than one (host, port, realm,
053: * scheme) tuple then this method must add the corresponding auth infos
054: * itself.
055: *
056: * <P>This method must check <var>req.allow_ui</var> and only attempt
057: * user interaction if it's <var>true</var>.
058: *
059: * @param challenge the parsed challenge from the server; the host,
060: * port, scheme, realm and params are set to the
061: * values given by the server in the challenge.
062: * @param req the request which provoked this response.
063: * @param resp the full response.
064: * @return the authorization info to use when retrying the request,
065: * or null if the request is not to be retried. The necessary
066: * info includes the host, port, scheme and realm as given in
067: * the <var>challenge</var> parameter, plus either the basic
068: * cookie or any necessary params.
069: * @exception AuthSchemeNotImplException if the authorization scheme
070: * in the challenge cannot be handled.
071: */
072: AuthorizationInfo getAuthorization(AuthorizationInfo challenge,
073: RoRequest req, RoResponse resp)
074: throws AuthSchemeNotImplException;
075:
076: /**
077: * This method is called whenever auth info is chosen from the list of
078: * known info in the AuthorizationInfo class to be sent with a request.
079: * This happens when either auth info is being preemptively sent or if
080: * a 401 response is retrieved and a matching info is found in the list
081: * of known info. The intent of this method is to allow the handler to
082: * fix up the info being sent based on the actual request (e.g. in digest
083: * authentication the digest-uri, nonce and response-digest usually need
084: * to be recalculated).
085: *
086: * @param info the authorization info retrieved from the list of
087: * known info.
088: * @param req the request this info is targeted for.
089: * @param challenge the authorization challenge received from the server
090: * if this is in response to a 401, or null if we are
091: * preemptively sending the info.
092: * @param resp the full 401 response received, or null if we are
093: * preemptively sending the info.
094: * @return the authorization info to be sent with the request, or null
095: * if none is to be sent.
096: * @exception AuthSchemeNotImplException if the authorization scheme
097: * in the info cannot be handled.
098: */
099: AuthorizationInfo fixupAuthInfo(AuthorizationInfo info,
100: RoRequest req, AuthorizationInfo challenge, RoResponse resp)
101: throws AuthSchemeNotImplException;
102:
103: /**
104: * Sometimes even non-401 responses will contain headers pertaining to
105: * authorization (such as the "Authentication-Info" header). Therefore
106: * this method is invoked for each response received, even if it is not
107: * a 401 or 407 response. In case of a 401 or 407 response the methods
108: * <code>fixupAuthInfo()</code> and <code>getAuthorization()</code> are
109: * invoked <em>after</em> this method.
110: *
111: * @param resp the full Response
112: * @param req the Request which provoked this response
113: * @param prev the previous auth info sent, or null if none was sent
114: * @param prxy the previous proxy auth info sent, or null if none was sent
115: * @exception IOException if an exception occurs during the reading of
116: * the headers.
117: */
118: void handleAuthHeaders(Response resp, RoRequest req,
119: AuthorizationInfo prev, AuthorizationInfo prxy)
120: throws IOException;
121:
122: /**
123: * This method is similar to <code>handleAuthHeaders</code> except that
124: * it is called if any headers in the trailer were sent. This also
125: * implies that it is invoked after any <code>fixupAuthInfo()</code> or
126: * <code>getAuthorization()</code> invocation.
127: *
128: * @param resp the full Response
129: * @param req the Request which provoked this response
130: * @param prev the previous auth info sent, or null if none was sent
131: * @param prxy the previous proxy auth info sent, or null if none was sent
132: * @exception IOException if an exception occurs during the reading of
133: * the trailers.
134: * @see #handleAuthHeaders(RoResponse, RoRequest, AuthorizationInfo, AuthorizationInfo)
135: */
136: void handleAuthTrailers(Response resp, RoRequest req,
137: AuthorizationInfo prev, AuthorizationInfo prxy)
138: throws IOException;
139: }
|