Class IOUtilities
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 Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic String
canNotReadFile
(Locale locale, String format, String filename, Object store) Returns the error message for a file that cannot be parsed.static String
Encodes the characters that are not legal for theURI(String)
constructor.static short
errorMessageKey
(Object[] parameters) Returns theResources.Keys
value together with the parameters given byerrorMessageParameters(…)
.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.static String
Returns the filename extension (without leading dot) from aPath
,File
,URL
,URI
orCharSequence
instance.static String
static String
Returns the given path without the directories and without the extension.static boolean
isKindOfPath
(Object path) static boolean
isWrite
(OpenOption[] options) Returnstrue
if the given options would open a file mostly for writing.private static String
Implementation offilename(Object)
andextension(Object)
methods.static int
readCodePoint
(Reader in) Reads the next character as an Unicode code point.static URL
toAuxiliaryURL
(URI location, String extension) static File
Returns the given path as aFile
, ornull
if it cannot be converted.static File
static Object
toFileOrURL
(String path, String encoding) static InputStream
toInputStream
(AutoCloseable stream) Converts the given output stream to an input stream.static OutputStream
toOutputStream
(AutoCloseable stream) Converts the given input stream to an output stream.static Path
static Path
toPathOrNull
(Object path) Converts the given object to aPath
if the object is a known type, or returnsnull
otherwise.static String
Returns a string representation of the given path, ornull
if none.static URI
static boolean
truncate
(AutoCloseable stream) Truncates the given output stream at its current position.
-
Field Details
-
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
Returnstrue
if the given object is aPath
,File
,URL
,URI
orCharSequence
. They are the types accepted by methods such asfilename(Object)
.- Parameters:
path
- the object to verify.- Returns:
- whether the given object is of known type.
- Since:
- 1.1
-
filename
Returns the filename from aPath
,File
,URL
,URI
orCharSequence
instance. If the given argument is specialized type likePath
orFile
, then this method uses dedicated API likePath.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, ornull
.- Returns:
- the filename in the given path, or
null
if the given object is null or of unknown type.
-
extension
Returns the filename extension (without leading dot) from aPath
,File
,URL
,URI
orCharSequence
instance. If no extension is found, returns an empty string. If the given object is of unknown type, returnnull
.- Parameters:
path
- the filename extension (may be an empty string), ornull
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
Implementation offilename(Object)
andextension(Object)
methods. -
toString
Returns a string representation of the given path, ornull
if none. The current implementation recognizes only thePath
,File
,URL
,URI
orCharSequence
types.- Parameters:
path
- the path for which to return a string representation.- Returns:
- the string representation, or
null
if none.
-
toFile
Returns the given path as aFile
, ornull
if it cannot be converted. -
toAuxiliaryURL
Converts the givenURI
to aURL
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, ornull
.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
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, ornull
.- Returns:
- the filename without extension, or
null
if none.
-
encodeURI
Encodes the characters that are not legal for theURI(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, ornull
.- Returns:
- the encoded path, or
null
if and only if the given path was null.
-
toURI
Converts aURL
to aURI
. This is equivalent to a call to the standardURL.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, ornull
.encoding
- if the URL is encoded in aapplication/x-www-form-urlencoded
MIME format, the character encoding (normally"UTF-8"
). If the URL is not encoded, thennull
.- 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:
- Optionally decodes the
-
toFile
Converts aURL
to aFile
. This is equivalent to a call to the standardURL.toURI()
method followed by a call to theFile(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, ornull
.encoding
- if the URL is encoded in aapplication/x-www-form-urlencoded
MIME format, the character encoding (normally"UTF-8"
). If the URL is not encoded, thennull
.- 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:
- Optionally decodes the
-
toPath
Converts aURL
to aPath
. This is equivalent to a call to the standardURL.toURI()
method followed by a call to thePaths.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, ornull
.encoding
- if the URL is encoded in aapplication/x-www-form-urlencoded
MIME format, the character encoding (normally"UTF-8"
). If the URL is not encoded, thennull
.- 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:
- Optionally decodes the
-
toFileOrURL
Parses the following path as aFile
if possible, or aURL
otherwise. In the special case where the givenpath
is a URL using the"file"
protocol, the URL is converted to aFile
object using the givenencoding
for decoding the"%XX"
sequences, if any.Rational
A URL can represent a file, butURL.openStream()
appears to return aBufferedInputStream
wrapping theFileInputStream
, which is not a desirable feature when we want to obtain a channel.- Parameters:
path
- the path to convert, ornull
.encoding
- if the URL is encoded in aapplication/x-www-form-urlencoded
MIME format, the character encoding (normally"UTF-8"
). If the URL is not encoded, thennull
. This argument is ignored if the given path does not need to be converted from URL toFile
.- Returns:
- the path as a
File
if possible, or aURL
otherwise. - Throws:
IOException
- if the given path is not a file and cannot be parsed as a URL.
-
toPathOrNull
Converts the given object to aPath
if the object is a known type, or returnsnull
otherwise. Current implementation recognizesCharSequence
,Path
,File
,URI
but notURL
, 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
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 anInputStream
.- 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
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 anOutputStream
.- 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
Truncates the given output stream at its current position. This method works with Apache SIS implementations backed (sometimes indirectly) bySeekableByteChannel
. 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
Returnstrue
if the given options would open a file mostly for writing. This method returnstrue
if the following conditions are true:- The array contains
StandardOpenOption.WRITE
. - The array does not contain
StandardOpenOption.READ
, unless the array also containsStandardOpenOption.CREATE_NEW
orStandardOpenOption.TRUNCATE_EXISTING
in which case theREAD
option is ignored (because the caller would have no data to read).
- Parameters:
options
- the open options to check, ornull
if none.- Returns:
true
if a file opened with the given options would be mostly for write operations.- Since:
- 0.8
- The array contains
-
readCodePoint
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
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, ornull
.- Returns:
- the parameters for a localized error message for a file that cannot be processed.
- Since:
- 0.8
-
errorMessageKey
Returns theResources.Keys
value together with the parameters given byerrorMessageParameters(…)
.- Parameters:
parameters
- the result oferrorMessageParameters(…)
method call.- Returns:
- the
Resources.Keys
value to use for formatting the error message. - Since:
- 0.8
-
errorMessageParameters
Returns the parameters for an error message saying that an error occurred while processing a file. This method uses the information provided by methods likeLineNumberReader.getLineNumber()
orXMLStreamReader.getLocation()
if the givenstore
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, ornull
.- Returns:
- the parameters for a localized error message for a file that cannot be processed.
- Since:
- 0.8
-