Package org.apache.sis.internal.storage.io

Class IOUtilities

java.lang.Object
org.apache.sis.util.Static
org.apache.sis.internal.storage.io.IOUtilities
public final class IOUtilities extends Static
Utility methods related to I/O operations. Many methods in this class accept arbitrary Object argument and perform a sequence of instanceof checks. Since this approach provides no type safety and since the sequence of instanceof checks is somewhat arbitrary, those methods cannot be in public API.

Unless otherwise specified, giving an instance of unknown type or a null value cause the methods to return null. No exception is thrown for unknown type - callers must check that the return value is not null. However, exceptions may be thrown for malformed URI or URL.

Since:
0.3
Version:
1.4

  • Field Details

    • CURRENT_DIRECTORY_SYMBOL

      public static final String CURRENT_DIRECTORY_SYMBOL
      The symbol for current directory.
      See Also:

  • Constructor Details

    • IOUtilities

      private IOUtilities()
      Do not allow instantiation of this class.

  • Method Details

    • isKindOfPath

      public static boolean isKindOfPath(Object path)
      Returns true if the given object is a Path, File, URL, URI or CharSequence. They are the types accepted by methods such as filename(Object).
      Parameters:
      path - the object to verify.
      Returns:
      whether the given object is of known type.
      Since:
      1.1

    • filename

      public static String filename(Object path)
      Returns the filename from a Path, File, URL, URI or CharSequence instance. If the given argument is specialized type like Path or File, then this method uses dedicated API like Path.getFileName(). Otherwise this method gets a string representation of the path and returns the part after the last '/' or platform-dependent name separator character, if any. The returned string may be empty if the given path is empty or is the root directory.
      Parameters:
      path - the path as an instance of one of the above-cited types, or null.
      Returns:
      the filename in the given path, or null if the given object is null or of unknown type.

    • extension

      public static String extension(Object path)
      Returns the filename extension (without leading dot) from a Path, File, URL, URI or CharSequence instance. If no extension is found, returns an empty string. If the given object is of unknown type, return null.
      Parameters:
      path - the filename extension (may be an empty string), or null if unknown.
      Returns:
      the extension in the given path, or an empty string if none, or null if the given object is null or of unknown type.

    • part

      private static String part(Object path, boolean extension)
      Implementation of filename(Object) and extension(Object) methods.

    • toString

      public static String toString(Object path)
      Returns a string representation of the given path, or null if none. The current implementation recognizes only the Path, File, URL, URI or CharSequence types.
      Parameters:
      path - the path for which to return a string representation.
      Returns:
      the string representation, or null if none.

    • toFile

      public static File toFile(Object path)
      Returns the given path as a File, or null if it cannot be converted.
      Parameters:
      path - the object to convert to a File. Can be null.
      Returns:
      the given path as a File, or null if it cannot be converted.

    • toAuxiliaryURL

      public static URL toAuxiliaryURL(URI location, String extension) throws MalformedURLException
      Converts the given URI to a URL with the same path except for the file extension, which is replaced by the given extension. This method is used for opening auxiliary files such as "*.prj" and "*.tfw" files that come with e.g. TIFF files.
      Parameters:
      location - the URI to convert to a URL with a different extension, or null.
      extension - the file extension (without '.') of the auxiliary file.
      Returns:
      URL for the auxiliary file with the given extension, or null if none.
      Throws:
      MalformedURLException - if the URI uses an unknown protocol or a negative port number other than -1.
      Since:
      1.2

    • filenameWithoutExtension

      public static String filenameWithoutExtension(String path)
      Returns the given path without the directories and without the extension. For example if the given path is "/Users/name/Map.png", then this method returns "Map".
      Parameters:
      path - the path from which to get the filename without extension, or null.
      Returns:
      the filename without extension, or null if none.

    • encodeURI

      public static String encodeURI(String path)
      Encodes the characters that are not legal for the URI(String) constructor. Note that in addition to unreserved characters ("_-!.~'()*"), the reserved characters ("?/[]@") and the punctuation characters (",;:$&+=") are left unchanged, so they will be processed with their special meaning by the URI constructor.

      The current implementations replaces only the space characters, control characters and the % character. Future versions may replace more characters as we learn from experience.

      Parameters:
      path - the path to encode, or null.
      Returns:
      the encoded path, or null if and only if the given path was null.

    • toURI

      public static URI toURI(URL url, String encoding) throws IOException
      Converts a URL to a URI. This is equivalent to a call to the standard URL.toURI() method, except for the following functionalities:
      • Optionally decodes the "%XX" sequences, where "XX" is a number.
      • Converts various exceptions into subclasses of IOException.
      Parameters:
      url - the URL to convert, or null.
      encoding - if the URL is encoded in a application/x-www-form-urlencoded MIME format, the character encoding (normally "UTF-8"). If the URL is not encoded, then null.
      Returns:
      the URI for the given URL, or null if the given URL was null.
      Throws:
      IOException - if the URL cannot be converted to a URI.
      See Also:

    • toFile

      public static File toFile(URL url, String encoding) throws IOException
      Converts a URL to a File. This is equivalent to a call to the standard URL.toURI() method followed by a call to the File(URI) constructor, except for the following functionalities:
      • Optionally decodes the "%XX" sequences, where "XX" is a number.
      • Converts various exceptions into subclasses of IOException.
      Parameters:
      url - the URL to convert, or null.
      encoding - if the URL is encoded in a application/x-www-form-urlencoded MIME format, the character encoding (normally "UTF-8"). If the URL is not encoded, then null.
      Returns:
      the file for the given URL, or null if the given URL was null.
      Throws:
      IOException - if the URL cannot be converted to a file.
      See Also:

    • toPath

      public static Path toPath(URL url, String encoding) throws IOException
      Converts a URL to a Path. This is equivalent to a call to the standard URL.toURI() method followed by a call to the Paths.get(URI) static method, except for the following functionalities:
      • Optionally decodes the "%XX" sequences, where "XX" is a number.
      • Converts various exceptions into subclasses of IOException.
      Parameters:
      url - the URL to convert, or null.
      encoding - if the URL is encoded in a application/x-www-form-urlencoded MIME format, the character encoding (normally "UTF-8"). If the URL is not encoded, then null.
      Returns:
      the path for the given URL, or null if the given URL was null.
      Throws:
      IOException - if the URL cannot be converted to a path.
      See Also:

    • toFileOrURL

      public static Object toFileOrURL(String path, String encoding) throws IOException
      Parses the following path as a File if possible, or a URL otherwise. In the special case where the given path is a URL using the "file" protocol, the URL is converted to a File object using the given encoding for decoding the "%XX" sequences, if any.

      Rational

      A URL can represent a file, but URL.openStream() appears to return a BufferedInputStream wrapping the FileInputStream, which is not a desirable feature when we want to obtain a channel.
      Parameters:
      path - the path to convert, or null.
      encoding - if the URL is encoded in a application/x-www-form-urlencoded MIME format, the character encoding (normally "UTF-8"). If the URL is not encoded, then null. This argument is ignored if the given path does not need to be converted from URL to File.
      Returns:
      the path as a File if possible, or a URL otherwise.
      Throws:
      IOException - if the given path is not a file and cannot be parsed as a URL.

    • toPathOrNull

      public static Path toPathOrNull(Object path)
      Converts the given object to a Path if the object is a known type, or returns null otherwise. Current implementation recognizes CharSequence, Path, File, URI but not URL, because conversion of URL requires to know the encoding.
      Parameters:
      path - the object to convert to a path.
      Returns:
      the given object as a path, or null.
      Throws:
      IllegalArgumentException - if the given object is an instance of a supported type but cannot be converted.
      FileSystemNotFoundException - if the file system identified by URI cannot be used.

    • toInputStream

      public static InputStream toInputStream(AutoCloseable stream) throws IOException
      Converts the given output stream to an input stream. It is caller's responsibility to flush the stream and reset its position to the beginning of file before to invoke this method. The data read by the input stream will be the data that have been written in the output stream before this method is invoked.

      The given output stream should not be used anymore after this method invocation, but should not be closed neither since the returned input stream may be backed by the same channel.

      Parameters:
      stream - the input or output stream to converts to an InputStream.
      Returns:
      the input stream, or null if the given stream cannot be converted.
      Throws:
      IOException - if an error occurred during input stream creation.
      Since:
      0.8

    • toOutputStream

      public static OutputStream toOutputStream(AutoCloseable stream) throws IOException
      Converts the given input stream to an output stream. It is caller's responsibility to reset the stream position to the beginning of file before to invoke this method. The data written by the output stream will overwrite the previous data, but the caller may need to truncate the output stream after he finished to write in it.

      The given input stream should not be used anymore after this method invocation, but should not be closed neither since the returned output stream may be backed by the same channel.

      Parameters:
      stream - the input or output stream to converts to an OutputStream.
      Returns:
      the output stream, or null if the given stream cannot be converted.
      Throws:
      IOException - if an error occurred during output stream creation.
      Since:
      0.8

    • truncate

      public static boolean truncate(AutoCloseable stream) throws IOException
      Truncates the given output stream at its current position. This method works with Apache SIS implementations backed (sometimes indirectly) by SeekableByteChannel. Callers may need to flush the stream before to invoke this method.
      Parameters:
      stream - the output stream or writable channel to truncate.
      Returns:
      whether this method has been able to truncate the given stream.
      Throws:
      IOException - if an error occurred while truncating the stream.

    • isWrite

      public static boolean isWrite(OpenOption[] options)
      Returns true if the given options would open a file mostly for writing. This method returns true if the following conditions are true:
      Parameters:
      options - the open options to check, or null if none.
      Returns:
      true if a file opened with the given options would be mostly for write operations.
      Since:
      0.8

    • readCodePoint

      public static int readCodePoint(Reader in) throws IOException
      Reads the next character as an Unicode code point. Unless end-of-file has been reached, the returned value is between 0 and 1114111 inclusive.
      Parameters:
      in - the reader from which to read code point.
      Returns:
      the next code point, or -1 on end of file.
      Throws:
      IOException - if an error occurred while reading characters.
      Since:
      0.8

    • canNotReadFile

      public static String canNotReadFile(Locale locale, String format, String filename, Object store)
      Returns the error message for a file that cannot be parsed. The error message will contain the line number if available.
      Parameters:
      locale - the language for the error message.
      format - abbreviation of the file format (e.g. "CSV", "GML", "WKT", etc).
      filename - name of the file or the data store.
      store - the input or output object, or null.
      Returns:
      the parameters for a localized error message for a file that cannot be processed.
      Since:
      0.8

    • errorMessageKey

      public static short errorMessageKey(Object[] parameters)
      Returns the Resources.Keys value together with the parameters given by errorMessageParameters(…).
      Parameters:
      parameters - the result of errorMessageParameters(…) method call.
      Returns:
      the Resources.Keys value to use for formatting the error message.
      Since:
      0.8

    • errorMessageParameters

      public static Object[] errorMessageParameters(String format, String filename, Object store)
      Returns the parameters for an error message saying that an error occurred while processing a file. This method uses the information provided by methods like LineNumberReader.getLineNumber() or XMLStreamReader.getLocation() if the given store is one of the supported types.
      Parameters:
      format - abbreviation of the file format (e.g. "CSV", "GML", "WKT", etc).
      filename - name of the file or the data store.
      store - the input or output object, or null.
      Returns:
      the parameters for a localized error message for a file that cannot be processed.
      Since:
      0.8