1 /*
2 * Copyright (c) 2011, 2019, 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 com.apple.eio;
27
28 import java.io.*;
29
30 /**
31 * Provides functionality to query and modify Mac-specific file attributes. The methods in this class are based on Finder
32 * attributes. These attributes in turn are dependent on HFS and HFS+ file systems. As such, it is important to recognize
33 * their limitation when writing code that must function well across multiple platforms.<p>
34 *
35 * In addition to file name suffixes, Mac OS X can use Finder attributes like file {@code type} and {@code creator} codes to
36 * identify and handle files. These codes are unique 4-byte identifiers. The file {@code type} is a string that describes the
37 * contents of a file. For example, the file type {@code APPL} identifies the file as an application and therefore
38 * executable. A file type of {@code TEXT} means that the file contains raw text. Any application that can read raw
39 * text can open a file of type {@code TEXT}. Applications that use proprietary file types might assign their files a proprietary
40 * file {@code type} code.
41 * <p>
42 * To identify the application that can handle a document, the Finder can look at the {@code creator}. For example, if a user
43 * double-clicks on a document with the {@code ttxt creator}, it opens up in Text Edit, the application registered
44 * with the {@code ttxt creator} code. Note that the {@code creator}
45 * code can be set to any application, not necessarily the application that created it. For example, if you
46 * use an editor to create an HTML document, you might want to assign a browser's {@code creator} code for the file rather than
47 * the HTML editor's {@code creator} code. Double-clicking on the document then opens the appropriate browser rather than the
48 *HTML editor.
49 *<p>
50 * If you plan to publicly distribute your application, you must register its creator and any proprietary file types with the Apple
51 * Developer Connection to avoid collisions with codes used by other developers. You can register a codes online at the
52 * <a target=_blank href=http://developer.apple.com/dev/cftype/>Creator Code Registration</a> site.
53 *
54 * @since 1.4
55 */
56 public class FileManager {
57 static {
58 jdk.internal.access.SharedSecrets.getJavaLangAccess().loadLibrary("osx");
59 }
60
61 /**
62 * The default
63 * @since Java for Mac OS X 10.5 - 1.5
64 * @since Java for Mac OS X 10.5 Update 1 - 1.6
65 */
66 public static final short kOnAppropriateDisk = -32767;
67 /**
68 * Read-only system hierarchy.
69 * @since Java for Mac OS X 10.5 - 1.5
70 * @since Java for Mac OS X 10.5 Update 1 - 1.6
71 */
72 public static final short kSystemDomain = -32766;
73 /**
74 * All users of a single machine have access to these resources.
75 * @since Java for Mac OS X 10.5 - 1.5
76 * @since Java for Mac OS X 10.5 Update 1 - 1.6
77 */
78 public static final short kLocalDomain = -32765;
79 /**
80 * All users configured to use a common network server has access to these resources.
81 * @since Java for Mac OS X 10.5 - 1.5
82 * @since Java for Mac OS X 10.5 Update 1 - 1.6
83 */
84 public static final short kNetworkDomain = -32764;
85 /**
86 * Read/write. Resources that are private to the user.
87 * @since Java for Mac OS X 10.5 - 1.5
88 * @since Java for Mac OS X 10.5 Update 1 - 1.6
89 */
90 public static final short kUserDomain = -32763;
91
92
93 /**
94 * Converts an OSType (e.g. "macs"
95 * from {@literal <CarbonCore/Folders.h>}) into an int.
96 *
97 * @param type the 4 character type to convert.
98 * @return an int representing the 4 character value
99 *
100 * @since Java for Mac OS X 10.5 - 1.5
101 * @since Java for Mac OS X 10.5 Update 1 - 1.6
102 */
103 @SuppressWarnings("deprecation")
104 public static int OSTypeToInt(String type) {
105 int result = 0;
106
107 byte[] b = { (byte) 0, (byte) 0, (byte) 0, (byte) 0 };
108 int len = type.length();
109 if (len > 0) {
110 if (len > 4) len = 4;
111 type.getBytes(0, len, b, 4 - len);
112 }
113
114 for (int i = 0; i < len; i++) {
115 if (i > 0) result <<= 8;
116 result |= (b[i] & 0xff);
117 }
118
119 return result;
120 }
121
122 /**
123 * Sets the file {@code type} and {@code creator} codes for a file or folder.
124 *
125 * @since 1.4
126 */
127 public static void setFileTypeAndCreator(String filename, int type, int creator) throws IOException {
128 SecurityManager security = System.getSecurityManager();
129 if (security != null) {
130 security.checkWrite(filename);
131 }
132 _setFileTypeAndCreator(filename, type, creator);
133 }
134 private static native void _setFileTypeAndCreator(String filename, int type, int creator) throws IOException;
135
136 /**
137 * Sets the file {@code type} code for a file or folder.
138 *
139 * @since 1.4
140 */
141 public static void setFileType(String filename, int type) throws IOException {
142 SecurityManager security = System.getSecurityManager();
143 if (security != null) {
144 security.checkWrite(filename);
145 }
146 _setFileType(filename, type);
147 }
148 private static native void _setFileType(String filename, int type) throws IOException;
149
150 /**
151 * Sets the file {@code creator} code for a file or folder.
152 *
153 * @since 1.4
154 */
155 public static void setFileCreator(String filename, int creator) throws IOException {
156 SecurityManager security = System.getSecurityManager();
157 if (security != null) {
158 security.checkWrite(filename);
159 }
160 _setFileCreator(filename, creator);
161 }
162 private static native void _setFileCreator(String filename, int creator) throws IOException;
163
164 /**
165 * Obtains the file {@code type} code for a file or folder.
166 *
167 * @since 1.4
168 */
169 public static int getFileType(String filename) throws IOException {
170 SecurityManager security = System.getSecurityManager();
171 if (security != null) {
172 security.checkRead(filename);
173 }
174 return _getFileType(filename);
175 }
176 private static native int _getFileType(String filename) throws IOException;
177
178 /**
179 * Obtains the file {@code creator} code for a file or folder.
180 *
181 * @since 1.4
182 */
183 public static int getFileCreator(String filename) throws IOException {
184 SecurityManager security = System.getSecurityManager();
185 if (security != null) {
186 security.checkRead(filename);
187 }
188 return _getFileCreator(filename);
189 }
190 private static native int _getFileCreator(String filename) throws IOException;
191
192
193 /**
194 * Locates a folder of a particular type. Mac OS X recognizes certain specific folders that have distinct purposes.
195 * For example, the user's desktop or temporary folder. These folders have corresponding codes. Given one of these codes,
196 * this method returns the path to that particular folder. Certain folders of a given type may appear in more than
197 * one domain. For example, although there is only one {@code root} folder, there are multiple {@code pref}
198 * folders. If this method is called to find the {@code pref} folder, it will return the first one it finds,
199 * the user's preferences folder in {@code ~/Library/Preferences}. To explicitly locate a folder in a certain
200 * domain use {@code findFolder(short domain, int folderType)} or
201 * {@code findFolder(short domain, int folderType, boolean createIfNeeded)}.
202 *
203 * @return the path to the folder searched for
204 *
205 * @since 1.4
206 */
207 public static String findFolder(int folderType) throws FileNotFoundException {
208 return findFolder(kOnAppropriateDisk, folderType);
209 }
210
211 /**
212 * Locates a folder of a particular type, within a given domain. Similar to {@code findFolder(int folderType)}
213 * except that the domain to look in can be specified. Valid values for {@code domain} include:
214 * <dl>
215 * <dt>user</dt>
216 * <dd>The User domain contains resources specific to the user who is currently logged in</dd>
217 * <dt>local</dt>
218 * <dd>The Local domain contains resources shared by all users of the system but are not needed for the system
219 * itself to run.</dd>
220 * <dt>network</dt>
221 * <dd>The Network domain contains resources shared by users of a local area network.</dd>
222 * <dt>system</dt>
223 * <dd>The System domain contains the operating system resources installed by Apple.</dd>
224 * </dl>
225 *
226 * @return the path to the folder searched for
227 *
228 * @since 1.4
229 */
230 public static String findFolder(short domain, int folderType) throws FileNotFoundException {
231 return findFolder(domain, folderType, false);
232 }
233
234 /**
235 * Locates a folder of a particular type within a given domain and optionally creating the folder if it does
236 * not exist. The behavior is similar to {@code findFolder(int folderType)} and
237 * {@code findFolder(short domain, int folderType)} except that it can create the folder if it does not already exist.
238 *
239 * @param createIfNeeded
240 * set to {@code true}, by setting to {@code false} the behavior will be the
241 * same as {@code findFolder(short domain, int folderType, boolean createIfNeeded)}
242 * @return the path to the folder searched for
243 *
244 * @since 1.4
245 */
246 public static String findFolder(short domain, int folderType, boolean createIfNeeded) throws FileNotFoundException {
247 final SecurityManager security = System.getSecurityManager();
248 if (security != null) {
249 security.checkPermission(new RuntimePermission("canExamineFileSystem"));
250 }
251
252 final String foundFolder = _findFolder(domain, folderType, createIfNeeded);
253 if (foundFolder == null) throw new FileNotFoundException("Can't find folder: " + Integer.toHexString(folderType));
254 return foundFolder;
255 }
256 private static native String _findFolder(short domain, int folderType, boolean createIfNeeded);
257
258
259 /**
260 * Opens the path specified by a URL in the appropriate application for that URL. HTTP URL's ({@code http://})
261 * open in the default browser as set in the Internet pane of System Preferences. File ({@code file://}) and
262 * FTP URL's ({@code ftp://}) open in the Finder. Note that opening an FTP URL will prompt the user for where
263 * they want to save the downloaded file(s).
264 *
265 * @param url
266 * the URL for the file you want to open, it can either be an HTTP, FTP, or file url
267 *
268 * @deprecated this functionality has been superseded by java.awt.Desktop.browse() and java.awt.Desktop.open()
269 *
270 * @since 1.4
271 */
272 @Deprecated
273 public static void openURL(String url) throws IOException {
274 SecurityManager security = System.getSecurityManager();
275 if (security != null) {
276 security.checkPermission(new RuntimePermission("canOpenURLs"));
277 }
278 _openURL(url);
279 }
280 private static native void _openURL(String url) throws IOException;
281
282 /**
283 * @return full pathname for the resource identified by a given name.
284 *
285 * @since 1.4
286 */
287 public static String getResource(String resourceName) throws FileNotFoundException {
288 return getResourceFromBundle(resourceName, null, null);
289 }
290
291 /**
292 * @return full pathname for the resource identified by a given name and located in the specified bundle subdirectory.
293 *
294 * @since 1.4
295 */
296 public static String getResource(String resourceName, String subDirName) throws FileNotFoundException {
297 return getResourceFromBundle(resourceName, subDirName, null);
298 }
299
300 /**
301 * Returns the full pathname for the resource identified by the given name and file extension
302 * and located in the specified bundle subdirectory.
303 *
304 * If extension is an empty string or null, the returned pathname is the first one encountered where the
305 * file name exactly matches name.
306 *
307 * If subpath is null, this method searches the top-level nonlocalized resource directory (typically Resources)
308 * and the top-level of any language-specific directories. For example, suppose you have a modern bundle and
309 * specify "Documentation" for the subpath parameter. This method would first look in the
310 * Contents/Resources/Documentation directory of the bundle, followed by the Documentation subdirectories of
311 * each language-specific .lproj directory. (The search order for the language-specific directories
312 * corresponds to the user's preferences.) This method does not recurse through any other subdirectories at
313 * any of these locations. For more details see the AppKit NSBundle documentation.
314 *
315 * @return full pathname for the resource identified by the given name and file extension and located in the specified bundle subdirectory.
316 *
317 * @since 1.4
318 */
319 public static String getResource(String resourceName, String subDirName, String type) throws FileNotFoundException {
320 return getResourceFromBundle(resourceName, subDirName, type);
321 }
322
323 private static native String getNativeResourceFromBundle(String resourceName, String subDirName, String type) throws FileNotFoundException;
324 private static String getResourceFromBundle(String resourceName, String subDirName, String type) throws FileNotFoundException {
325 final SecurityManager security = System.getSecurityManager();
326 if (security != null) security.checkPermission(new RuntimePermission("canReadBundle"));
327
328 final String resourceFromBundle = getNativeResourceFromBundle(resourceName, subDirName, type);
329 if (resourceFromBundle == null) throw new FileNotFoundException(resourceName);
330 return resourceFromBundle;
331 }
332
333 /**
334 * Obtains the path to the current application's NSBundle, may not
335 * return a valid path if Java was launched from the command line.
336 *
337 * @return full pathname of the NSBundle of the current application executable.
338 *
339 * @since Java for Mac OS X 10.5 Update 1 - 1.6
340 * @since Java for Mac OS X 10.5 Update 2 - 1.5
341 */
342 public static String getPathToApplicationBundle() {
343 SecurityManager security = System.getSecurityManager();
344 if (security != null) security.checkPermission(new RuntimePermission("canReadBundle"));
345 return getNativePathToApplicationBundle();
346 }
347
348 private static native String getNativePathToApplicationBundle();
349
350 /**
351 * Moves the specified file to the Trash
352 *
353 * @param file the file
354 * @return returns true if the NSFileManager successfully moved the file to the Trash.
355 * @throws FileNotFoundException
356 *
357 * @since Java for Mac OS X 10.6 Update 1 - 1.6
358 * @since Java for Mac OS X 10.5 Update 6 - 1.6, 1.5
359 */
360 public static boolean moveToTrash(final File file) throws FileNotFoundException {
361 if (file == null) throw new FileNotFoundException();
362 final String fileName = file.getAbsolutePath();
363
364 final SecurityManager security = System.getSecurityManager();
365 if (security != null) security.checkDelete(fileName);
366
367 return _moveToTrash(fileName);
368 }
369
370 private static native boolean _moveToTrash(String fileName);
371
372 /**
373 * Reveals the specified file in the Finder
374 *
375 * @param file
376 * the file to reveal
377 * @return returns true if the NSFileManager successfully revealed the file in the Finder.
378 * @throws FileNotFoundException
379 *
380 * @since Java for Mac OS X 10.6 Update 1 - 1.6
381 * @since Java for Mac OS X 10.5 Update 6 - 1.6, 1.5
382 */
383 public static boolean revealInFinder(final File file) throws FileNotFoundException {
384 if (file == null || !file.exists()) throw new FileNotFoundException();
385 final String fileName = file.getAbsolutePath();
386
387 final SecurityManager security = System.getSecurityManager();
388 if (security != null) security.checkRead(fileName);
389
390 return _revealInFinder(fileName);
391 }
392
393 private static native boolean _revealInFinder(String fileName);
394 }