net.roydesign.io.SpecialFolder Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of mrjadapter Show documentation
MRJ Adapter is a wrapper around built in Java Virtual Machine APIs provided by Apple.
The newest version!
/*******************************************************************************

	File:		SpecialFolder.java
	Author:		Steve Roy 
				
	Part of MRJ Adapter, a unified API for easy integration of Mac OS specific
	functionality within your cross-platform Java application.
	
	This library is open source and can be modified and/or distributed under
	the terms of the Artistic License.
	
	
	Change History:
	02/14/03	Created this file - Steve
	03/19/04    Added use of java.io.tmpdir in getTemporaryItemsFolder() - Steve
	05/24/04    Made getPreferencesFolder() return user.home instead of
				throwing a FileNotFoundException - Steve

*******************************************************************************/

package net.roydesign.io;

import net.roydesign.mac.MRJAdapter;
import net.roydesign.mac.MRJFolderConstants;

import java.io.File;
import java.io.FileNotFoundException;

/**
 * A collection of static methods for locating special folders in the file system.
 * Examples of special folders are the home directory and the preferences folder.
 * This class is highly platform dependant and is also quite minimal at this stage
 * in terms of supported platforms. The idea is to add to it as development needs
 * come up. Code contributions are welcome.
 * 
 * @version MRJ Adapter 1.2
 */
public final class SpecialFolder
{
	/**
	 * The name of the OS, from the os.name system property.
	 */
	private static final String osName = System.getProperty("os.name");
	
	/**
	 * The default constructor is private so this class can't
	 * be instantiated.
	 */
	private SpecialFolder()
	{
	}
	
	/**
	 * Get the home directory of the current user.
	 * @return the home directory
	 */
	public static File getHomeFolder()
	{
		return new File(System.getProperty("user.home"));
	}
	
	/**
	 * Get the preferences folder for the current user.
	 * @return the preferences folder
	 * @exception FileNotFoundException if the folder can't be found
	 */
	public static File getPreferencesFolder() throws FileNotFoundException
	{
		return MRJAdapter.findFolder(MRJFolderConstants.kUserDomain,
			MRJFolderConstants.kPreferencesFolderType, true);
	}
	
	/**
	 * Get the temporary items folder.
	 * @return the temporary items folder
	 * @exception FileNotFoundException if the folder can't be found
	 */
	public static File getTemporaryItemsFolder() throws FileNotFoundException
	{
		return MRJAdapter.findFolder(MRJFolderConstants.kUserDomain,
			MRJFolderConstants.kTemporaryFolderType, true);
	}
	
	/**
	 * Get the desktop folder for the current user.
	 * @return the desktop folder
	 * @exception FileNotFoundException if the folder can't be found
	 */
	public static File getDesktopFolder() throws FileNotFoundException
	{
		return MRJAdapter.findFolder(MRJFolderConstants.kUserDomain,
			MRJFolderConstants.kDesktopFolderType, true);
	}
	
	/**
	 * Find a special Mac OS folder. This method locates on disk a folder
	 * designated by the Mac OS for a specific purpose.
	 * @param domain the domain of the folder
	 * @param type the type code of the folder to find
	 * @param create whether to create the folder if it doesn't already exist
	 * @return the special folder object
	 * @exception FileNotFoundException when the folder can't be found
	 * @see MRJAdapter#findFolder
	 */
	public static File findMacFolder(short domain, String type, boolean create)
		throws FileNotFoundException
	{
		return findFolder(domain, type, create);
	}

	/**
	 * Find a special Mac OS folder. This method locates on disk a folder
	 * designated by the OS for a specific purpose. For example, this can be
	 * the Preferences folder or the Desktop folder. Sometimes such folders
	 * exist in multiple versions for different contexts, which is why the
	 * method requires a domain to be specified. Most of the time, you will
	 * want to use the value {@code MRJFolderConstants.kUserDomain}. Then
	 * you have to specify the type of the folder that you're looking for.
	 * Each such folder is identified by a unique code. Just like file types
	 * and creators, this code is four characters long and case sensitive.
	 * If there's a constant defined in {@code MRJFolderConstants} for the
	 * folder you're looking for then you should use the other form of this
	 * method. Otherwise, pass the type as a string. The format of the type
	 * code will be normalized to be four-characters long if it isn't already.
	 * Look in Folders.h of the Carbon interfaces for possible values to be
	 * passed. This method throws a {@code FileNotFoundException}
	 * on other platforms.
	 * @param domain the domain of the folder
	 * @param type the type code of the folder to find
	 * @param create whether to create the folder if it doesn't already exist
	 * @return the special folder object\
	 * @exception FileNotFoundException when the folder can't be found
	 */
	public static File findFolder(short domain, String type, boolean create)
		throws FileNotFoundException
	{
		return MRJAdapter.findFolder(domain, MRJAdapter.fourCharCodeToInt(type), create);
	}
}