URLConnection | Java In A Nutshell, 5th Edition

URLConnection

java.net

Java 1.0

This abstract class defines a network connection to an object specified by a URL. URL.openConnection( ) returns a URLConnection instance. You should use a URLConnection object when you want more control over the downloading of data than is available through the simpler URL methods . connect( ) actually establishes the network connection. Some methods must be called before the connection is made, and others depend on being connected. The methods that depend on being connected call connect( ) themselves if no connection exists yet, so you never need to call this method explicitly. The getContent( ) methods are just like the same-named methods of the URL class: they download the data referred to by the URL and parse it into an appropriate type of object (such as a string or an image). In Java 1.3 and later, there is a version of getContent( ) that allows you to specify the types of parsed objects that you are willing to accept by passing an array of Class objects. If you prefer to parse the URL content yourself instead of calling getContent( ) , you can call getInputStream( ) (and getOutputStream( ) if the URL protocol supports writing) to obtain a stream through which you can read (or write) data from (or to) the resource identified by the URL.

Before a connection is established, you may want to set request fields (such as HTTP request headers) to refine the URL request. Use setRequestProperty( ) to set a new value for a named header. In Java 1.4 and later, you can use addRequestProperty( ) to add a new comma-separated item to an existing header. Java 1.4 also added geTRequestProperties( ) , a method that returns the current set of request properties in the form of an unmodifiable Map object that maps request header names to List objects that contain the string value or values for the named header.

Once a connection has been established, there are a number of methods you can call to obtain information from the "response headers" of the URL. getContentLength( ) , getContentType( ) , getContentEncoding( ) , getExpiration( ) , getdate( ) , and getLastModified( ) return the appropriate information about the object referred to by the URL, if that information can be determined (e.g., from HTTP header fields). getHeaderField( ) returns an HTTP header field specified by name or by number. getHeaderFieldInt( ) and getHeaderFieldDate( ) return the value of a named header field parsed as an integer or a date. In Java 1.4 and later, getHeaderFields( ) returns an unmodifiable Map object that maps response header names to an unmodifiable List that contains the string value or values for the named header.

There are a number of options you can specify to control how the URLConnection behaves. These options are set with the various set( ) methods and may be queried with corresponding get( ) methods. The options must be set before the connect( ) method is called. setDoInput( ) and setDoOutput( ) allow you to specify whether you are using the URLConnection for input and/or output (input-only by default). setAllowUserInteraction( ) specifies whether user interaction (such as typing a password) is allowed during the data transfer ( false by default). setDefaultAllowUserInteraction( ) is a class method that allows you to change the default value for user interaction. setUseCaches( ) allows you to specify whether a cached version of the URL can be used. You can set this to false to force a URL to be reloaded. setDefaultUseCaches( ) sets the default value for setUseCaches( ) . setIfModifiedSince( ) allows you to specify that a URL should not be fetched unless it has been modified since a specified time (if it is possible to determine its modification date). In Java 5.0 and later, you can specify how long a URLConnection should wait while connecting or reading data with setConnectTimeout( ) and setReadTimeout( ) .

 public abstract class  URLConnection  {  // Protected Constructors  protected  URLConnection  (URL  url  );  // Public Class Methods  public static boolean  getDefaultAllowUserInteraction  ( );  1.1  public static FileNameMap  getFileNameMap  ( );  synchronized  public static String  guessContentTypeFromName  (String  fname  );       public static String  guessContentTypeFromStream  (java.io.InputStream  is  )       throws java.io.IOException;        public static void  setContentHandlerFactory  (ContentHandlerFactory  fac  );  synchronized  public static void  setDefaultAllowUserInteraction  (boolean  defaultallowuserinteraction  );  1.1  public static void  setFileNameMap  (FileNameMap  map  );  // Public Instance Methods   1.4  public void  addRequestProperty  (String  key  , String  value  );        public abstract void  connect  ( ) throws java.io.IOException;        public boolean  getAllowUserInteraction  ( );  5.0  public int  getConnectTimeout  ( );        public Object  getContent  ( ) throws java.io.IOException;  1.3  public Object  getContent  (Class[ ]  classes  ) throws java.io.IOException;        public String  getContentEncoding  ( );        public int  getContentLength  ( );        public String  getContentType  ( );        public long  getDate  ( );        public boolean  getDefaultUseCaches  ( );        public boolean  getDoInput  ( );        public boolean  getDoOutput  ( );        public long  getExpiration  ( );        public String  getHeaderField  (int  n  );  constant  public String  getHeaderField  (String  name  );  constant  public long  getHeaderFieldDate  (String  name  , long  Default  );        public int  getHeaderFieldInt  (String  name  , int  Default  );        public String  getHeaderFieldKey  (int  n  );  constant   1.4  public java.util.Map<String,java.util.List<String>>  getHeaderFields  ( );       public long  getIfModifiedSince  ( );        public java.io.InputStream  getInputStream  ( ) throws java.io.IOException;        public long  getLastModified  ( );        public java.io.OutputStream  getOutputStream  ( ) throws java.io.IOException;  1.2  public java.security.Permission  getPermission  ( )          throws java.io.IOException;  5.0  public int  getReadTimeout  ( );  1.4  public java.util.Map<String,java.util.List<String>>  getRequestProperties  ( );      public String  getRequestProperty  (String  key  );        public URL  getURL  ( );        public boolean  getUseCaches  ( );        public void  setAllowUserInteraction  (boolean  allowuserinteraction  );  5.0  public void  setConnectTimeout  (int  timeout  );        public void  setDefaultUseCaches  (boolean  defaultusecaches  );        public void  setDoInput  (boolean  doinput  );        public void  setDoOutput  (boolean  dooutput  );        public void  setIfModifiedSince  (long  ifmodifiedsince  );  5.0  public void  setReadTimeout  (int  timeout  );        public void  setRequestProperty  (String  key  , String  value  );        public void  setUseCaches  (boolean  usecaches  );  // Public Methods Overriding Object  public String  toString  ( );  // Protected Instance Fields  protected boolean  allowUserInteraction  ;        protected boolean  connected  ;        protected boolean  doInput  ;        protected boolean  doOutput  ;        protected long  ifModifiedSince  ;        protected URL  url  ;        protected boolean  useCaches  ;  // Deprecated Public Methods   #  public static String  getDefaultRequestProperty  (String  key  );  constant   #  public static void  setDefaultRequestProperty  (String  key  ,       String  value  );  empty  }

Subclasses

HttpURLConnection , JarURLConnection

Passed To

java.net.ContentHandler.getContent( ) , ResponseCache.put( )

Returned By

URL.openConnection( ) , URLStreamHandler.openConnection( )

Type Of

JarURLConnection.jarFileURLConnection