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