001 /*
002 * This file is part of muCommander, http://www.mucommander.com
003 * Copyright (C) 2002-2008 Maxence Bernard
004 *
005 * muCommander is free software; you can redistribute it and/or modify
006 * it under the terms of the GNU General Public License as published by
007 * the Free Software Foundation; either version 3 of the License, or
008 * (at your option) any later version.
009 *
010 * muCommander is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
013 * GNU General Public License for more details.
014 *
015 * You should have received a copy of the GNU General Public License
016 * along with this program. If not, see <http://www.gnu.org/licenses/>.
017 */
018
019 package com.mucommander.desktop;
020
021 import com.mucommander.file.AbstractFile;
022
023 /**
024 * AbstractTrash is an abstract representation of a file trash, i.e. a temporary place where deleted files are stored
025 * before the trash is emptied. A trash implementation provides methods to access basic trash operations: move files
026 * to the trash, empty the trash, ...
027 *
028 * <p>Since AbstractTrash implementations are system-dependent, they should not be instanciated directly.
029 * Use {@link DesktopManager#getTrash()} to retrieve an instance of a trash implementation that can
030 * be used on the current platform.<br>
031 * Also, some AbstractTrash subclasses may not be able to provide working implementations for all trash operations;
032 * probe methods are provided to find out if a particular operation is available.</p>
033 *
034 * @see TrashProvider
035 * @see DesktopManager#getTrash()
036 * @author Maxence Bernard
037 */
038 public abstract class AbstractTrash {
039
040 /**
041 * Returns <code>true</code> if the specified file is eligible for being moved to the trash. This doesn't mean that
042 * a call to {@link #moveToTrash(com.mucommander.file.AbstractFile)} will necessarily succeed, but it should at least ensure that basic
043 * prerequisites are met.
044 *
045 * @param file the file to test
046 * @return true if the given file can be moved to the trash
047 */
048 public abstract boolean canMoveToTrash(AbstractFile file);
049
050 /**
051 * Attempts to move the given file to the trash and returns <code>true</code> if the file could be moved successfully.
052 *
053 * @param file the file to move to the trash
054 * @return true if the file could successfully be moved to the trash
055 */
056 public abstract boolean moveToTrash(AbstractFile file);
057
058 /**
059 * Returns <code>true</code> if this trash can be emptied.
060 *
061 * @return true if the trash can be emptied.
062 */
063 public abstract boolean canEmpty();
064
065 /**
066 * Attempts to empty this trash and returns <code>true</code> if it was successfully emptied.
067 *
068 * @return true if the trash was successfully emptied
069 */
070 public abstract boolean empty();
071
072 /**
073 * Returns <code>true</code> if the given file is a trash folder, or one of its children.
074 * For example, if <code>/home/someuser/.Trash</code> is a trash folder, calling this method with:
075 * <ul>
076 * <li><code>/home/someuser/.Trash</code> will return <code>true</code>
077 * <li><code>/home/someuser/.Trash/somefolder/somefile</code> will return <code>true</code>
078 * <li><code>/home/someuser/Desktop</code> will return <code>false</code>
079 * </ul>
080 *
081 * <p>Note that this method does not check the existence of the given file, the test is solely based on the
082 * file's path.
083 *
084 * @param file the file to test
085 * @return true if the given file is a trash folder, or one of its children.
086 */
087 public abstract boolean isTrashFile(AbstractFile file);
088
089 /**
090 * Returns the number of items that currently are in this trash, <code>-1</code> if this information is not available.
091 *
092 * @return the number of items that currently are in this trash, <code>-1</code> if this information is not available
093 */
094 public abstract int getItemCount();
095
096 /**
097 * Opens the trash in the default file manager of the current OS/Desktop manager.
098 */
099 public abstract void open();
100
101 /**
102 * Returns <code>true</code> if this trash can be opened in the default file manager of the current OS/Desktop manager
103 * by calling {@link #open()}.
104 *
105 * @return true if this trash can be opened in the default file manager of the current OS/Desktop manager.
106 */
107 public abstract boolean canOpen();
108
109 /**
110 * Waits (locks the caller thread) until all pending trash operations are completed.
111 * This method can be useful since some <code>AbstractTrash</code> implementations are asynchroneous, i.e. perform
112 * operations in separate threads.
113 */
114 public abstract void waitForPendingOperations();
115 }