com.devexperts.io

Class URLInputStream

java.lang.Object

java.io.InputStream

java.io.FilterInputStream

com.devexperts.io.URLInputStream

All Implemented Interfaces:

Closeable, AutoCloseable

public class URLInputStream
extends FilterInputStream

Convenient class that opens specified URL for reading. It supports all URL formats supported by Java and also understands file names using both local and absolute paths. It properly configures outgoing connections and releases all resources when closed.

To open HTTP resources use standard HTTP URL syntax:

• http://www.host.com/path/file.txt
• http://www.host.com:8080/images/picture.jpg
• https://www.host.com/mydata/secret.zip
• https://user:password@www.host.com/mydata/secret.zip

To open FTP resources use standard FTP URL syntax:

• ftp://ftp.host.com/path/file.zip - anonymous user, local path, default mode
• ftp://ftp.host.com/%2Fabsolute-path/file.zip - anonymous user, absolute path ('%2F' is quoted root '/'), default mode
• ftp://ftp.host.com/file.zip;type=i - anonymous user, local path, binary mode
• ftp://ftp.host.com/file.txt;type=a - anonymous user, local path, ASCII mode
• ftp://ftp.host.com/path/ - anonymous user, local path, UNIX-style file list
• ftp://ftp.host.com/path;type=d - anonymous user, local path, plain file list (includes 'path/' prefix)
• ftp://ftp.host.com/path/.;type=d - anonymous user, local path, plain file list (without prefix)
• ftp://user:password@ftp.host.com/file.zip - specified user, local path, default mode

To open file use either local file name or standard file URL syntax:

• data.txt
• path/data.txt
• /absolute-path/data.txt
• file:data.txt
• file:path/data.txt
• file:/absolute-path/data.txt
• file:/C:/absolute-path/data.txt

Field Summary

Fields

Modifier and Type	Field and Description
protected URLConnection	connection

Fields inherited from class java.io.FilterInputStream

in

Constructor Summary

Constructors

Constructor and Description
URLInputStream(String url) Creates a new URLInputStream instance for specified URL.
URLInputStream(URL url, AuthToken token, long ifModifiedSince) Creates a new URLInputStream instance for specified URL with specified credentials and specified If-Modified-Since request parameter.
URLInputStream(URL url, String user, String password) Creates a new URLInputStream instance for specified URL with specified credentials.
URLInputStream(URL url, String user, String password, long ifModifiedSince) Creates a new URLInputStream instance for specified URL with specified credentials and specified If-Modified-Since request parameter.

Method Summary

Modifier and Type	Method and Description
static void	checkConnectionResponseCode(URLConnection connection) Checks connection response code and throws IOException if it is not Ok.
void	close()
protected void	finalize()
URLConnection	getConnection() Returns URLConnection for this URLInputStream.
long	getLastModified() Returns last modification time from this URLInputStream.
static long	getLastModified(String url) Returns last modification time for specified URL.
static long	getLastModified(URL url, AuthToken token) Returns last modification time for specified URL with specified credentials.
static long	getLastModified(URL url, String user, String password) Returns last modification time for specified URL with specified credentials.
boolean	isModifiedSince() Determines whether content of this URLInputStream was modified according to If-Modified-Since request parameter specified at creation.
static URLConnection	openConnection(String url) Opens URLConnection for specified URL.
static URLConnection	openConnection(URL url, AuthToken token) Opens URLConnection for specified URL with specified credentials.
static URLConnection	openConnection(URL url, String user, String password) Opens URLConnection for specified URL with specified credentials.
byte[]	readAllBytes() Reads remaining content from this URLInputStream and returns it as a byte array.
static byte[]	readBytes(String url) Reads content for specified URL and returns it as a byte array.
static byte[]	readBytes(URL url, AuthToken token) Reads content for specified URL with specified credentials and returns it as a byte array.
static byte[]	readBytes(URL url, String user, String password) Reads content for specified URL with specified credentials and returns it as a byte array.
static byte[]	readURL(String url) Deprecated. use readBytes instead
static URL	resolveURL(String url) Resolves specified URL in the context of the current user directory.

Methods inherited from class java.io.FilterInputStream

available, mark, markSupported, read, read, read, reset, skip

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

connection

protected final URLConnection connection

Constructor Detail

URLInputStream

public URLInputStream(String url)
               throws IOException

Creates a new URLInputStream instance for specified URL.

This is a shortcut for URLInputStream(resolveURL(url), null, null).

Parameters:

url - the URL

Throws:

IOException - if an I/O error occurs

URLInputStream

public URLInputStream(URL url,
                      String user,
                      String password)
               throws IOException

Creates a new URLInputStream instance for specified URL with specified credentials. Credentials are used only if any of user or password is non-empty. Specified credentials take precedence over authentication information that is supplied to this method as part of URL user info like "http://user:password@host:port/path/file".

Parameters:

url - the URL

user - the username, may be null

password - the password, may be null

Throws:

IOException - if an I/O error occurs

URLInputStream

public URLInputStream(URL url,
                      String user,
                      String password,
                      long ifModifiedSince)
               throws IOException

Creates a new URLInputStream instance for specified URL with specified credentials and specified If-Modified-Since request parameter. Credentials are used only if any of user or password is non-empty. Specified credentials take precedence over authentication information that is supplied to this method as part of URL user info like "http://user:password@host:port/path/file". The If-Modified-Since time is used only when it is not 0.

Parameters:

url - the URL

user - the username, may be null

password - the password, may be null

ifModifiedSince - the If-Modified-Since time, may be 0

Throws:

IOException - if an I/O error occurs

URLInputStream

public URLInputStream(URL url,
                      AuthToken token,
                      long ifModifiedSince)
               throws IOException

Creates a new URLInputStream instance for specified URL with specified credentials and specified If-Modified-Since request parameter. Specified non-null token takes precedence over authentication information that is supplied to this method as part of URL user info like "http://user:password@host:port/path/file". The If-Modified-Since time is used only when it is not 0.

Parameters:

url - the URL

token - the token, may be null

ifModifiedSince - the If-Modified-Since time, may be 0

Throws:

IOException - if an I/O error occurs

Method Detail

resolveURL

public static URL resolveURL(String url)
                      throws MalformedURLException

Resolves specified URL in the context of the current user directory.

Parameters:

url - the URL

Returns:

resolved URL

Throws:

MalformedURLException - if URL cannot be parsed

openConnection

public static URLConnection openConnection(String url)
                                    throws IOException

Opens URLConnection for specified URL. This method resolves specified URL first, for a proper support of file name.

Use checkConnectionResponseCode after establishing connection to ensure that it was Ok.

This is a shortcut for openConnection(resolveURL(url), null, null).

Parameters:

url - the URL

Returns:

opened URLConnection

Throws:

IOException - if an I/O error occurs

openConnection

public static URLConnection openConnection(URL url,
                                           String user,
                                           String password)
                                    throws IOException

Opens URLConnection for specified URL with specified credentials. Credentials are used only if any of user or password is non-empty. Specified credentials take precedence over authentication information that is supplied to this method as part of URL user info like "http://user:password@host:port/path/file".

Use checkConnectionResponseCode after establishing connection to ensure that it was Ok.

Parameters:

url - the URL

user - the username, may be null

password - the password, may be null

Returns:

opened URLConnection

Throws:

IOException - if an I/O error occurs

openConnection

public static URLConnection openConnection(URL url,
                                           AuthToken token)
                                    throws IOException

Opens URLConnection for specified URL with specified credentials. Specified non-null token takes precedence over authentication information that is supplied to this method as part of URL user info like "http://user:password@host:port/path/file".

Use checkConnectionResponseCode after establishing connection to ensure that it was Ok.

Parameters:

url - the URL

token - the token, may be null

Returns:

opened URLConnection

Throws:

IOException - if an I/O error occurs

checkConnectionResponseCode

public static void checkConnectionResponseCode(URLConnection connection)
                                        throws IOException

Checks connection response code and throws IOException if it is not Ok.

Parameters:

connection - URLConnection

Throws:

IOException - if an I/O error occurs or if connection response code is not Ok

readURL

@Deprecated
public static byte[] readURL(String url)
                                  throws IOException

Deprecated. use readBytes instead

Reads content for specified URL and returns it as a byte array. This method resolves specified URL first, for a proper support of file name.

This is a shortcut for readBytes(resolveURL(url), null, null).

Parameters:

url - the URL

Returns:

the byte array with read content

Throws:

IOException - if an I/O error occurs

readBytes

public static byte[] readBytes(String url)
                        throws IOException

Reads content for specified URL and returns it as a byte array. This method resolves specified URL first, for a proper support of file name.

This is a shortcut for readBytes(resolveURL(url), null, null).

Parameters:

url - the URL

Returns:

the byte array with read content

Throws:

IOException - if an I/O error occurs

readBytes

public static byte[] readBytes(URL url,
                               String user,
                               String password)
                        throws IOException

Reads content for specified URL with specified credentials and returns it as a byte array. Credentials are used only if any of user or password is non-empty. Specified credentials take precedence over authentication information that is supplied to this method as part of URL user info like "http://user:password@host:port/path/file".

Parameters:

url - the URL

user - the username, may be null

password - the password, may be null

Returns:

the byte array with read content

Throws:

IOException - if an I/O error occurs

readBytes

public static byte[] readBytes(URL url,
                               AuthToken token)
                        throws IOException

Reads content for specified URL with specified credentials and returns it as a byte array. Specified non-null token takes precedence over authentication information that is supplied to this method as part of URL user info like "http://user:password@host:port/path/file".

Parameters:

url - the URL

token - the token, may be null

Returns:

the byte array with read content

Throws:

IOException - if an I/O error occurs

getLastModified

public static long getLastModified(String url)
                            throws IOException

Returns last modification time for specified URL. This method never returns 0.

This is a shortcut for getLastModified(resolveURL(url), null, null).

Parameters:

url - the URL

Returns:

last modification time

Throws:

IOException - if an I/O error occurs or if last modification time is not known

getLastModified

public static long getLastModified(URL url,
                                   String user,
                                   String password)
                            throws IOException

Returns last modification time for specified URL with specified credentials. This method never returns 0. Credentials are used only if any of user or password is non-empty. Specified credentials take precedence over authentication information that is supplied to this method as part of URL user info like "http://user:password@host:port/path/file".

Parameters:

url - the URL

user - the username, may be null

password - the password, may be null

Returns:

last modification time

Throws:

IOException - if an I/O error occurs or if last modification time is not known

getLastModified

public static long getLastModified(URL url,
                                   AuthToken token)
                            throws IOException

Returns last modification time for specified URL with specified credentials. This method never returns 0. Specified non-null token takes precedence over authentication information that is supplied to this method as part of URL user info like "http://user:password@host:port/path/file".

Parameters:

url - the URL

token - the token, may be null

Returns:

last modification time

Throws:

IOException - if an I/O error occurs or if last modification time is not known

getConnection

public URLConnection getConnection()

Returns URLConnection for this URLInputStream.

Returns:

URLConnection for this URLInputStream

getLastModified

public long getLastModified()

Returns last modification time from this URLInputStream. Returns 0 when last modification time is not known.

Returns:

last modification time from this URLInputStream or 0 if unknown

isModifiedSince

public boolean isModifiedSince()
                        throws IOException

Determines whether content of this URLInputStream was modified according to If-Modified-Since request parameter specified at creation.

Returns:

true if content was modified according to If-Modified-Since parameter, or parameter was not specified or was 0

Throws:

IOException - if an I/O error occurs

readAllBytes

public byte[] readAllBytes()
                    throws IOException

Reads remaining content from this URLInputStream and returns it as a byte array.

Returns:

the byte array with read content

Throws:

IOException - if an I/O error occurs

close

public void close()
           throws IOException

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Overrides:

close in class FilterInputStream

Throws:

IOException

finalize

protected void finalize()
                 throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable