/* *  @(#)File.java	1.5 01/05/01 * *  Copyright (c) 2001 Sun Microsystems, Inc., 901 San Antonio Road, *  Palo Alto, CA 94303, U.S.A.  All Rights Reserved. * *  Sun Microsystems, Inc. has intellectual property rights relating *  to the technology embodied in this software.  In particular, and *  without limitation, these intellectual property rights may include *  one or more U.S. patents, foreign patents, or pending *  applications.  Sun, Sun Microsystems, the Sun logo, Java, KJava, *  and all Sun-based and Java-based marks are trademarks or *  registered trademarks of Sun Microsystems, Inc.  in the United *  States and other countries. * *  This software is distributed under licenses restricting its use, *  copying, distribution, and decompilation.  No part of this *  software may be reproduced in any form by any means without prior *  written authorization of Sun and its licensors, if any. * *  FEDERAL ACQUISITIONS:  Commercial Software -- Government Users *  Subject to Standard License Terms and Conditions */package com.sun.midp.io.j2me.storage;import java.io.IOException;import java.util.Vector;import com.sun.midp.security.SecurityDomain;import com.sun.midp.security.Actions;import com.sun.midp.midlet.Scheduler;import com.sun.midp.midlet.MIDletSuite;/** * 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;        }    }    /**     * Converts <code>string</code> into a null terminated     * byte array.  Expects the characters in <code>string     * </code> to be in th Ascii range (0-127 base 10).     *     * @param string the string to convert     *     * @return byte array with contents of <code>string</code>     */    public static byte[] toCString(String string) {        int length = string.length();        byte[] cString = new byte[length + 1];        for (int i = 0; i < length; i++) {            cString[i] = (byte)string.charAt(i);        }        return cString;    }    /**     * 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.checkIfPermitted(Actions.DEVICE_CORE_FUNCTION);        }    }    /**     * Constructs a file object.     *     * @param callerSecurityDomain a SecurityDomain object     */    public File(SecurityDomain callerSecurityDomain) {        callerSecurityDomain.checkIfPermitted(Actions.DEVICE_CORE_FUNCTION);    }    /**     * 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 = toCString(oldName);        byte[] newAsciiFilename = 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 = 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 = 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 = 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();}