Android File Rename rename(File file1, File file2)

Description

Trys to rename file1 to file2.

License

Open Source License

Parameter

Parameter	Description
file1	the currently existing file
file2	the file that is to be renamed to

Exception

Parameter	Description
IllegalArgumentException	if file1 is Check#validFile not valid;file2 == null; file2 already exists and is not equal to file1
SecurityException	if a security manager exists and denies write access to file1 or file2
IOException	if an I/O problem occurs; this includes failure of the file to be renamed

Return

file2

Declaration

public static File rename(File file1, File file2)
        throws IllegalArgumentException, SecurityException, IOException 

Method Source Code

/*//w w  w.j  a v a 2  s.co  m
Copyright ? 2008 Brent Boyer

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the Lesser GNU General Public License for more details.

You should have received a copy of the Lesser GNU General Public License along with this program (see the license directory in this project).  If not, see <http://www.gnu.org/licenses/>.
 */

import bb.science.FormatUtil;
import bb.util.Check;
import bb.util.StringUtil;
import bb.util.ThrowableUtil;
import bb.util.logging.LogUtil;
import java.io.File;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.io.RandomAccessFile;
import java.nio.ByteBuffer;
import java.nio.charset.CharacterCodingException;
import java.nio.charset.Charset;
import java.util.Random;
import java.util.logging.Level;
import org.junit.Assert;
import org.junit.Test;

public class Main{
    /**
     * Trys to rename file1 to file2.
     * Since file2 may be in a different directory and/or have a different name,
     * this is really a combined move/rename method.
     * <p>
     * This method was written because {@link File#renameTo File.renameTo} unfortunately
     * merely returns a boolean indicating the success of the operation, which forces the user to check.
     * In contrast, this method corrects that defect and throws an Exception instead.
     * <p>
     * Furthermore, for maximum safety, this method will never overwrite an existing but different file.
     * Therefore, it insists that file2 must not currently exist unless it is equal to file1.
     * (One reason why the user may wish to supply file2 equal to file1 is if their
     * operating system has case insensitive file names:
     * perhaps they are simply trying to change file1's name to a standard case.)
     * <p>
     * Note: {@link DirUtil#rename DirUtil.rename} should be used to rename directories.
     * <p>
     * @param file1 the currently existing file
     * @param file2 the file that is to be renamed to
     * @return file2
     * @throws IllegalArgumentException if file1 is {@link Check#validFile not valid};
     * file2 == null; file2 already exists and is not equal to file1
     * @throws SecurityException if a security manager exists and denies write access to file1 or file2
     * @throws IOException if an I/O problem occurs; this includes failure of the file to be renamed
     */
    public static File rename(File file1, File file2)
            throws IllegalArgumentException, SecurityException, IOException {
        Check.arg().validFile(file1);
        Check.arg().notNull(file2);
        if (file2.exists() && !file1.equals(file2))
            throw new IllegalArgumentException("file2 = " + file2.getPath()
                    + " already exists and is not equal to file1 = "
                    + file1.getPath());

        boolean renamed = file1.renameTo(file2);
        if (!renamed)
            throw new IOException("failed to rename file1 = "
                    + file1.getPath() + " to file2 = " + file2.getPath());
        return file2;
    }
}

Related

1. mark(String pathName, String tag)
2. rename(File fromFile, File toFile)
3. rename(String from, String to)
4. rename(String oldName, String newName)
5. renameAs(String pathDir, String name, String wishName)