1 /* 2 * Copyright (c) 2015, 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 package java.awt.desktop; 26 27 import java.io.File; 28 import java.io.FileNotFoundException; 29 import java.io.IOException; 30 31 /** 32 * Provides functionality to query and modify Mac-specific file attributes. The methods in this class are based on Finder 33 * attributes. These attributes in turn are dependent on HFS and HFS+ file systems. As such, it is important to recognize 34 * their limitation when writing code that must function well across multiple platforms.<p> 35 * 36 * In addition to file name suffixes, Mac OS X can use Finder attributes like file <code>type</code> and <code>creator</code> codes to 37 * identify and handle files. These codes are unique 4-byte identifiers. The file <code>type</code> is a string that describes the 38 * contents of a file. For example, the file type <code>APPL</code> identifies the file as an application and therefore 39 * executable. A file type of <code>TEXT</code> means that the file contains raw text. Any application that can read raw 40 * text can open a file of type <code>TEXT</code>. Applications that use proprietary file types might assign their files a proprietary 41 * file <code>type</code> code. 42 * <p> 43 * To identify the application that can handle a document, the Finder can look at the <code>creator</code>. For example, if a user 44 * double-clicks on a document with the <code>ttxt</code> <code>creator</code>, it opens up in Text Edit, the application registered 45 * with the <code>ttxt</code> <code>creator</code> code. Note that the <code>creator</code> 46 * code can be set to any application, not necessarily the application that created it. For example, if you 47 * 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 48 * the HTML editor's <code>creator</code> code. Double-clicking on the document then opens the appropriate browser rather than the 49 *HTML editor. 50 *<p> 51 * If you plan to publicly distribute your application, you must register its creator and any proprietary file types with the Apple 52 * Developer Connection to avoid collisions with codes used by other developers. You can register a codes online at the 53 * <a target=_blank href=http://developer.apple.com/dev/cftype/>Creator Code Registration</a> site. 54 */ 55 public abstract class FileManager { 56 57 /** 58 * The default. 59 */ 60 public static final short kOnAppropriateDisk = -32767; 61 62 /** 63 * Read-only system hierarchy. 64 */ 65 public static final short kSystemDomain = -32766; 66 67 /** 68 * All users of a single machine have access to these resources. 69 */ 70 public static final short kLocalDomain = -32765; 71 72 /** 73 * All users configured to use a common network server has access to these 74 * resources. 75 */ 76 public static final short kNetworkDomain = -32764; 77 78 /** 79 * Read/write. Resources that are private to the user. 80 */ 81 public static final short kUserDomain = -32763; 82 83 /** 84 * Converts an OSType (e.g. "macs" from {@literal <CarbonCore/Folders.h>}) 85 * into an int. 86 * 87 * @param type the 4 character type to convert. 88 * @return an int representing the 4 character value 89 */ 90 public abstract int OSTypeToInt(String type); 91 92 /** 93 * Sets the file <code>type</code> and <code>creator</code> codes for a file 94 * or folder. 95 * 96 * @param filename file name 97 * @param type of a file 98 * @param creator for a file 99 * @throws java.io.IOException if an I/O exception occurs 100 */ 101 public abstract void setFileTypeAndCreator(String filename, int type, int creator) throws IOException; 102 103 /** 104 * Sets the file <code>type</code> code for a file or folder. 105 * 106 * @param filename file name 107 * @param type of a file 108 * @throws java.io.IOException if an I/O exception occurs 109 */ 110 public abstract void setFileType(String filename, int type) throws IOException; 111 112 /** 113 * Sets the file <code>creator</code> code for a file or folder. 114 * 115 * @param filename file name 116 * @param creator for a file 117 * @throws java.io.IOException if an I/O exception occurs 118 */ 119 public abstract void setFileCreator(String filename, int creator) throws IOException; 120 121 /** 122 * Obtains the file <code>type</code> code for a file or folder. 123 * 124 * @param filename file name 125 * @return file or folder type 126 * @throws java.io.IOException if an I/O exception occurs 127 */ 128 public abstract int getFileType(String filename) throws IOException; 129 130 /** 131 * Obtains the file <code>creator</code> code for a file or folder. 132 * 133 * @param filename file name 134 * @return creator for a file or folder 135 * @throws java.io.IOException if an I/O exception occurs 136 */ 137 public abstract int getFileCreator(String filename) throws IOException; 138 139 /** 140 * Locates a folder of a particular type. Mac OS X recognizes certain 141 * specific folders that have distinct purposes. For example, the user's 142 * desktop or temporary folder. These folders have corresponding codes. 143 * Given one of these codes, this method returns the path to that particular 144 * folder. Certain folders of a given type may appear in more than one 145 * domain. For example, although there is only one <code>root</code> folder, 146 * there are multiple <code>pref</code> folders. If this method is called to 147 * find the <code>pref</code> folder, it will return the first one it finds, 148 * the user's preferences folder in <code>~/Library/Preferences</code>. To 149 * explicitly locate a folder in a certain domain use 150 * <code>findFolder(short domain, int folderType)</code> or <code>findFolder(short domain, int folderType, 151 * boolean createIfNeeded)</code>. 152 * 153 * @param folderType folder type 154 * @return the path to the folder searched for 155 * @throws java.io.FileNotFoundException if the folder does not exist 156 */ 157 public abstract String findFolder(int folderType) throws FileNotFoundException; 158 159 /** 160 * Locates a folder of a particular type, within a given domain. Similar to 161 * <code>findFolder(int folderType)</code> except that the domain to look in 162 * can be specified. Valid values for <code>domain</code>include: 163 * <dl> 164 * <dt>user</dt> 165 * <dd>The User domain contains resources specific to the user who is 166 * currently logged in</dd> 167 * <dt>local</dt> 168 * <dd>The Local domain contains resources shared by all users of the system 169 * but are not needed for the system itself to run.</dd> 170 * <dt>network</dt> 171 * <dd>The Network domain contains resources shared by users of a local area 172 * network.</dd> 173 * <dt>system</dt> 174 * <dd>The System domain contains the operating system resources installed 175 * by Apple.</dd> 176 * </dl> 177 * 178 * @param domain domain 179 * @param folderType folder type 180 * @return the path to the folder searched for 181 * @throws java.io.FileNotFoundException if the folder does not exist 182 */ 183 public abstract String findFolder(short domain, int folderType) throws FileNotFoundException; 184 185 /** 186 * Locates a folder of a particular type within a given domain and 187 * optionally creating the folder if it does not exist. The behavior is 188 * similar to <code>findFolder(int folderType)</code> and 189 * <code>findFolder(short domain, int folderType)</code> except that it can 190 * create the folder if it does not already exist. 191 * 192 * @param domain domain 193 * @param folderType folder type 194 * @param createIfNeeded set to <code>true</code>, by setting to 195 * <code>false</code> the behavior will be the same as 196 * <code>findFolder(short domain, int folderType, boolean createIfNeeded)</code> 197 * @return the path to the folder searched for 198 * @throws java.io.FileNotFoundException if the folder does not exist 199 */ 200 public abstract String findFolder(short domain, int folderType, 201 boolean createIfNeeded) throws FileNotFoundException; 202 203 204 /** 205 * Returns full pathname for the resource identified by a given name. 206 * 207 * @param resourceName resource name 208 * @return full pathname 209 * @throws java.io.FileNotFoundException if the resource does not exist 210 */ 211 public abstract String getResource(String resourceName) throws FileNotFoundException; 212 213 /** 214 * Returns full pathname for the resource identified by a given name and 215 * located in the specified bundle subdirectory. 216 * 217 * @param resourceName resource name 218 * @param subDirName subdirectory name 219 * @return full pathname 220 * @throws java.io.FileNotFoundException if the resource does not exist 221 */ 222 public abstract String getResource(String resourceName, String subDirName) 223 throws FileNotFoundException; 224 225 /** 226 * Returns the full pathname for the resource identified by the given name 227 * and file extension and located in the specified bundle subdirectory. 228 * 229 * If extension is an empty string or null, the returned pathname is the 230 * first one encountered where the file name exactly matches name. 231 * 232 * If subpath is null, this method searches the top-level nonlocalized 233 * resource directory (typically Resources) and the top-level of any 234 * language-specific directories. For example, suppose you have a modern 235 * bundle and specify "Documentation" for the subpath parameter. This method 236 * would first look in the Contents/Resources/Documentation directory of the 237 * bundle, followed by the Documentation subdirectories of each 238 * language-specific .lproj directory. (The search order for the 239 * language-specific directories corresponds to the user's preferences.) 240 * This method does not recurse through any other subdirectories at any of 241 * these locations. For more details see the AppKit NSBundle documentation. 242 * 243 * @param resourceName the name of the resource file 244 * @param subDirName subdirectory 245 * @param type type 246 * @return full pathname for the resource identified by the given name and 247 * file extension and located in the specified bundle subdirectory. 248 * @throws java.io.FileNotFoundException if the resource does not exist 249 */ 250 public abstract String getResource(String resourceName, String subDirName, 251 String type) throws FileNotFoundException; 252 253 /** 254 * Obtains the path to the current application's NSBundle, may not return a 255 * valid path if Java was launched from the command line. 256 * 257 * @return full pathname of the NSBundle of the current application 258 * executable. 259 */ 260 public abstract String getPathToApplicationBundle(); 261 262 /** 263 * Moves the specified file to the Trash 264 * 265 * @param file the file 266 * @return returns true if the NSFileManager successfully moved the file to 267 * the Trash. 268 * @throws FileNotFoundException if the file does not exist 269 */ 270 public abstract boolean moveToTrash(final File file) throws FileNotFoundException; 271 272 /** 273 * Reveals the specified file in the Finder 274 * 275 * @param file the file to reveal 276 * @return returns true if the NSFileManager successfully revealed the file 277 * in the Finder. 278 * @throws FileNotFoundException if the file does not exist 279 */ 280 public abstract boolean revealInFinder(final File file) throws FileNotFoundException; 281 }