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 {
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      */
get(String first, String... more)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      */
get(URI uri)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