org.crosswire.common.util

## Class NetUtil

- java.lang.Object
- - org.crosswire.common.util.NetUtil

-     public final class NetUtil
      extends Object

  The NetUtil class looks after general utility stuff around the java.net package.
  Author:
    Joe Walker, Mark Goodwin, DM Smith
  See Also:
    `The GNU Lesser General Public License for details.`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `NetUtil.IsDirectoryURIFilter` Check that the directories in the version directory really represent versions.
    `static class` | `NetUtil.URIFilterFilenameFilter` Quick implementation of FilenameFilter that uses a URIFilter

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `AUTH_SEPERATOR_PASSWORD` Separating the password from the username
    `static String` | `AUTH_SEPERATOR_USERNAME` Separating the username from the rest of the URL/URI
    `private static File` | `cachedir` Where are temporary files cached.
    `static String` | `INDEX_FILE` For directory listings
    `private static org.slf4j.Logger` | `LOGGER` The log stream
    `static String` | `PROTOCOL_FILE` Constant for the file: protocol or scheme
    `static String` | `PROTOCOL_FTP` Constant for the ftp: protocol or scheme
    `static String` | `PROTOCOL_HTTP` Constant for the http: protocol or scheme
    `static String` | `PROTOCOL_JAR` Constant for the jar: protocol or scheme
    `static String` | `SEPARATOR` URL/URI separator
    `private static String` | `TEMP_SUFFIX` The temporary suffix, used when a temporary file is needed in the system's temporary directory.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `private` | `NetUtil()` Basic constructor - ensure that we can't be instantiated

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static boolean` | `canRead(URI orig)` If there is a readable directory or file at the other end of this URI return true.
    `static boolean` | `canWrite(URI orig)` If there is a writable directory or file at the other end of this URI return true.
    `private static void` | `checkFileURI(URI uri)` Throw if the given URI does not use the 'file:' protocol
    `static URI` | `copy(URI uri)`
    `static boolean` | `delete(URI orig)` Delete a URI.
    `static File` | `getAsFile(URI uri)` Return a File from the URI either by extracting from a file: URI or by downloading to a temp dir first
    `static InputStream` | `getInputStream(URI uri)` Attempt to obtain an InputStream from a URI.
    `static long` | `getLastModified(URI uri)` When was the given URI last modified.
    `static long` | `getLastModified(URI uri, String proxyHost)` When was the given URI last modified.
    `static long` | `getLastModified(URI uri, String proxyHost, Integer proxyPort)` When was the given URI last modified.
    `static OutputStream` | `getOutputStream(URI uri)` Attempt to obtain an OutputStream from a URI.
    `static OutputStream` | `getOutputStream(URI uri, boolean append)` Attempt to obtain an OutputStream from a URI.
    `static int` | `getSize(URI uri)`
    `static int` | `getSize(URI uri, String proxyHost)`
    `static int` | `getSize(URI uri, String proxyHost, Integer proxyPort)`
    `static URI` | `getTemporaryURI(String prefix, String suffix)` A URI version of `File.createTempFile()`
    `static URI` | `getURI(File file)` Get a URI version of the given file.
    `static File` | `getURICacheDir()` Returns the cache directory.
    `static boolean` | `isDirectory(URI orig)` If there is a directory at the other end of this URI return true.
    `static boolean` | `isFile(URI uri)` If there is a file at the other end of this URI return true.
    `static boolean` | `isNewer(URI left, URI right)` Returns whether the left is newer than the right by comparing their last modified dates.
    `static boolean` | `isNewer(URI left, URI right, String proxyHost)` Returns whether the left is newer than the right by comparing their last modified dates.
    `static boolean` | `isNewer(URI left, URI right, String proxyHost, Integer proxyPort)` Returns whether the left is newer than the right by comparing their last modified dates.
    `private static boolean` | `isSeparator(char c)`
    `static URI` | `lengthenURI(URI orig, String anExtra)` Utility to add a string to the end of a URI.
    `static String[]` | `list(URI uri, URIFilter filter)` List the items available assuming that this URI points to a directory.
    `static String[]` | `listByFile(URI uri, URIFilter filter)` List all the files specified by the index file passed in.
    `static String[]` | `listByIndexFile(URI index)` List all the strings specified by the index file passed in.
    `static String[]` | `listByIndexFile(URI index, URIFilter filter)` List all the files specified by the index file passed in.
    `static PropertyMap` | `loadProperties(URI uri)` Load up properties given by a URI.
    `static void` | `makeDirectory(URI orig)` If the directory does not exist, create it.
    `static void` | `makeFile(URI orig)` If the file does not exist, create it.
    `static boolean` | `move(URI oldUri, URI newUri)` Move a URI from one place to another.
    `static void` | `setURICacheDir(File cachedir)` Sets the cache directory.
    `static URI` | `shortenURI(URI orig, String strip)` Utility to strip a string from the end of a URI.
    `static void` | `storeProperties(PropertyMap properties, URI uri, String title)` Store the properties at the location given by the uri using the supplied title.
    `static URI` | `toURI(URL url)` Convert an URL to an URI.
    `static URL` | `toURL(URI uri)` Convert an URI to an URL.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### PROTOCOL_FILE

          public static final String PROTOCOL_FILE

      Constant for the file: protocol or scheme
      See Also:
        Constant Field Values

    - #### PROTOCOL_HTTP

          public static final String PROTOCOL_HTTP

      Constant for the http: protocol or scheme
      See Also:
        Constant Field Values

    - #### PROTOCOL_FTP

          public static final String PROTOCOL_FTP

      Constant for the ftp: protocol or scheme
      See Also:
        Constant Field Values

    - #### PROTOCOL_JAR

          public static final String PROTOCOL_JAR

      Constant for the jar: protocol or scheme
      See Also:
        Constant Field Values

    - #### INDEX_FILE

          public static final String INDEX_FILE

      For directory listings
      See Also:
        Constant Field Values

    - #### SEPARATOR

          public static final String SEPARATOR

      URL/URI separator
      See Also:
        Constant Field Values

    - #### AUTH_SEPERATOR_USERNAME

          public static final String AUTH_SEPERATOR_USERNAME

      Separating the username from the rest of the URL/URI
      See Also:
        Constant Field Values

    - #### AUTH_SEPERATOR_PASSWORD

          public static final String AUTH_SEPERATOR_PASSWORD

      Separating the password from the username
      See Also:
        Constant Field Values

    - #### TEMP_SUFFIX

          private static final String TEMP_SUFFIX

      The temporary suffix, used when a temporary file is needed in the system's temporary directory.
      See Also:
        Constant Field Values

    - #### cachedir

          private static File cachedir

      Where are temporary files cached.

    - #### LOGGER

          private static final org.slf4j.Logger LOGGER

      The log stream

  - ### Constructor Detail

    - #### NetUtil

          private NetUtil()

      Basic constructor - ensure that we can't be instantiated

  - ### Method Detail

    - #### copy

          public static URI copy(URI uri)

    - #### makeDirectory

          public static void makeDirectory(URI orig)
                                    throws MalformedURLException

      If the directory does not exist, create it. Note this currently only works with file: type URIs
      Parameters:
        `orig` - The directory URI to create
      Throws:
        `MalformedURLException` - If the URI is not valid

    - #### makeFile

          public static void makeFile(URI orig)
                               throws MalformedURLException,
                                      IOException

      If the file does not exist, create it. Note this currently only works with file: type URIs
      Parameters:
        `orig` - The file URI to create
      Throws:
        `MalformedURLException` - If the URI is not valid
        `IOException` - a problem with I/O happened

    - #### isFile

          public static boolean isFile(URI uri)

      If there is a file at the other end of this URI return true.
      Parameters:
        `uri` - The URI to check
      Returns:
        true if the URI points at a file

    - #### isDirectory

          public static boolean isDirectory(URI orig)

      If there is a directory at the other end of this URI return true. Note non file: type URI will always return false
      Parameters:
        `orig` - The URI to check
      Returns:
        true if the URI points at a file: directory

    - #### canWrite

          public static boolean canWrite(URI orig)

      If there is a writable directory or file at the other end of this URI return true. Note non file: type URIs will always return false
      Parameters:
        `orig` - The URI to check
      Returns:
        true if the URI points at a writable file or directory

    - #### canRead

          public static boolean canRead(URI orig)

      If there is a readable directory or file at the other end of this URI return true. Note non file: type URIs will always return false
      Parameters:
        `orig` - The URI to check
      Returns:
        true if the URI points at a readable file or directory

    - #### move

          public static boolean move(URI oldUri,
                     URI newUri)
                              throws IOException

      Move a URI from one place to another. Currently this only works for file: URIs, however the interface should not need to change to handle more complex URIs
      Parameters:
        `oldUri` - The URI to move
        `newUri` - The destination URI
      Returns:
        whether the move happened
      Throws:
        `IOException` - a problem with I/O happened

    - #### delete

          public static boolean delete(URI orig)
                                throws IOException

      Delete a URI. Currently this only works for file: URIs, however the interface should not need to change to handle more complex URIs
      Parameters:
        `orig` - The URI to delete
      Returns:
        whether the deleted happened
      Throws:
        `IOException` - a problem with I/O happened

    - #### getAsFile

          public static File getAsFile(URI uri)
                                throws IOException

      Return a File from the URI either by extracting from a file: URI or by downloading to a temp dir first
      Parameters:
        `uri` - The original URI to the file.
      Returns:
        The URI as a file
      Throws:
        `IOException` - a problem with I/O happened

    - #### shortenURI

          public static URI shortenURI(URI orig,
                       String strip)
                                throws MalformedURLException

      Utility to strip a string from the end of a URI.
      Parameters:
        `orig` - The URI to strip
        `strip` - The text to strip from the end of the URI
      Returns:
        The stripped URI
      Throws:
        `MalformedURLException` - If the URI does not end in the given text

    - #### lengthenURI

          public static URI lengthenURI(URI orig,
                        String anExtra)

      Utility to add a string to the end of a URI.
      Parameters:
        `orig` - The URI to lengthen
        `anExtra` - The text to add to the end of the URI
      Returns:
        The lengthened URI

    - #### isSeparator

          private static boolean isSeparator(char c)

    - #### getInputStream

          public static InputStream getInputStream(URI uri)
                                            throws IOException

      Attempt to obtain an InputStream from a URI. If the URI is a file scheme then just open it directly. Otherwise, call uri.toURL().openStream().
      Parameters:
        `uri` - The URI to attempt to read from
      Returns:
        An InputStream connection
      Throws:
        `IOException` - a problem with I/O happened

    - #### getOutputStream

          public static OutputStream getOutputStream(URI uri)
                                              throws IOException

      Attempt to obtain an OutputStream from a URI. The simple case will open it if it is local. Otherwise, it will call uri.toURL().openConnection().getOutputStream(), however in some JVMs (MS at least this fails where new FileOutputStream(url) works.
      Parameters:
        `uri` - The URI to attempt to write to
      Returns:
        An OutputStream connection
      Throws:
        `IOException` - a problem with I/O happened

    - #### getOutputStream

          public static OutputStream getOutputStream(URI uri,
                                     boolean append)
                                              throws IOException

      Attempt to obtain an OutputStream from a URI. The simple case will open it if it is local. Otherwise, it will call uri.toURL().openConnection().getOutputStream(), however in some JVMs (MS at least this fails where new FileOutputStream(url) works.
      Parameters:
        `uri` - The URI to attempt to write to
        `append` - Do we write to the end of the file instead of the beginning
      Returns:
        An OutputStream connection
      Throws:
        `IOException` - a problem with I/O happened

    - #### list

          public static String[] list(URI uri,
                      URIFilter filter)
                               throws MalformedURLException,
                                      IOException

      List the items available assuming that this URI points to a directory.

      There are 2 methods of calculating the answer - if the URI is a file: URI then we can just use File.list(), otherwise we ask for a file inside the directory called index.txt and assume the directories contents to be listed one per line.

      If the URI is a file: URI then we execute both methods and warn if there is a difference, but returning the values from the index.txt method.

      Parameters:
        `uri` - the URI to list
        `filter` - the filter for the listing
      Returns:
        the filtered list
      Throws:
        `MalformedURLException` - If the URI is not valid
        `IOException` - a problem with I/O happened

    - #### listByFile

          public static String[] listByFile(URI uri,
                            URIFilter filter)
                                     throws MalformedURLException

      List all the files specified by the index file passed in.
      Parameters:
        `uri` - the URI to list
        `filter` - the filter for the listing
      Returns:
        the filtered list
      Throws:
        `MalformedURLException` - If the URI is not valid

    - #### listByIndexFile

          public static String[] listByIndexFile(URI index)
                                          throws IOException

      List all the strings specified by the index file passed in. To be acceptable it must be a non-0 length string, not commented with #, and not the index file itself.
      Parameters:
        `index` - the URI to list
      Returns:
        the list.
      Throws:
        `IOException` - a problem with I/O happened

    - #### listByIndexFile

          public static String[] listByIndexFile(URI index,
                                 URIFilter filter)
                                          throws IOException

      List all the files specified by the index file passed in.

      Each line is pre-processed:

      - Ignore comments (# to end of line)
      - Trim spaces from line.
      - Ignore blank lines.
      To be acceptable it:
      - cannot be the index file itself
      - and must acceptable by the filter.
      Parameters:
        `index` - the URI to list
        `filter` - the filter for the listing
      Returns:
        the list.
      Throws:
        `IOException` - a problem with I/O happened

    - #### loadProperties

          public static PropertyMap loadProperties(URI uri)
                                            throws IOException

      Load up properties given by a URI.
      Parameters:
        `uri` - the location of the properties
      Returns:
        the properties given by the URI
      Throws:
        `IOException` - a problem with I/O happened

    - #### storeProperties

          public static void storeProperties(PropertyMap properties,
                             URI uri,
                             String title)
                                      throws IOException

      Store the properties at the location given by the uri using the supplied title.
      Parameters:
        `properties` - the properties to store
        `uri` - the location of the store
        `title` - the label held in the properties file
      Throws:
        `IOException` - a problem with I/O happened

    - #### getSize

          public static int getSize(URI uri)

      Parameters:
        `uri` - the resource whose size is wanted
      Returns:
        the size of that resource

    - #### getSize

          public static int getSize(URI uri,
                    String proxyHost)

    - #### getSize

          public static int getSize(URI uri,
                    String proxyHost,
                    Integer proxyPort)

    - #### getLastModified

          public static long getLastModified(URI uri)

      When was the given URI last modified. If no modification time is available then this method return the current time.
      Parameters:
        `uri` - the URI to examine
      Returns:
        the last modified date

    - #### getLastModified

          public static long getLastModified(URI uri,
                             String proxyHost)

      When was the given URI last modified. If no modification time is available then this method return the current time.
      Parameters:
        `uri` - the URI to examine
        `proxyHost` - the proxy host
      Returns:
        the last modified date

    - #### getLastModified

          public static long getLastModified(URI uri,
                             String proxyHost,
                             Integer proxyPort)

      When was the given URI last modified. If no modification time is available then this method return the current time.
      Parameters:
        `uri` - the URI to examine
        `proxyHost` - the proxy host
        `proxyPort` - the proxy port
      Returns:
        the last modified date

    - #### isNewer

          public static boolean isNewer(URI left,
                        URI right)

      Returns whether the left is newer than the right by comparing their last modified dates.
      Parameters:
        `left` - one URI to compare
        `right` - the other URI to compare
      Returns:
        true if the left is newer

    - #### isNewer

          public static boolean isNewer(URI left,
                        URI right,
                        String proxyHost)

      Returns whether the left is newer than the right by comparing their last modified dates.
      Parameters:
        `left` - one URI to compare
        `right` - the other URI to compare
        `proxyHost` - the proxy host
      Returns:
        true if the left is newer

    - #### isNewer

          public static boolean isNewer(URI left,
                        URI right,
                        String proxyHost,
                        Integer proxyPort)

      Returns whether the left is newer than the right by comparing their last modified dates.
      Parameters:
        `left` - one URI to compare
        `right` - the other URI to compare
        `proxyHost` - the proxy host
        `proxyPort` - the proxy port
      Returns:
        true if the left is newer

    - #### checkFileURI

          private static void checkFileURI(URI uri)
                                    throws MalformedURLException

      Throw if the given URI does not use the 'file:' protocol
      Parameters:
        `uri` - The URI to check
      Throws:
        `MalformedURLException` - If the protocol is not file:

    - #### getURICacheDir

          public static File getURICacheDir()

      Returns the cache directory.
      Returns:
        File

    - #### setURICacheDir

          public static void setURICacheDir(File cachedir)

      Sets the cache directory.
      Parameters:
        `cachedir` - The cache directory to set

    - #### getURI

          public static URI getURI(File file)

      Get a URI version of the given file.
      Parameters:
        `file` - The File to turn into a URI
      Returns:
        a URI for the given file

    - #### getTemporaryURI

          public static URI getTemporaryURI(String prefix,
                            String suffix)
                                     throws IOException

      A URI version of `File.createTempFile()`
      Parameters:
        `prefix` - the prefix of the temporary file
        `suffix` - the suffix of the temporary file
      Returns:
        A new temporary URI
      Throws:
        `IOException` - If something goes wrong creating the temp URI

    - #### toURI

          public static URI toURI(URL url)

      Convert an URL to an URI.
      Parameters:
        `url` - to convert
      Returns:
        the URI representation of the URL

    - #### toURL

          public static URL toURL(URI uri)

      Convert an URI to an URL.
      Parameters:
        `uri` - to convert
      Returns:
        the URL representation of the URI