1 /*
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.
4 *
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
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.nio.file;
27
28 import jdk.internal.util.PathParser;
29
30 import java.io.File;
31 import java.net.URI;
32 import java.util.Arrays;
33 import java.util.List;
34 import java.util.Objects;
35 import java.util.stream.Collectors;
36
37 /**
38 * This class consists exclusively of static methods that return a {@link Path}
39 * by converting a path string or {@link URI}.
40 *
41 * <p>Unless otherwise noted, passing a {@code null} argument to a method
42 * in this class will cause a {@link NullPointerException} to be thrown.
43 *
44 * @apiNote
45 * It is recommended to obtain a {@code Path} via the {@code Path.of} methods
46 * instead of via the {@code get} methods defined in this class as this class
47 * may be deprecated in a future release.
48 *
49 * @since 1.7
50 * @see Path
51 */
52
53 public final class Paths {
54 private Paths() { }
55
56 /**
57 * Converts a path string, or a sequence of strings that when joined form
58 * a path string, to a {@code Path}.
59 *
60 * @implSpec
61 * This method simply invokes {@link Path#of(String,String...)
62 * Path.of(String, String...)} with the given parameters.
63 *
64 * @param first
65 * the path string or initial part of the path string
66 * @param more
67 * additional strings to be joined to form the path string
68 *
69 * @return the resulting {@code Path}
70 *
71 * @throws InvalidPathException
72 * if the path string cannot be converted to a {@code Path}
73 *
74 * @see FileSystem#getPath
75 * @see Path#of(String,String...)
76 */
77 public static Path get(String first, String... more) {
78 return Path.of(first, more);
79 }
80
81 /**
82 * Converts the given URI to a {@link Path} object.
83 *
84 * @implSpec
85 * This method simply invokes {@link Path#of(URI) * Path.of(URI)} with the given parameter.
86 *
87 * @param uri
88 * the URI to convert
89 *
90 * @return the resulting {@code Path}
91 *
92 * @throws IllegalArgumentException
93 * if preconditions on the {@code uri} parameter do not hold. The
94 * format of the URI is provider specific.
95 * @throws FileSystemNotFoundException
96 * The file system, identified by the URI, does not exist and
97 * cannot be created automatically, or the provider identified by
98 * the URI's scheme component is not installed
99 * @throws SecurityException
100 * if a security manager is installed and it denies an unspecified
101 * permission to access the file system
102 *
103 * @see Path#of(URI)
104 */
105 public static Path get(URI uri) {
106 return Path.of(uri);
107 }
108
109 /**
110 * Returns a list of path strings parsed from a string with empty paths removed.
111 * The {@link File#pathSeparator} is used to split the string and
112 * empty strings are removed. A list is created of the remaining strings.
113 * <p>
114 * The {@code pathSeparator} character can be included in a path
115 * on operating systems that support quoting segments of the string.
116 *
117 * @implNote On Windows, quoting of path segments is supported.
118 * Each {@link File#pathSeparator} between pairs of quotation marks (@code 'U+0022')
119 * is considered an ordinary character and the quotes are omitted from the path.
120 * An unmatched double-quote is matched by the end of the string.
121 *
122 * @param path a {@code non-null} string containing paths separated by
123 * {@link File#pathSeparator}.
124 * @return a {@code non-null} immutable list of strings for each non-empty path
125 */
126 public static List<String> pathToStrings(String path) {
127 Objects.requireNonNull(path, "path");
128 return List.of(PathParser.parsePath(path, null));
129 }
130
131 /**
132 * Returns a list of Paths parsed from a string with empty paths removed.
133 * The {@link File#pathSeparator} is used to split the string and
134 * empty strings are removed. A list is created of the remaining strings after
135 * mapping each string using {@link Path#of Path.of} using the
136 * {@link FileSystems#getDefault default} {@link FileSystem}.
137 * <p>
138 * The {@code pathSeparator} character can be included in a path
139 * on operating systems that support quoting segments of the string.
140 *
141 * @implNote On Windows, quoting of path segments is supported.
142 * Each {@link File#pathSeparator} between pairs of quotation marks (@code 'U+0022')
143 * is considered an ordinary character and the quotes are omitted from the path.
144 * An unmatched double-quote is matched by the end of the string.
145 *
146 * @param path a {@code non-null} string containing paths separated by
147 * {@link File#pathSeparator}.
148 * @return a {@code non-null} immutable list of Paths for each non-empty path
149 *
150 * @throws InvalidPathException
151 * if each path string cannot be converted to a {@code Path}
152 */
153 public static List<Path> pathToPaths(String path) {
154 Objects.requireNonNull(path, "path");
155 return Arrays.stream(PathParser.parsePath(path, null))
156 .map(s -> Path.of(s))
157 .collect(Collectors.toList());
158 }
159 }