oracle.adfnmc.java.net
Class URLConnection

java.lang.Object
  oracle.adfnmc.java.net.URLConnection

public abstract class URLConnection
extends java.lang.Object

The URLConnection class is responsible for establishing a connection to an URL for a given protocol. The correct URLConnection subclass to call is determined by URLStreamHandler.openConnection().

Field Summary

protected boolean	allowUserInteraction
protected boolean	connected
protected boolean	doInput
protected boolean	doOutput
protected long	ifModifiedSince
protected URL	url
protected boolean	useCaches

Constructor Summary

protected

URLConnection(URL url) Creates a URLConnection pointing to the resource specified by the url

Method Summary

void	addRequestProperty(java.lang.String field, java.lang.String newValue) Adds the given request property.
abstract void	connect() Establishes the connection to the resource specified by this URL with this method, along with other options that can only be set before this connection is made.
boolean	getAllowUserInteraction() Answers the value of allowUserInteraction which indicates if this connection allows user interaction
int	getConnectTimeout() Returns a timeout of connection by milliseconds
java.lang.Object	getContent() Answers the object pointed to by this URL.
java.lang.Object	getContent(java.lang.Class[] types) Answers the object pointed to by this URL.
java.lang.String	getContentEncoding() Answers the Content encoding type of the response body, null if no such field is found in the header response.
int	getContentLength() Answers the length of the content or body in the response header in bytes.
java.lang.String	getContentType() Answers the type of the content.
long	getDate() Answers the date in milliseconds since epoch when this response header was created, or 0 if the field Date is not found in the header.
static boolean	getDefaultAllowUserInteraction() Answers whether this connection allow user interaction by default.
static java.lang.String	getDefaultRequestProperty(java.lang.String field) Deprecated. Use getRequestProperty().
boolean	getDefaultUseCaches() Answers whether this connection use caches by default.
boolean	getDoInput() Answers whether this connection supports input.
boolean	getDoOutput() Answers whether this connection supports output.
long	getExpiration() Answers the date in milliseconds since epoch when this response header expires or 0 if the field Expires is not found in the header.
static FileNameMap	getFileNameMap() Answers the MIME table of this URL connection.
java.lang.String	getHeaderField(int pos) Answers the value of the field at position pos.
java.lang.String	getHeaderField(java.lang.String key) Answers the value of the field corresponding to the key Answers null if there is no such field.
long	getHeaderFieldDate(java.lang.String field, long defaultValue) Answers the date value in the form of milliseconds since epoch corresponding to the field field.
int	getHeaderFieldInt(java.lang.String field, int defaultValue) Answers the integer value of the specified field.
java.lang.String	getHeaderFieldKey(int posn) Answers the name of the field at position specified by posn, null if there are fewer than posn fields.
Map	getHeaderFields() Provides an unmodifiable map of the connection header values.
long	getIfModifiedSince() Answers the value of ifModifiedSince of this connection in milliseconds since epoch
java.io.InputStream	getInputStream() Creates an InputStream for reading from this URL Connection.
long	getLastModified() Answers the value of the field Last-Modified in the response header, 0 if no such field exists
java.io.OutputStream	getOutputStream() Creates an OutputStream for writing to this URL Connection.
oracle.adfnmc.java.security.Permission	getPermission() Answers the permissions necessary to make the connection.
int	getReadTimeout() Returns a timeout of reading by milliseconds
Map	getRequestProperties() Provides an unmodifiable map of the request properties.
java.lang.String	getRequestProperty(java.lang.String field) Answers the value corresponding to the field in the request Header, null if no such field exists.
URL	getURL() Answers the URL of this connection
boolean	getUseCaches() Answers whether this connection uses caches
static java.lang.String	guessContentTypeFromName(java.lang.String url) Determines the MIME type of the file specified by the string URL, using the filename extension.
static java.lang.String	guessContentTypeFromStream(java.io.InputStream is) Examines the bytes of the input stream and returns the MIME type, null if no content type can be deduced.
void	setAllowUserInteraction(boolean newValue) Sets the flag indicating whether this connection allows user interaction This can only be called prior to connection establishment.
void	setConnectTimeout(int timeout) Sets a timeout for connection to perform non-block.
static void	setContentHandlerFactory(ContentHandlerFactory contentFactory) Sets the current content handler factory to be contentFactory.
static void	setDefaultAllowUserInteraction(boolean allows) Set whether user interaction is allowed by default.
static void	setDefaultRequestProperty(java.lang.String field, java.lang.String value) Deprecated. Use getRequestProperty().
void	setDefaultUseCaches(boolean newValue) Set whether caches are used by default.
void	setDoInput(boolean newValue) Sets whether this URLConnection allows input.
void	setDoOutput(boolean newValue) Sets whether this URLConnection allows output.
static void	setFileNameMap(FileNameMap map) With permission from the security manager, this method sets the map to be the MIME Table of this URL connection.
void	setIfModifiedSince(long newValue) Sets the header field ifModifiedSince.
void	setReadTimeout(int timeout) Sets a timeout for reading to perform non-block.
void	setRequestProperty(java.lang.String field, java.lang.String newValue) Sets the value of the request header field field to newValue Only the current URL Connection is affected.
void	setUseCaches(boolean newValue) Sets the flag indicating if this connection uses caches.
java.lang.String	toString() Answers the name of the class of the URLConnection

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

url

protected URL url

ifModifiedSince

protected long ifModifiedSince

useCaches

protected boolean useCaches

connected

protected boolean connected

doOutput

protected boolean doOutput

doInput

protected boolean doInput

allowUserInteraction

protected boolean allowUserInteraction

Constructor Detail

URLConnection

protected URLConnection(URL url)

Creates a URLConnection pointing to the resource specified by the url

Method Detail

connect

public abstract void connect()
                      throws java.io.IOException

Establishes the connection to the resource specified by this URL with this method, along with other options that can only be set before this connection is made.

Throws:

java.io.IOException - If an error occurs while connecting

See Also:

IOException, URLStreamHandler

getAllowUserInteraction

public boolean getAllowUserInteraction()

Answers the value of allowUserInteraction which indicates if this connection allows user interaction

Returns:

the value of the flag

See Also:

getDefaultRequestProperty(java.lang.String), setDefaultRequestProperty(java.lang.String, java.lang.String), allowUserInteraction

getContent

public java.lang.Object getContent()
                            throws java.io.IOException

Answers the object pointed to by this URL. It first attempts to get the content type from getContentType(), which looks for the response header field "Content-Type". If none is found, it will guess the content type from the filename extension. If that fails, it will guess by inspecting the stream.

Returns:

a non-null object

Throws:

java.io.IOException - if an IO error occurred

See Also:

ContentHandler, ContentHandlerFactory, IOException, setContentHandlerFactory(oracle.adfnmc.java.net.ContentHandlerFactory)

getContent

public java.lang.Object getContent(java.lang.Class[] types)
                            throws java.io.IOException

Answers the object pointed to by this URL. It first attempts to get the content type from getContentType(), which looks for the response header field "Content-Type". If none is found, it will guess the content type from the filename extension. If that fails, it will guess by inspecting the stream.

Parameters:

types - The list of acceptable content types

Returns:

Object The object of the resource pointed by this URL, or null if the content does not match a specified content type.

Throws:

java.io.IOException - If an error occurred obtaining the content.

getContentEncoding

public java.lang.String getContentEncoding()

Answers the Content encoding type of the response body, null if no such field is found in the header response.

Returns:

The content encoding type

See Also:

getContentType()

getContentLength

public int getContentLength()

Answers the length of the content or body in the response header in bytes. Answer -1 if Content-Length cannot be found in the response header.

Returns:

The length of the content

See Also:

getContentType()

getContentType

public java.lang.String getContentType()

Answers the type of the content. Answers null if there's no such field.

Returns:

The type of the content

See Also:

guessContentTypeFromName(java.lang.String), guessContentTypeFromStream(java.io.InputStream)

getDate

public long getDate()

Answers the date in milliseconds since epoch when this response header was created, or 0 if the field Date is not found in the header.

Returns:

Date in millisecond since epoch

See Also:

getExpiration(), getLastModified(), Date

getDefaultAllowUserInteraction

public static boolean getDefaultAllowUserInteraction()

Answers whether this connection allow user interaction by default.

Returns:

the value of defaultAllowUserInteraction

See Also:

getAllowUserInteraction(), setDefaultAllowUserInteraction(boolean), setAllowUserInteraction(boolean), allowUserInteraction

getDefaultRequestProperty

public static java.lang.String getDefaultRequestProperty(java.lang.String field)

Deprecated. Use getRequestProperty().

Answers the default value for the field specified by field, null if there's no such field.

Parameters:

field - the field to get the request property for

Returns:

the field to be looked up

getDefaultUseCaches

public boolean getDefaultUseCaches()

Answers whether this connection use caches by default.

Returns:

true if this connection use caches by default, false otherwise

See Also:

getUseCaches(), setDefaultUseCaches(boolean), setUseCaches(boolean), useCaches

getDoInput

public boolean getDoInput()

Answers whether this connection supports input.

Returns:

true if this connection supports input, false otherwise

See Also:

setDoInput(boolean), doInput

getDoOutput

public boolean getDoOutput()

Answers whether this connection supports output.

Returns:

true if this connection supports output, false otherwise

See Also:

setDoOutput(boolean), doOutput

getExpiration

public long getExpiration()

Answers the date in milliseconds since epoch when this response header expires or 0 if the field Expires is not found in the header.

Returns:

Date in milliseconds since epoch

See Also:

getHeaderField(int), getHeaderField(String), getHeaderFieldDate(String, long), getHeaderFieldInt(String, int), getHeaderFieldKey(int)

getFileNameMap

public static FileNameMap getFileNameMap()

Answers the MIME table of this URL connection.

Returns:

FileNameMap

getHeaderField

public java.lang.String getHeaderField(int pos)

Answers the value of the field at position pos. Answers null if there are fewer than pos fields in the response header.

Parameters:

pos - the position of the field

Returns:

The value of the field

See Also:

getHeaderFieldDate(java.lang.String, long), getHeaderFieldInt(java.lang.String, int), getHeaderFieldKey(int)

getHeaderFields

public Map getHeaderFields()

Provides an unmodifiable map of the connection header values. The map keys are the String header field names. Each map value is a List of the header field values associated with that key name.

Returns:

the mapping of header field names to values

Since:

1.4

getRequestProperties

public Map getRequestProperties()

Provides an unmodifiable map of the request properties. The map keys are Strings, the map values are each a List of Strings, with each request property name mapped to its corresponding property values.

Returns:

the mapping of request property names to values

Since:

1.4

addRequestProperty

public void addRequestProperty(java.lang.String field,
                               java.lang.String newValue)

Adds the given request property. Will not overwrite any existing properties associated with the given field name.

Parameters:

field - the request property field name

newValue - the property value

Throws:

java.lang.IllegalStateException - - if connection already established

java.lang.NullPointerException - - if field is null

Since:

1.4

getHeaderField

public java.lang.String getHeaderField(java.lang.String key)

Answers the value of the field corresponding to the key Answers null if there is no such field.

Parameters:

key - the name of the header field

Returns:

The value of the header field

See Also:

getHeaderFieldDate(java.lang.String, long), getHeaderFieldInt(java.lang.String, int), getHeaderFieldKey(int)

getHeaderFieldDate

public long getHeaderFieldDate(java.lang.String field,
                               long defaultValue)

Answers the date value in the form of milliseconds since epoch corresponding to the field field. Answers defaultValue if no such field can be found in the response header.

Parameters:

field - the field in question

defaultValue - the default value if no field is found or the value is invalid

Returns:

milliseconds since epoch

See Also:

ifModifiedSince, setIfModifiedSince(long)

getHeaderFieldInt

public int getHeaderFieldInt(java.lang.String field,
                             int defaultValue)

Answers the integer value of the specified field. Answers default value defaultValue if no such field exists.

Parameters:

field - the field to return

defaultValue - to be returned if field> does not exist

Returns:

value of the field

getHeaderFieldKey

public java.lang.String getHeaderFieldKey(int posn)

Answers the name of the field at position specified by posn, null if there are fewer than posn fields.

Parameters:

posn - the position to look for; the first field being 0

Returns:

the name of the field

See Also:

getHeaderFieldDate(java.lang.String, long), getHeaderFieldInt(java.lang.String, int), getHeaderField(int), getHeaderField(String), getHeaderFieldDate(String, long), getHeaderFieldInt(String, int), getHeaderFieldKey(int)

getIfModifiedSince

public long getIfModifiedSince()

Answers the value of ifModifiedSince of this connection in milliseconds since epoch

Returns:

the time since epoch

See Also:

ifModifiedSince, setIfModifiedSince(long)

getInputStream

public java.io.InputStream getInputStream()
                                   throws java.io.IOException

Creates an InputStream for reading from this URL Connection. It throws UnknownServiceException by default. This method should be overridden by its subclasses

Returns:

The InputStream to read from

Throws:

java.io.IOException - If an InputStream could not be created

See Also:

getContent(), getContent(Class[]), getOutputStream(), InputStream, IOException

getLastModified

public long getLastModified()

Answers the value of the field Last-Modified in the response header, 0 if no such field exists

Returns:

the value of the field last modified

See Also:

Date, getDate(), getExpiration()

getOutputStream

public java.io.OutputStream getOutputStream()
                                     throws java.io.IOException

Creates an OutputStream for writing to this URL Connection. It throws UnknownServiceException by default. This method should be overridden by subclasses.

Returns:

The OutputStream to write to

Throws:

java.io.IOException - If an OutputStream could not be created

See Also:

getContent(), getContent(Class[]), getInputStream(), IOException

getPermission

public oracle.adfnmc.java.security.Permission getPermission()
                                                     throws java.io.IOException

Answers the permissions necessary to make the connection. Depending on the protocol, this can be any of the permission subclasses. The permission returned may also depend on the state of the connection, E.G In the case of HTTP, redirection can change the applicable permission if the host changed.

By default, this methods returns AllPermission. Subclasses should override this and return the appropriate permission object.

Returns:

the permission object governing the connection

Throws:

java.io.IOException - if an IO exception occurs during the creation of the permission object.

getRequestProperty

public java.lang.String getRequestProperty(java.lang.String field)

Answers the value corresponding to the field in the request Header, null if no such field exists.

Parameters:

field - the field to get the property for

Returns:

the field to look up

Throws:

java.lang.IllegalStateException - - if connection already established

See Also:

getDefaultRequestProperty(java.lang.String), setDefaultRequestProperty(java.lang.String, java.lang.String), setRequestProperty(java.lang.String, java.lang.String)

getURL

public URL getURL()

Answers the URL of this connection

Returns:

the URL of this connection

See Also:

URL, URLConnection(URL)

getUseCaches

public boolean getUseCaches()

Answers whether this connection uses caches

Returns:

the value of the flag

guessContentTypeFromName

public static java.lang.String guessContentTypeFromName(java.lang.String url)

Determines the MIME type of the file specified by the string URL, using the filename extension. Any fragment identifier is removed before processing.

Parameters:

url - the MIME type of the file.

Returns:

the string representation of an URL

See Also:

FileNameMap, FileNameMap.getContentTypeFor(String), getContentType(), guessContentTypeFromStream(java.io.InputStream)

guessContentTypeFromStream

public static java.lang.String guessContentTypeFromStream(java.io.InputStream is)
                                                   throws java.io.IOException

Examines the bytes of the input stream and returns the MIME type, null if no content type can be deduced.

Parameters:

is - the input stream for the URL

Returns:

the type of the input stream

Throws:

java.io.IOException - If an IO error occurs

setAllowUserInteraction

public void setAllowUserInteraction(boolean newValue)

Sets the flag indicating whether this connection allows user interaction This can only be called prior to connection establishment.

Parameters:

newValue - the value of the flag to be set

Throws:

java.lang.IllegalStateException - if this method attempts to change the flag after a connection has been established

setContentHandlerFactory

public static void setContentHandlerFactory(ContentHandlerFactory contentFactory)

Sets the current content handler factory to be contentFactory. It can only do so with the permission of the security manager. The ContentFactory can only be specified once during the lifetime of an application.

Parameters:

contentFactory - the factory

Throws:

java.lang.Error - if a ContentFactory has been created before SecurityException if the security manager does not allow this action

See Also:

ContentHandler, ContentHandlerFactory, SecurityException, java.lang.SecurityManager#checkSetFactory()

setDefaultAllowUserInteraction

public static void setDefaultAllowUserInteraction(boolean allows)

Set whether user interaction is allowed by default. Existing URLConnections are unaffected.

Parameters:

allows - allow user interaction

setDefaultRequestProperty

public static void setDefaultRequestProperty(java.lang.String field,
                                             java.lang.String value)

Deprecated. Use getRequestProperty().

Sets the field in the default request header with the value value

Parameters:

field - the request header field to be set

value - the new value

setDefaultUseCaches

public void setDefaultUseCaches(boolean newValue)

Set whether caches are used by default. Existing URLConnections are unaffected.

Parameters:

newValue - the value of the flag to be set

See Also:

getDefaultUseCaches(), getUseCaches(), setUseCaches(boolean), useCaches

setDoInput

public void setDoInput(boolean newValue)

Sets whether this URLConnection allows input. It cannot be set after the connection is made.

Parameters:

newValue - boolean

Throws:

IllegalAccessError - Exception thrown when this method attempts to change the value after connected

See Also:

doInput, getDoInput(), setDoInput(boolean), java.lang.IllegalAccessError

setDoOutput

public void setDoOutput(boolean newValue)

Sets whether this URLConnection allows output. It cannot be set after the connection is made.

Parameters:

newValue - boolean

Throws:

IllegalAccessError - Exception thrown when this method attempts to change the value after connected

See Also:

doOutput, getDoOutput(), setDoOutput(boolean), java.lang.IllegalAccessError

setFileNameMap

public static void setFileNameMap(FileNameMap map)

With permission from the security manager, this method sets the map to be the MIME Table of this URL connection.

Parameters:

map - the MIME table to be set.

setIfModifiedSince

public void setIfModifiedSince(long newValue)

Sets the header field ifModifiedSince.

Parameters:

newValue - number of milliseconds since epoch

Throws:

java.lang.IllegalStateException - if already connected.

setRequestProperty

public void setRequestProperty(java.lang.String field,
                               java.lang.String newValue)

Sets the value of the request header field field to newValue Only the current URL Connection is affected. It can only be called before the connection is made

Parameters:

field - the field

newValue - the field's new value

Throws:

java.lang.IllegalStateException - - if connection already established

java.lang.NullPointerException - - if field is null

See Also:

getDefaultRequestProperty(java.lang.String), setDefaultRequestProperty(java.lang.String, java.lang.String), getRequestProperty(java.lang.String)

setUseCaches

public void setUseCaches(boolean newValue)

Sets the flag indicating if this connection uses caches. This value cannot be set after the connection is made.

Parameters:

newValue - the value of the flag to be set

Throws:

java.lang.IllegalStateException - Exception thrown when this method attempts to change the value after connected

See Also:

getDefaultUseCaches(), setDefaultUseCaches(boolean), getUseCaches(), useCaches

setConnectTimeout

public void setConnectTimeout(int timeout)

Sets a timeout for connection to perform non-block. Default is zero. Timeout of zero means infinite.

Parameters:

timeout - timeout for connection in milliseconds.

Throws:

java.lang.IllegalArgumentException - if timeout is less than zero.

getConnectTimeout

public int getConnectTimeout()

Returns a timeout of connection by milliseconds

Returns:

timeout of connection by milliseconds

setReadTimeout

public void setReadTimeout(int timeout)

Sets a timeout for reading to perform non-block. Default is zero. Timeout of zero means infinite.

Parameters:

timeout - timeout for reading in milliseconds.

Throws:

java.lang.IllegalArgumentException - if timeout is less than zero.

getReadTimeout

public int getReadTimeout()

Returns a timeout of reading by milliseconds

Returns:

timeout of reading by milliseconds

toString

public java.lang.String toString()

Answers the name of the class of the URLConnection

Overrides:

toString in class java.lang.Object

Returns:

The string representation of this URLConnection

See Also:

getURL(), URLConnection(URL)