KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > HTTPClient > AuthorizationHandler


1 /*
2  * @(#)AuthorizationHandler.java 0.3-2 18/06/1999
3  *
4  * This file is part of the HTTPClient package
5  * Copyright (C) 1996-1999 Ronald Tschalär
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public
9  * License as published by the Free Software Foundation; either
10  * version 2 of the License, or (at your option) any later version.
11  *
12  * This library is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15  * Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public
18  * License along with this library; if not, write to the Free
19  * Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
20  * MA 02111-1307, USA
21  *
22  * For questions, suggestions, bug-reports, enhancement-requests etc.
23  * I may be contacted at:
24  *
25  * ronald@innovation.ch
26  *
27  */
28
29 package HTTPClient;
30
31 import java.io.IOException JavaDoc;
32
33
34 /**
35  * This is the interface that an Authorization handler must implement. You
36  * can implement your own auth handler to add support for auth schemes other
37  * than the ones handled by the default handler, to use a different UI for
38  * soliciting usernames and passwords, or for using an altogether different
39  * way of getting the necessary auth info.
40  *
41  * @see AuthorizationInfo#setAuthHandler(HTTPClient.AuthorizationHandler)
42  * @version 0.3-2 18/06/1999
43  * @author Ronald Tschalär
44  */
45
46 public interface AuthorizationHandler
47 {
48     /**
49      * This method is called whenever a 401 or 407 response is received and
50      * no candidate info is found in the list of known auth info. Usually
51      * this method will query the user for the necessary info.
52      *
53      * <P>If the returned info is not null it will be added to the list of
54      * known info. If the info is valid for more than one (host, port, realm,
55      * scheme) tuple then this method must add the corresponding auth infos
56      * itself.
57      *
58      * <P>This method must check <var>req.allow_ui</var> and only attempt
59      * user interaction if it's <var>true</var>.
60      *
61      * @param challenge the parsed challenge from the server; the host,
62      * port, scheme, realm and params are set to the
63      * values given by the server in the challenge.
64      * @param req the request which provoked this response.
65      * @param resp the full response.
66      * @return the authorization info to use when retrying the request,
67      * or null if the request is not to be retried. The necessary
68      * info includes the host, port, scheme and realm as given in
69      * the <var>challenge</var> parameter, plus either the basic
70      * cookie or any necessary params.
71      * @exception AuthSchemeNotImplException if the authorization scheme
72      * in the challenge cannot be handled.
73      */
74     AuthorizationInfo getAuthorization(AuthorizationInfo challenge,
75                        RoRequest req, RoResponse resp)
76         throws AuthSchemeNotImplException;
77
78
79     /**
80      * This method is called whenever auth info is chosen from the list of
81      * known info in the AuthorizationInfo class to be sent with a request.
82      * This happens when either auth info is being preemptively sent or if
83      * a 401 response is retrieved and a matching info is found in the list
84      * of known info. The intent of this method is to allow the handler to
85      * fix up the info being sent based on the actual request (e.g. in digest
86      * authentication the digest-uri, nonce and response-digest usually need
87      * to be recalculated).
88      *
89      * @param info the authorization info retrieved from the list of
90      * known info.
91      * @param req the request this info is targeted for.
92      * @param challenge the authorization challenge received from the server
93      * if this is in response to a 401, or null if we are
94      * preemptively sending the info.
95      * @param resp the full 401 response received, or null if we are
96      * preemptively sending the info.
97      * @return the authorization info to be sent with the request, or null
98      * if none is to be sent.
99      * @exception AuthSchemeNotImplException if the authorization scheme
100      * in the info cannot be handled.
101      */
102     AuthorizationInfo fixupAuthInfo(AuthorizationInfo info, RoRequest req,
103                    AuthorizationInfo challenge, RoResponse resp)
104         throws AuthSchemeNotImplException;
105
106
107     /**
108      * Sometimes even non-401 responses will contain headers pertaining to
109      * authorization (such as the "Authentication-Info" header). Therefore
110      * this method is invoked for each response received, even if it is not
111      * a 401 or 407 response. In case of a 401 or 407 response the methods
112      * <code>fixupAuthInfo()</code> and <code>getAuthorization()</code> are
113      * invoked <em>after</em> this method.
114      *
115      * @param resp the full Response
116      * @param req the Request which provoked this response
117      * @param prev the previous auth info sent, or null if none was sent
118      * @param prxy the previous proxy auth info sent, or null if none was sent
119      * @exception IOException if an exception occurs during the reading of
120      * the headers.
121      */
122     void handleAuthHeaders(Response resp, RoRequest req,
123                AuthorizationInfo prev, AuthorizationInfo prxy)
124         throws IOException JavaDoc;
125
126
127     /**
128      * This method is similar to <code>handleAuthHeaders</code> except that
129      * it is called if any headers in the trailer were sent. This also
130      * implies that it is invoked after any <code>fixupAuthInfo()</code> or
131      * <code>getAuthorization()</code> invocation.
132      *
133      * @param resp the full Response
134      * @param req the Request which provoked this response
135      * @param prev the previous auth info sent, or null if none was sent
136      * @param prxy the previous proxy auth info sent, or null if none was sent
137      * @exception IOException if an exception occurs during the reading of
138      * the trailers.
139      * @see #handleAuthHeaders(Response, RoRequest, AuthorizationInfo, AuthorizationInfo)
140      */
141     void handleAuthTrailers(Response resp, RoRequest req,
142                 AuthorizationInfo prev, AuthorizationInfo prxy)
143         throws IOException JavaDoc;
144 }
145
146
Popular Tags