KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > net > ssl > HttpsURLConnection


1 /*
2  * @(#)HttpsURLConnection.java 1.13 04/02/16
3  *
4  * Copyright (c) 2004 Sun Microsystems, Inc. All Rights Reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7   
8 /*
9  * NOTE:
10  * Because of various external restrictions (i.e. US export
11  * regulations, etc.), the actual source code can not be provided
12  * at this time. This file represents the skeleton of the source
13  * file, so that javadocs of the API can be created.
14  */
15
16 package javax.net.ssl;
17
18 import java.net.URL;
19 import java.net.HttpURLConnection;
20 import java.security.Principal;
21 import java.security.cert.X509Certificate;
22 import javax.security.auth.x500.X500Principal;
23
24 /**
25  * <code>HttpsURLConnection</code> extends <code>HttpURLConnection</code>
26  * with support for https-specific features.
27  * <P>
28  * See <A HREF="http://www.w3.org/pub/WWW/Protocols/">
29  * http://www.w3.org/pub/WWW/Protocols/</A> and
30  * <A HREF="http://www.ietf.org/"> RFC 2818 </A>
31  * for more details on the
32  * https specification.
33  * <P>
34  * This class uses <code>HostnameVerifier</code> and
35  * <code>SSLSocketFactory</code>.
36  * There are default implementations defined for both classes.
37  * However, the implementations can be replaced on a per-class (static) or
38  * per-instance basis. All new <code>HttpsURLConnection</code>s instances
39  * will be assigned
40  * the "default" static values at instance creation, but they can be overriden
41  * by calling the appropriate per-instance set method(s) before
42  * <code>connect</code>ing.
43  *
44  * @since 1.4
45  * @version 1.25
46  */
47 public abstract class HttpsURLConnection extends HttpURLConnection
48 {
49     /**
50      * The <code>hostnameVerifier</code> for this object.
51      */
52     protected HostnameVerifier hostnameVerifier;
53
54     /**
55      * Creates an <code>HttpsURLConnection</code> using the
56      * URL specified.
57      *
58      * @param url the URL
59      */
60     protected HttpsURLConnection(URL url) { }
61
62     /**
63      * Returns the cipher suite in use on this connection.
64      *
65      * @return the cipher suite
66      * @throws IllegalStateException if this method is called before
67      * the connection has been established.
68      */
69     public abstract String getCipherSuite();
70
71     /**
72      * Returns the certificate(s) that were sent to the server during
73      * handshaking.
74      * <P>
75      * Note: This method is useful only when using certificate-based
76      * cipher suites.
77      * <P>
78      * When multiple certificates are available for use in a
79      * handshake, the implementation chooses what it considers the
80      * "best" certificate chain available, and transmits that to
81      * the other side. This method allows the caller to know
82      * which certificate chain was actually sent.
83      *
84      * @return an ordered array of certificates,
85      * with the client's own certificate first followed by any
86      * certificate authorities. If no certificates were sent,
87      * then null is returned.
88      * @throws IllegalStateException if this method is called before
89      * the connection has been established.
90      * @see #getLocalPrincipal()
91      */
92     public abstract java.security.cert.Certificate[] getLocalCertificates();
93
94     /**
95      * Returns the server's certificate chain which was established
96      * as part of defining the session.
97      * <P>
98      * Note: This method can be used only when using certificate-based
99      * cipher suites; using it with non-certificate-based cipher suites,
100      * such as Kerberos, will throw an SSLPeerUnverifiedException.
101      *
102      * @return an ordered array of server certificates,
103      * with the peer's own certificate first followed by
104      * any certificate authorities.
105      * @throws SSLPeerUnverifiedException if the peer is not verified.
106      * @throws IllegalStateException if this method is called before
107      * the connection has been established.
108      * @see #getPeerPrincipal()
109      */
110     public abstract java.security.cert.Certificate[] getServerCertificates()
111         throws SSLPeerUnverifiedException;
112
113     /**
114      * Returns the server's principal which was established as part of
115      * defining the session.
116      * <P>
117      * Note: Subclasses should override this method. If not overridden, it
118      * will default to returning the X500Principal of the server's end-entity
119      * certificate for certificate-based ciphersuites, or throw an
120      * SSLPeerUnverifiedException for non-certificate based ciphersuites,
121      * such as Kerberos.
122      *
123      * @return the server's principal. Returns an X500Principal of the
124      * end-entity certiticate for X509-based cipher suites, and
125      * KerberosPrincipal for Kerberos cipher suites.
126      *
127      * @throws SSLPeerUnverifiedException if the peer was not verified
128      * @throws IllegalStateException if this method is called before
129      * the connection has been established.
130      *
131      * @see #getServerCertificates()
132      * @see #getLocalPrincipal()
133      *
134      * @since 1.5
135      */
136     public Principal getPeerPrincipal() throws SSLPeerUnverifiedException {
137         return null;
138     }
139
140     /**
141      * Returns the principal that was sent to the server during handshaking.
142      * <P>
143      * Note: Subclasses should override this method. If not overridden, it
144      * will default to returning the X500Principal of the end-entity certificate
145      * that was sent to the server for certificate-based ciphersuites or,
146      * return null for non-certificate based ciphersuites, such as Kerberos.
147      *
148      * @return the principal sent to the server. Returns an X500Principal
149      * of the end-entity certificate for X509-based cipher suites, and
150      * KerberosPrincipal for Kerberos cipher suites. If no principal was
151      * sent, then null is returned.
152      *
153      * @throws IllegalStateException if this method is called before
154      * the connection has been established.
155      *
156      * @see #getLocalCertificates()
157      * @see #getPeerPrincipal()
158      *
159      * @since 1.5
160      */
161     public Principal getLocalPrincipal() {
162         return null;
163     }
164
165     /**
166      * Sets the default <code>HostnameVerifier</code> inherited by a
167      * new instance of this class.
168      * <P>
169      * If this method is not called, the default
170      * <code>HostnameVerifier</code> assumes the connection should not
171      * be permitted.
172      *
173      * @param v the default host name verifier
174      * @throws IllegalArgumentException if the <code>HostnameVerifier</code>
175      * parameter is null.
176      * @see #getDefaultHostnameVerifier()
177      */
178     public static void setDefaultHostnameVerifier(HostnameVerifier v) { }
179
180     /**
181      * Gets the default <code>HostnameVerifier</code> that is inherited
182      * by new instances of this class.
183      *
184      * @return the default host name verifier
185      * @see #setDefaultHostnameVerifier(HostnameVerifier)
186      */
187     public static HostnameVerifier getDefaultHostnameVerifier() {
188         return null;
189     }
190
191     /**
192      * Sets the <code>HostnameVerifier</code> for this instance.
193      * <P>
194      * New instances of this class inherit the default static hostname
195      * verifier set by {@link #setDefaultHostnameVerifier(HostnameVerifier)
196      * setDefaultHostnameVerifier}. Calls to this method replace
197      * this object's <code>HostnameVerifier</code>.
198      *
199      * @param v the host name verifier
200      * @throws IllegalArgumentException if the <code>HostnameVerifier</code>
201      * parameter is null.
202      * @see #getHostnameVerifier()
203      * @see #setDefaultHostnameVerifier(HostnameVerifier)
204      */
205     public void setHostnameVerifier(HostnameVerifier v) { }
206
207     /**
208      * Gets the <code>HostnameVerifier</code> in place on this instance.
209      *
210      * @return the host name verifier
211      * @see #setHostnameVerifier(HostnameVerifier)
212      * @see #setDefaultHostnameVerifier(HostnameVerifier)
213      */
214     public HostnameVerifier getHostnameVerifier() {
215         return null;
216     }
217
218     /**
219      * Sets the default <code>SSLSocketFactory</code> inherited by new
220      * instances of this class.
221      * <P>
222      * The socket factories are used when creating sockets for secure
223      * https URL connections.
224      *
225      * @param sf the default SSL socket factory
226      * @throws IllegalArgumentException if the SSLSocketFactory
227      * parameter is null.
228      * @see #getDefaultSSLSocketFactory()
229      */
230     public static void setDefaultSSLSocketFactory(SSLSocketFactory sf) { }
231
232     /**
233      * Gets the default static <code>SSLSocketFactory</code> that is
234      * inherited by new instances of this class.
235      * <P>
236      * The socket factories are used when creating sockets for secure
237      * https URL connections.
238      *
239      * @return the default <code>SSLSocketFactory</code>
240      * @see #setDefaultSSLSocketFactory(SSLSocketFactory)
241      */
242     public static SSLSocketFactory getDefaultSSLSocketFactory() {
243         return null;
244     }
245
246     /**
247      * Sets the <code>SSLSocketFactory</code> to be used when this instance
248      * creates sockets for secure https URL connections.
249      * <P>
250      * New instances of this class inherit the default static
251      * <code>SSLSocketFactory</code> set by
252      * {@link #setDefaultSSLSocketFactory(SSLSocketFactory)
253      * setDefaultSSLSocketFactory}. Calls to this method replace
254      * this object's <code>SSLSocketFactory</code>.
255      *
256      * @param sf the SSL socket factory
257      * @throws IllegalArgumentException if the <code>SSLSocketFactory</code>
258      * parameter is null.
259      * @see #getSSLSocketFactory()
260      */
261     public void setSSLSocketFactory(SSLSocketFactory sf) { }
262
263     /**
264      * Gets the SSL socket factory to be used when creating sockets
265      * for secure https URL connections.
266      *
267      * @return the <code>SSLSocketFactory</code>
268      * @see #setSSLSocketFactory(SSLSocketFactory)
269      */
270     public SSLSocketFactory getSSLSocketFactory() {
271         return null;
272     }
273 }
274
Popular Tags