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 java.nio.file.spi.FileSystemProvider; 29 import java.net.URI; 30 31 /** 32 * This class consists exclusively of static methods that return a {@link Path} 33 * by converting a path string or {@link URI}. 34 * 35 * @since 1.7 36 * @see Path 37 */ 38 39 public final class Paths { 40 private Paths() { } 41 42 /** 43 * Converts a path string, or a sequence of strings that when joined form 44 * a path string, to a {@code Path}. If {@code more} does not specify any 45 * elements then the value of the {@code first} parameter is the path string 46 * to convert. If {@code more} specifies one or more elements then each 47 * non-empty string, including {@code first}, is considered to be a sequence 48 * of name elements (see {@link Path}) and is joined to form a path string. 49 * The details as to how the Strings are joined is provider specific but 50 * typically they will be joined using the {@link FileSystem#getSeparator 51 * name-separator} as the separator. For example, if the name separator is 52 * "{@code /}" and {@code getPath("/foo","bar","gus")} is invoked, then the 53 * path string {@code "/foo/bar/gus"} is converted to a {@code Path}. 54 * A {@code Path} representing an empty path is returned if {@code first} 55 * is the empty string and {@code more} does not contain any non-empty 56 * strings. 57 * 58 * <p> The {@code Path} is obtained by invoking the {@link FileSystem#getPath 59 * getPath} method of the {@link FileSystems#getDefault default} {@link 60 * FileSystem}. 61 * 62 * <p> Note that while this method is very convenient, using it will imply 63 * an assumed reference to the default {@code FileSystem} and limit the 64 * utility of the calling code. Hence it should not be used in library code 65 * intended for flexible reuse. A more flexible alternative is to use an 66 * existing {@code Path} instance as an anchor, such as: 67 * <pre> 68 * Path dir = ... 69 * Path path = dir.resolve("file"); 70 * </pre> 71 * 72 * @implSpec 73 * This method simply invokes {@link Path#get(String,String...) 74 * Path.get(String, String...)} with the given parameters. 75 * 76 * @param first 77 * the path string or initial part of the path string 78 * @param more 79 * additional strings to be joined to form the path string 80 * 81 * @return the resulting {@code Path} 82 * 83 * @throws InvalidPathException 84 * if the path string cannot be converted to a {@code Path} 85 * 86 * @see FileSystem#getPath 87 * @see Path#get(String,String...) 88 */ 89 public static Path get(String first, String... more) { 90 return Path.get(first, more); 91 } 92 93 /** 94 * Converts the given URI to a {@link Path} object. 95 * 96 * <p> This method iterates over the {@link FileSystemProvider#installedProviders() 97 * installed} providers to locate the provider that is identified by the 98 * URI {@link URI#getScheme scheme} of the given URI. URI schemes are 99 * compared without regard to case. If the provider is found then its {@link 100 * FileSystemProvider#getPath getPath} method is invoked to convert the 101 * URI. 102 * 103 * <p> In the case of the default provider, identified by the URI scheme 104 * "file", the given URI has a non-empty path component, and undefined query 105 * and fragment components. Whether the authority component may be present 106 * is platform specific. The returned {@code Path} is associated with the 107 * {@link FileSystems#getDefault default} file system. 108 * 109 * <p> The default provider provides a similar <em>round-trip</em> guarantee 110 * to the {@link java.io.File} class. For a given {@code Path} <i>p</i> it 111 * is guaranteed that 112 * <blockquote>{@code 113 * Paths.get(}<i>p</i>{@code .}{@link Path#toUri() toUri}{@code ()).equals(} 114 * <i>p</i>{@code .}{@link Path#toAbsolutePath() toAbsolutePath}{@code ())} 115 * </blockquote> 116 * so long as the original {@code Path}, the {@code URI}, and the new {@code 117 * Path} are all created in (possibly different invocations of) the same 118 * Java virtual machine. Whether other providers make any guarantees is 119 * provider specific and therefore unspecified. 120 * 121 * @implSpec 122 * <p> This method simply invokes {@link Path#get(URI) 123 * Path.get(URI)} with the given parameter. 124 * 125 * @param uri 126 * the URI to convert 127 * 128 * @return the resulting {@code Path} 129 * 130 * @throws IllegalArgumentException 131 * if preconditions on the {@code uri} parameter do not hold. The 132 * format of the URI is provider specific. 133 * @throws FileSystemNotFoundException 134 * The file system, identified by the URI, does not exist and 135 * cannot be created automatically, or the provider identified by 136 * the URI's scheme component is not installed 137 * @throws SecurityException 138 * if a security manager is installed and it denies an unspecified 139 * permission to access the file system 140 * 141 * @see Path#get(URI) 142 */ 143 public static Path get(URI uri) { 144 return Path.get(uri); 145 } 146 }