file.java

用于移动设备上的java虚拟机源代码

/*
 * @(#)File.java	1.14 02/08/14 @(#)
 *
 * Copyright (c) 2001 Sun Microsystems, Inc.  All rights reserved.
 * PROPRIETARY/CONFIDENTIAL
 * Use is subject to license terms.
 */

package com.sun.midp.io.j2me.storage;

import java.io.IOException;

import java.util.Vector;

import com.sun.midp.security.SecurityToken;
import com.sun.midp.security.Permissions;

import com.sun.midp.midlet.Scheduler;
import com.sun.midp.midlet.MIDletSuite;

import com.sun.midp.io.Util;

/**
 * Provide the methods to manage files in a device's persistant storage.
 */
public class File {
    /** Table to speed up the unicodeToAsciiFilename conversion method. */
    private static final char NUMS[] = {
        '0', '1', '2', '3', '4', '5', '6', '7',
        '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'
    };

    /** Caches the storage root to save repeated native method calls. */
    private static String storageRoot = null;

    /**
     * Returns the root to build storage filenames including an needed
     * file separators, abstracting difference of the file systems
     * of development and device platforms. Note the root is never null.
     *
     * @return root of any filename for accessing device persistant
     *         storage. 
     */
    public static String getStorageRoot() {
        if (storageRoot == null) {
            storageRoot = initStorageRoot();
        } 

        return storageRoot;
    }

    /**
     * Convert a file name into a form that can be safely stored on
     * an ANSI-compatible file system. All characters that are not
     * [A-Za-z0-9] are converted into %uuuu, where uuuu is the hex
     * representation of the character's unicode value. Note even
     * though "_" is allowed it is converted because we use it for
     * for internal purposes. Potential file separators are converted
     * so the native layer does not have deal with sub-directory hierachies.
     *
     * @param str a string that may contain any character
     * @return an equivalent string that contains only the "safe" characters.
     */
    public static String unicodeToAsciiFilename(String str) {
        StringBuffer sbuf = new StringBuffer();

        for (int i = 0; i < str.length(); i++) {
            char c = str.charAt(i);
            if ((c >= 'a' && c <= 'z') ||
                (c >= '0' && c <= '9')) {
                sbuf.append(c);
            } else if (c >= 'A' && c <= 'Z') {
		sbuf.append('#');
		sbuf.append(c);
	    } else {
                int v = (int)(c & 0xffff);
                sbuf.append('%');
                sbuf.append(NUMS[(v & 0xf000) >> 12]);
                sbuf.append(NUMS[(v & 0x0f00) >>  8]);
                sbuf.append(NUMS[(v & 0x00f0) >>  4]);
                sbuf.append(NUMS[(v & 0x000f) >>  0]);
            }
        }

        return sbuf.toString();
    }

    /**
     * Perform the reverse conversion of unicodeToAscii().
     *
     * @param str a string previously returned by escape()
     * @return the original string before the conversion by escape().
     */
    public static String asciiFilenameToUnicode(String str) {
        StringBuffer sbuf = new StringBuffer();

        for (int i = 0; i < str.length(); i++) {
            char c = str.charAt(i);
            if (c == '%') {
                int v = 0;

                v <<= 4; v += hexValue(str.charAt(i+1));
                v <<= 4; v += hexValue(str.charAt(i+2));
                v <<= 4; v += hexValue(str.charAt(i+3));
                v <<= 4; v += hexValue(str.charAt(i+4));

                i += 4;
                sbuf.append((char)(v & 0x0000ffff));
            } else if (c == '#') {
		// drop c
	    } else {
                sbuf.append(c);
            }
        }

        return sbuf.toString();
    }

    /**
     * A utility method that convert a hex character 0-9a-f to the
     * numerical value represented by this hex char.
     *
     * @param c the character to convert
     * @return the number represented by the character. E.g., '0' representes
     * the number 0x0, 'a' representes the number 0x0a, etc.
     */
    private static int hexValue(char c) {
        if (c >= '0' && c <= '9') {
            return ((int)c) - '0';
        } else {
            return ((int)c) - 'a' + 10;
        }
    }

    /**
     * Constructs a file object.
     */
    public File() {
        MIDletSuite midletSuite = Scheduler.getScheduler().getMIDletSuite();

        // if a MIDlet suite is not scheduled, assume the JAM is calling.
        if (midletSuite != null) {
            midletSuite.checkIfPermissionAllowed(Permissions.MIDP);
        }
    }

    /**
     * Constructs a file object.
     *
     * @param callerSecurityToken security token of the caller
     */
    public File(SecurityToken callerSecurityToken) {
        callerSecurityToken.checkIfPermissionAllowed(Permissions.MIDP);
    }

    /**
     * Replaces the current name of storage, <code>oldName</code>
     * with <code>newName</code>.
     *
     * @param oldName original name of storage file
     * @param newName new name for storage file
     * @exception IOException if an error occurs during rename
     */
    public synchronized void rename(String oldName, String newName)
            throws IOException {
        byte[] oldAsciiFilename = Util.toCString(oldName);
        byte[] newAsciiFilename = Util.toCString(newName);

        renameStorage(oldAsciiFilename, newAsciiFilename);
    }

    /**
     * Returns <code>true</code> if storage file <code>name</code>
     * exists.
     *
     * @param name name of storage file
     *
     * @return <code>true</code> if the named storage file exists
     */
    public synchronized boolean exists(String name) {
        byte[] asciiFilename = Util.toCString(name);

        return storageExists(asciiFilename);
    }

    /**
     * Finds the file names which start with prifix
     * <code>root</code>.
     *
     * @param root prefix to match in file names
     *
     * @return a <code>Vector</code> containing the matching file names.
     */
    public synchronized Vector filenamesThatStartWith(String root) {
        Vector list = new Vector();
        byte[] szRoot;
        String filename;

        szRoot = Util.toCString(root);
        filename = getFirstFileThatStartsWith(szRoot);
        while (filename != null) {
            list.addElement(filename);
            filename = getNextFileThatStartsWith(szRoot);
        }

        return list;
    }

    /**
     * Remove a file from storage if it exists.
     *
     * @param name name of the file to delete
     * @exception IOException if an error occurs during delete
     */
    public synchronized void delete(String name)
            throws IOException {
        byte[] asciiFilename = Util.toCString(name);

        deleteStorage(asciiFilename);
    }

    /**
     * Retrieves the approximate space available to grow or
     * create new storage files.
     *
     * @return approximate number of free bytes in storage
     */
    public int getBytesAvailableForFiles() {
        return availableStorage();
    }

    /**
     * Initializes storage root for this file instance.
     *
     * @return path of the storage root
     */
    private static native String initStorageRoot();

    /**
     * Renames storage file.
     *
     * @param szOldName old name of storage file
     * @param szNewName new name for storage file
     */
    private static native void renameStorage(byte[] szOldName,
                                             byte[] szNewName)
        throws IOException;
    
    /**
     * Determines if a storage file matching szFilename exists.
     *
     * @param szFilename storage file to match
     *
     * @return <code>true</code> if storage indicated by 
     *         <code>szFilename</code> exists
     */
    private static native boolean storageExists(byte[] szFilename);

    /**
     * Removes storage file szFilename.
     *
     * @param szFilename storage file to delete
     *
     * @exception IOException if an error occurs during deletion
     */
    private static native void deleteStorage(byte[] szFilename)
        throws IOException;

    /**
     * The calling method should be synchronzed and call
     * getNextFileThatStartsWith until it returns null since
     * they share static state information.
     *
     * @param szRoot prefix string to mach in return value
     *
     * @return the first storage file to contain <code>szRoot</code>
     *         as a prefix
     */
    private static native String getFirstFileThatStartsWith(byte[] szRoot);

    /**
     * getFirstFileThatStartsWith must becalled first since it sets up
     * some shared static state.
     *
     * @param szRoot prefix string to match in return value
     *
     * @return the 'next' storage file to contain <code>szRoot</code>
     *         as a prefix
     */
    private static native String getNextFileThatStartsWith(byte[] szRoot);

    /**
     * Gets the approximate number of free storage bytes remaining.
     *
     * @return free storage space remaining, in bytes
     */
    private static native int availableStorage();
}