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