/*

* Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:

*

*/

package com.nokia.mj.impl.fileutils;

import java.io.DataInputStream;

import java.io.DataOutputStream;

import java.io.IOException;

import java.io.InputStream;

import java.io.OutputStream;

import java.lang.IllegalArgumentException;

import java.lang.SecurityException;

import java.util.Enumeration;

import java.util.Random;

import java.util.Vector;

import javax.microedition.io.Connector;

import com.nokia.mj.impl.rt.support.Finalizer;

import com.nokia.mj.impl.rt.support.Jvm;

import com.nokia.mj.impl.utils.Logger;

import com.nokia.mj.impl.utils.Tokenizer;

/**

 * FileUtility provides File handling APIs for internal use in OMJ.

 *

 * <p>

 * <strong>Creating FileUtility</strong>

 * <p>

 * The pathname used to create the FileUtility object must always be abolute. An

 * absolute pathname is complete in that no other information is required in

 * order to locate the file that it denotes. A relative pathname, in contrast,

 * must be interpreted in terms of information taken from some other pathname.

 * Relative paths cannot be passed to the constructor of FileUtility.

 * FileUtility.getCanonicalPath() can be used to resolve relative paths to

 * absolute path.

 * <p>

 * File URL can also be used to create FileUtility object. The format of the

 * input string used to access a FileUtility must follow the format of a

 * fully-qualified, absolute path file name as described by the file URL format

 * in IETF RFCs 1738 & 2396.

 *

 * <p>

 * <strong>FileUtility Behavior</strong>

 * <p>

 * FileUtility can be created immeterial of whether the intended iTarget exists

 * or not. This behavior allows the creation of new files and directories on a

 * file system. For example, the following code snippet can be used to create a

 * file on the file system.

 *

 * <pre>

 * try

 * {

 *     FileUtility fileTarget = new FileUtility("/home/user1/newFile.txt");

 *     // If no exception is thrown, URI is valid, but file may or may not exist

 *

 *     if (!fileTarget.exists())

 *     {

 *         fileTarget.createNewFile();

 *     }

 *

 *     fileTarget = null;

 * }

 * catch (IOException ex)

 * {

 * }

 * </pre>

 *

 * Developers should always check for the file's or directory's existence after

 * a construction to determine if the file or directory actually exists.

 * Similarly, files or directories can be deleted using the delete() method.

 *

 * <p>

 * <strong>Streams in FileUtility</strong>

 * <p>

 * Input and output streams may be opened and closed multiple times on a

 * FileUtility instance.<br/>

 *

 * All FileUtility instances have one underlying InputStream and one

 * OutputStream. Opening a DataInputStream counts as opening an InputStream, and

 * opening a DataOutputStream counts as opening an OutputStream. A FileUtility

 * instance can have only one InputStream and one OutputStream open at any one

 * time. Trying to open more than one InputStream or more than one OutputStream

 * from a StreamConnection causes an IOException. Further detials can be found

 * in Common Streams.

 * <p>

 * Instances of the FileUtility class are immutable; that is, once created, the

 * pathname represented by a FileUtility object will never change.

 *

 */

public final class FileUtility

{

    static

    {

        try

        {

            Jvm.loadSystemLibrary("javafileutils");

        }

        catch (Exception e)

        {

            Logger.ELOG(Logger.EJavaFile, "Unable to load javafileutils dll");

        }

    }

    // Contains the iTarget to which the instance of FileUtility is pointing to.

    private FileURL iTarget;

    private Finalizer iFinalizer;

    private FileStreamHandler iStreamHandler;

    private int iDrmIntent;

    private boolean iExecuteIntent;

    /**

     * File name passed here should be absolute path.

     *

     * @param aFilePath

     *            file/directory that FileUtility must work on.

     */

    public FileUtility(String aFilePath)

    {

        this(aFilePath, FileDRMContentHandler.Execute, false);

    }

    /**

     * Constructs a FileUtility with given parameters. This is to be used when

     * trying to access DRM protected content.

     *

     * @param aFilePath

     *            absolute path of the file/directory.

     * @param aDrmIntent

     *            intent with which the user wants to open the file. The DRM

     *            intent specified must be one of the values present in

     *            FileDRMContentHandler

     * @param aExecuteIntent

     *            specifies whether to execute the intent when an InputStream is

     *            opened on the file.

     * @see FileDRMContentHandler

     */

    public FileUtility(String aFilePath, int aDrmIntent, boolean aExecuteIntent)

    {

        // Create a new FileURL that needs to be used internally.

        iTarget = new FileURL(aFilePath);

        iFinalizer = registerFinalize();

        iStreamHandler = null;

        iDrmIntent = aDrmIntent;

        iExecuteIntent = aExecuteIntent;

    }

    /**

     * Registers with Finalizer to call a method when the object gets collected

     * by GC

     *

     * @return Finalizer object that will be notified when GC happens

     */

    private Finalizer registerFinalize()

    {

        return new Finalizer()

        {

            public void finalizeImpl()

            {

                doFinalize();

            }

        };

    }

    /**

     * Creates a new empty file in the specified directory, using the given

     * prefix and suffix strings to generate its name. If this method returns

     * successfully then it is guaranteed that:

     * <ol>

     * <li>The file denoted by the returned abstract pathname did not exist

     * before this method was invoked, and</li>

     * <li>Neither this method nor any of its variants will return the same

     * abstract pathname again in the current invocation of the virtual machine.

     * </li>

     * </ol>

     * <p>

     * The prefix argument must be at least three characters long. It is

     * recommended that the prefix be a short, meaningful string such as "hjb"

     * or "mail".<br/>

     * The suffix argument may be null, in which case the suffix ".tmp" will be

     * used. <br/>

     * The directory argument should not be null and must provide a directory to

     * which the file has to be created.

     * <p>

     * New file will be generated by concatenating the prefix, five or more

     * internally-generated characters, and the suffix.

     *

     * @param aPrefix

     *            The prefix string to be used in generating the file's name

     *            must be at least three characters long

     * @param aSuffix

     *            The suffix string to be used in generating the file's name may

     *            be null, in which case the suffix ".tmp" will be used

     * @param aDirectory

     *            The directory in which the file is to be created

     * @return A new FileUtility instance denoting the newly created file.

     * @throws IOException

     *             if the file could not be created or the directory does not

     *             exist

     * @throws IllegalArgumentException

     *             if the prefix is fewer than three characters or directory

     *             parameter is null

     * @throws SecurityException

     *             if access was not allowed to create a file in the directory

     *             specified

     */

    public static FileUtility createTempFile(String aPrefix, String aSuffix,

            FileUtility aDirectory) throws IOException

    {

        Logger.LOG(Logger.EJavaFile, Logger.EInfo,

                   "--> FileUtility.createTempFile() Prefix: " + aPrefix

                   + " Suffix: " + aSuffix);

        if ((aPrefix.length() < 3) || (null == aDirectory))

        {

            throw new IllegalArgumentException("Directory passed is null or "

                                               + " file prefix is invalid");

        }

        if (!aDirectory.exists())

        {

            Logger.WLOG(Logger.EJavaFile, "    FileUtility.createTempFile(): "

                        + "Directory specified does not exist.");

            throw new IOException(FileUtilityErrorStrings.TEMP_DIR_NOT_PRESENT

                                  + ": " + aDirectory);

        }

        if (!aDirectory.isDirectory())

        {

            Logger.WLOG(Logger.EJavaFile, "    FileUtility.createTempFile(): "

                        + "Argument passed is a file.");

            throw new IOException(FileUtilityErrorStrings.TARGET_POINTS_TO_FILE

                                  + ": " + aDirectory);

        }

        if (null == aSuffix)

        {

            aSuffix = ".tmp";

        }

        Random generator = new Random();

        int generated = 0;

        String midString, file;

        String parent = aDirectory.getPath() + aDirectory.getName();

        char separator = '/';

        if (parent.indexOf('\\') != -1)

        {

            separator = '\\';

        }

        if (!parent.endsWith("" + separator))

        {

            parent += separator;

        }

        do

        {

            // The file name generated should be unique in the folder.

            generated = generator.nextInt();

            midString = "" + generated;

            midString = midString.substring(midString.length() - 5);

            file = aPrefix + midString + aSuffix;

        }

        while (_exists(parent + file));

        Logger.LOG(Logger.EJavaFile, Logger.EJavaFile,

                   "    FileUtility.createTempFile(): Attempting to create "

                   + parent + file);

        // Create the temporary file

        FileUtility newTempFile = new FileUtility(parent + file);

        if (!newTempFile.createNewFile())

        {

            Logger.WLOG(Logger.EJavaFile,

                        "    FileUtility.createTempFile(): Create failed.");

            // File could not be created.

            throw new IOException(FileUtilityErrorStrings.UNABLE_TO_CREATE_FILE

                                  + ": " + newTempFile);

        }

        Logger.LOG(Logger.EJavaFile, Logger.EInfo,

                   "<-- FileUtility.createTempFile()");

        return newTempFile;

    }

    /**

     * Resolves incomplete path by prefixing the path with one of the roots of

     * the file system.

     * <p>

     *

     * <pre>

     * Example of S60:

     *     String resolved = FileUtility.resolve("\\data\\images\\existingFile");

     *     // resolved will be C:\data\images\existingFile

     * </pre>

     *

     * @param aPath

     *            incomplete path that does not contain drive information.

     * @return resolved path or null if not found

     */

    public static String resolveDrive(String aPath)

    {

        Logger.LOG(Logger.EJavaFile, Logger.EInfo,

                   "--> FileUtility.resolveDrive() Path: " + aPath);

        String retVal = null;

        String path = aPath;

        try

        {

            retVal = FilePlatformSpecifics.resolveDrive(path);

        }

        catch (Exception e)

        {

            retVal = null;

        }

        Logger.LOG(Logger.EJavaFile, Logger.EInfo,

                   "<-- FileUtility.resolveDrive() returns: " + retVal);

        return retVal;

    }

    /**

     * A canonical pathname is both absolute and unique. The precise definition

     * of canonical form is system-dependent. This method first converts this

     * pathname to absolute form if necessary, and then maps it to its unique

     * form in a system-dependent way. This typically involves removing

     * redundant names such as "." and ".." from the pathname, resolving

     * symbolic links (on UNIX platforms), and converting drive letters to a

     * standard case (on Microsoft Windows platforms).

     * <p>

     * Every pathname that denotes an existing file or directory has a unique

     * canonical form. Every pathname that denotes a nonexistent file or

     * directory also has a unique canonical form.

     *

     * @param aPath

     * @return The canonical pathname string denoting the same file or

     *         directory.

     * @throws IOException

     *             If an I/O error occurs, which is possible because the

     *             construction of the canonical pathname may require filesystem

     *             queries

     *

     */

    public static String getCanonicalPath(String aPath) throws IOException

    {

        Logger.LOG(Logger.EJavaFile, Logger.EInfo,

                   "--> FileUtility.getCanonicalPath() Path: " + aPath);

        char separator;

        String tmpPath = aPath;

        if (tmpPath.endsWith("/") || tmpPath.endsWith("\\"))

        {

            tmpPath = aPath.substring(0, aPath.length() - 1);

        }

        // Find separator and check to see if the same separator is used

        // everywhere.

        if (tmpPath.indexOf("/") != -1)

        {

            // Store the separator used.

            separator = '/';

            // In case any other kind of separator is used in the path

            if (tmpPath.indexOf("\\") != -1)

            {

                throw new IllegalArgumentException("Invalid path separator: "

                                                   + aPath);

            }

        }

        else if (tmpPath.indexOf("\\") != -1)

        {

            separator = '\\';

            if (tmpPath.indexOf("/") != -1)

            {

                throw new IllegalArgumentException("Invalid path separator: "

                                                   + aPath);

            }

        }

        else

        {

            // no separtor present in the input, return as it is

            return tmpPath;

        }

        // Split the path based on the separator used.

        String[] pathTokens = Tokenizer.split(tmpPath, "" + separator);

        String initialPath = pathTokens[0];

        if (pathTokens == null)

        {

            initialPath = "";

        }

        initialPath += separator;

        // Resolves in case path starts with "." or ".." or "/" or "\\"

        String path = _getRealPath(initialPath);

        int count = 1;

        String sub = null;

        while (count < pathTokens.length)

        {

            sub = pathTokens[count];

            count++;

            if (sub != null)

            {

                // null implies that path was sumething like //a, which must be

                // considered as /a. Hence we ignore and move on to the nex

                // token.

                if (sub.equals("."))

                {

                    // We need to stay in the current working directory.

                    continue;

                }

                else if (sub.equals(".."))

                {

                    // Substring the main one

                    if (path.indexOf(separator) == path.lastIndexOf(separator))

                    {

                        // We are already at the root, we cannot go further back

                        continue;

                    }

                    path = path.substring(0, path.lastIndexOf(separator, path

                                          .length() - 2));

                }

                else

                {

                    if (!path.endsWith("" + separator))

                    {

                        path += separator;

                    }

                    // Just append the thing. It is some string.

                    path += sub;

                }

                // Add the separator in the end.

                if (count != pathTokens.length)

                {

                    path += separator;

                }

                // In case there are any symbolic links, resolve them

                path = _getRealPath(path);

            }

        }

        // In case of symbolic paths, resolve it.

        String toReturn = _getRealPath(path);

        Logger.LOG(Logger.EJavaFile, Logger.EInfo,

                   "<-- FileUtility.getCanonicalPath(): " + toReturn);

        return toReturn;

    }

    /**

     * Get file Content ID. Only DRM protected files have content Id.

     *

     * @param full

     *            path to file.

     * @return Content ID. Null if cannot be read or does not exists.

     */

    public static String getContentId(String aPath)

    {

        return FilePlatformSpecifics.getContentId(aPath);

    }

    /**

     * Checks to see if the Stream Handler instance is already present in the

     * object. If it is not present, a new instance is created.

     *

     */

    private void createStreamHandler()

    {

        if (null == iStreamHandler)

        {

            String name = iTarget.getFullPath();

            if (FileDRMContentHandler.isDRMProtectedFile(name))

            {

                Logger.LOG(Logger.EJavaFile, Logger.EInfo,

                           "FileUtility.checkStreamHandler(): "

                           + "Choosing DRM content handler");

                iStreamHandler = new FileDRMContentHandler(name, iDrmIntent,

                        iExecuteIntent);

            }

            else

            {

                Logger.LOG(Logger.EJavaFile, Logger.EInfo,

                           "FileUtility.checkStreamHandler(): "

                           + "Choosing normal stream handler");

                iStreamHandler = new FileStreamHandler(name);

            }

        }

    }

    /**

     * Open and return an input stream for a connection. The connection's

     * iTarget must already exist and be accessible for the input stream to be

     * created.

     *

     * @return An open input stream

     * @throws IOException

     *             if an I/O error occurs, if the method is invoked on a

     *             directory, if the connection's iTarget does not yet exist, or