rev 51675 : 8207690: Parsing API for classpath and similar path strings
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 } --- EOF ---