1 /*
2 * Copyright (c) 2007, 2009, 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 }