1 /* 2 * Copyright (c) 2007, 2011, 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 */ 37 38 public final class Paths { 39 private Paths() { } 40 41 /** 42 * 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 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 * 57 * <p> The {@code Path} is obtained by invoking the {@link FileSystem#getPath 58 * getPath} method of the {@link FileSystems#getDefault default} {@link 59 * FileSystem}. 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 * 71 * @param first 72 * the path string or initial part of the path string 73 * @param more 74 * additional strings to be joined to form the path string 75 * 76 * @return the resulting {@code Path} 77 * 78 * @throws InvalidPathException 79 * if the path string cannot be converted to a {@code Path} 80 * 81 * @see FileSystem#getPath 82 */ 83 public static Path get(String first, String... more) { 84 return FileSystems.getDefault().getPath(first, more); 85 } 86 87 /** 88 * Converts the given URI to a {@link Path} object. 89 * 90 * <p> This method iterates over the {@link FileSystemProvider#installedProviders() 91 * installed} providers to locate the provider that is identified by the 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><tt> 107 * Paths.get(</tt><i>p</i><tt>.{@link Path#toUri() toUri}()).equals(</tt> 108 * <i>p</i><tt>.{@link Path#toAbsolutePath() toAbsolutePath}())</tt> 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 * 115 * @param uri 116 * the URI to convert 117 * 118 * @return the resulting {@code Path} 119 * 120 * @throws IllegalArgumentException 121 * if preconditions on the {@code uri} parameter do not hold. The 122 * format of the URI is provider specific. 123 * @throws FileSystemNotFoundException 124 * The file system, identified by the URI, does not exist and 125 * cannot be created automatically, or the provider identified by 126 * the URI's scheme component is not installed 127 * @throws SecurityException 128 * if a security manager is installed and it denies an unspecified 129 * permission to access the file system 130 */ 131 public static Path get(URI uri) { 132 String scheme = uri.getScheme(); 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 } 149 } 150
