1 /* |
1 /* |
2 * Copyright (c) 2007, 2011, Oracle and/or its affiliates. All rights reserved. |
2 * Copyright (c) 2007, 2018, Oracle and/or its affiliates. All rights reserved. |
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
4 * |
4 * |
5 * This code is free software; you can redistribute it and/or modify it |
5 * This code is free software; you can redistribute it and/or modify it |
6 * under the terms of the GNU General Public License version 2 only, as |
6 * under the terms of the GNU General Public License version 2 only, as |
7 * published by the Free Software Foundation. Oracle designates this |
7 * published by the Free Software Foundation. Oracle designates this |
30 |
30 |
31 /** |
31 /** |
32 * This class consists exclusively of static methods that return a {@link Path} |
32 * This class consists exclusively of static methods that return a {@link Path} |
33 * by converting a path string or {@link URI}. |
33 * by converting a path string or {@link URI}. |
34 * |
34 * |
|
35 * @apiNote |
|
36 * It is recommended to obtain a {@code Path} via the {@code Path.of} methods |
|
37 * instead of via the {@code get} methods defined in this class as this class |
|
38 * may be deprecated in a future release. |
|
39 * |
35 * @since 1.7 |
40 * @since 1.7 |
|
41 * @see Path |
36 */ |
42 */ |
37 |
43 |
38 public final class Paths { |
44 public final class Paths { |
39 private Paths() { } |
45 private Paths() { } |
40 |
46 |
41 /** |
47 /** |
42 * Converts a path string, or a sequence of strings that when joined form |
48 * Converts a path string, or a sequence of strings that when joined form |
43 * a path string, to a {@code Path}. If {@code more} does not specify any |
49 * a path string, to a {@code Path}. |
44 * elements then the value of the {@code first} parameter is the path string |
|
45 * to convert. If {@code more} specifies one or more elements then each |
|
46 * non-empty string, including {@code first}, is considered to be a sequence |
|
47 * of name elements (see {@link Path}) and is joined to form a path string. |
|
48 * The details as to how the Strings are joined is provider specific but |
|
49 * typically they will be joined using the {@link FileSystem#getSeparator |
|
50 * name-separator} as the separator. For example, if the name separator is |
|
51 * "{@code /}" and {@code getPath("/foo","bar","gus")} is invoked, then the |
|
52 * path string {@code "/foo/bar/gus"} is converted to a {@code Path}. |
|
53 * A {@code Path} representing an empty path is returned if {@code first} |
|
54 * is the empty string and {@code more} does not contain any non-empty |
|
55 * strings. |
|
56 * |
50 * |
57 * <p> The {@code Path} is obtained by invoking the {@link FileSystem#getPath |
51 * @implSpec |
58 * getPath} method of the {@link FileSystems#getDefault default} {@link |
52 * This method simply invokes {@link Path#of(String,String...) |
59 * FileSystem}. |
53 * Path.of(String, String...)} with the given parameters. |
60 * |
|
61 * <p> Note that while this method is very convenient, using it will imply |
|
62 * an assumed reference to the default {@code FileSystem} and limit the |
|
63 * utility of the calling code. Hence it should not be used in library code |
|
64 * intended for flexible reuse. A more flexible alternative is to use an |
|
65 * existing {@code Path} instance as an anchor, such as: |
|
66 * <pre> |
|
67 * Path dir = ... |
|
68 * Path path = dir.resolve("file"); |
|
69 * </pre> |
|
70 * |
54 * |
71 * @param first |
55 * @param first |
72 * the path string or initial part of the path string |
56 * the path string or initial part of the path string |
73 * @param more |
57 * @param more |
74 * additional strings to be joined to form the path string |
58 * additional strings to be joined to form the path string |
77 * |
61 * |
78 * @throws InvalidPathException |
62 * @throws InvalidPathException |
79 * if the path string cannot be converted to a {@code Path} |
63 * if the path string cannot be converted to a {@code Path} |
80 * |
64 * |
81 * @see FileSystem#getPath |
65 * @see FileSystem#getPath |
|
66 * @see Path#of(String,String...) |
82 */ |
67 */ |
83 public static Path get(String first, String... more) { |
68 public static Path get(String first, String... more) { |
84 return FileSystems.getDefault().getPath(first, more); |
69 return Path.of(first, more); |
85 } |
70 } |
86 |
71 |
87 /** |
72 /** |
88 * Converts the given URI to a {@link Path} object. |
73 * Converts the given URI to a {@link Path} object. |
89 * |
74 * |
90 * <p> This method iterates over the {@link FileSystemProvider#installedProviders() |
75 * @implSpec |
91 * installed} providers to locate the provider that is identified by the |
76 * This method simply invokes {@link Path#of(URI) * Path.of(URI)} with the given parameter. |
92 * URI {@link URI#getScheme scheme} of the given URI. URI schemes are |
|
93 * compared without regard to case. If the provider is found then its {@link |
|
94 * FileSystemProvider#getPath getPath} method is invoked to convert the |
|
95 * URI. |
|
96 * |
|
97 * <p> In the case of the default provider, identified by the URI scheme |
|
98 * "file", the given URI has a non-empty path component, and undefined query |
|
99 * and fragment components. Whether the authority component may be present |
|
100 * is platform specific. The returned {@code Path} is associated with the |
|
101 * {@link FileSystems#getDefault default} file system. |
|
102 * |
|
103 * <p> The default provider provides a similar <em>round-trip</em> guarantee |
|
104 * to the {@link java.io.File} class. For a given {@code Path} <i>p</i> it |
|
105 * is guaranteed that |
|
106 * <blockquote>{@code |
|
107 * Paths.get(}<i>p</i>{@code .}{@link Path#toUri() toUri}{@code ()).equals(} |
|
108 * <i>p</i>{@code .}{@link Path#toAbsolutePath() toAbsolutePath}{@code ())} |
|
109 * </blockquote> |
|
110 * so long as the original {@code Path}, the {@code URI}, and the new {@code |
|
111 * Path} are all created in (possibly different invocations of) the same |
|
112 * Java virtual machine. Whether other providers make any guarantees is |
|
113 * provider specific and therefore unspecified. |
|
114 * |
77 * |
115 * @param uri |
78 * @param uri |
116 * the URI to convert |
79 * the URI to convert |
117 * |
80 * |
118 * @return the resulting {@code Path} |
81 * @return the resulting {@code Path} |
125 * cannot be created automatically, or the provider identified by |
88 * cannot be created automatically, or the provider identified by |
126 * the URI's scheme component is not installed |
89 * the URI's scheme component is not installed |
127 * @throws SecurityException |
90 * @throws SecurityException |
128 * if a security manager is installed and it denies an unspecified |
91 * if a security manager is installed and it denies an unspecified |
129 * permission to access the file system |
92 * permission to access the file system |
|
93 * |
|
94 * @see Path#of(URI) |
130 */ |
95 */ |
131 public static Path get(URI uri) { |
96 public static Path get(URI uri) { |
132 String scheme = uri.getScheme(); |
97 return Path.of(uri); |
133 if (scheme == null) |
|
134 throw new IllegalArgumentException("Missing scheme"); |
|
135 |
|
136 // check for default provider to avoid loading of installed providers |
|
137 if (scheme.equalsIgnoreCase("file")) |
|
138 return FileSystems.getDefault().provider().getPath(uri); |
|
139 |
|
140 // try to find provider |
|
141 for (FileSystemProvider provider: FileSystemProvider.installedProviders()) { |
|
142 if (provider.getScheme().equalsIgnoreCase(scheme)) { |
|
143 return provider.getPath(uri); |
|
144 } |
|
145 } |
|
146 |
|
147 throw new FileSystemNotFoundException("Provider \"" + scheme + "\" not installed"); |
|
148 } |
98 } |
149 } |
99 } |