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 }