Package opencard.opt.iso.fs

Class CardFile

  • All Implemented Interfaces:
    CardFileInfo
    public class CardFile
extends java.lang.Object
implements CardFileInfo
    Represents a file or directory on the smartcard. A card file object is a combination of an absolute path to the file represented, and the file information that was obtained from the smartcard on creation of the object. It provides methods to navigate through the smartcard's file system, and to obtain meta information about the files and directories therein. To access file contents, classes like CardFileInputStream, CardFileOutputStream, CardRandomByteAccess, or CardRandomRecordAccess can be instantiated.

    To instantiate class CardFile, a FileAccessCardService has to be provided. This service is used in the constructor to check whether the file that shall be represented actually exists, and to query meta information about the file. A card file object representing a directory or, in smartcard terminology, a dedicated file (DF), can be used to access other directories or files in the respective subtree of the smartcard's file system. The path names for these files must be relative to the represented directory. An absolute path will be created for newly created card file objects, which will use the same file service that was used by the parent object.
    Smartcards use 16 bit numbers to identify files and directories. Human friendly names are supported by a software layer, which has no platform dependencies. Card file names are represented by instances of class CardFilePath, for which different path components are defined. Class CardFile supports only path components that can be interpreted by the underlying file service. These components are file IDs, and optionally short file IDs and application identifiers. The string representation of a file ID is a colon, followed by a four digit hex number specifying the afforementioned 16 bit number. These file IDs can be concatenated to a path, for example ":BEEB:CAFE". Support for symbolic path names, like "/mama/papa/dog" may be added by derived classes.
    CardFilePath objects can be created directly from strings. To reduce memory requirements and to speed up operation, applications should create each path only once and use it directly later on, instead of using strings and creating paths any time they are needed. To enforce this behavior, only constructors of class CardFile accept strings instead of paths. The path created can be obtained using CardFile.getPath.

    Since the path to the file is part of this class, it corresponds to class java.io.File. Many of the methods found there are implemented here, too. Some others are implemented with slightly different signatures, but comparable functionality. However, there are significant differences between a standard disk file system and the file system on a smartcard, which are reflected in CardFile.
    Class java.io.file represents only a filename, on which symbolic operations can be performed, and which can be used to access an actual file on the underlying file system. Class CardFile represents actual files. It cannot be instantiated for files that do not exist. An operation like exists() does therefore not make sense. Other examples for methods that are not provided are renameTo and both list methods, since smartcards do not support file renaming, and typically do not support browsing directories.
    Traditional disk based file systems maintain file attributes like the time of the last modification, or access conditions. Smartcards do not support creation or modification times, and the access conditions are too complex to be mapped on methods as simple as canRead and canWrite. Support for platform dependent file separators, which is provided via attributes like pathSeparator in class java.io.File, do not make sense for smartcards either. The string representation of card file paths is interpreted by a platform neutral software layer.

    Class CardFile provides methods like create and delete, which are not supported by the interface FileAccessCardService. These methods are available only if an implementation of FileSystemCardService has been used to create the card file object. This is checked with the Java operator instanceof, so the methods may even be available if an application is not aware of it.
    The assumption for this implementation is that an application that needs creational methods will request a FileSystemCardService, while an application that does not need them will not invoke those methods. There is a small chance for programming errors if the file service used for testing implements both interfaces and there is no service that implements only FileAccessCardService.

    Author:
    Dirk Husemann (hud@zurich.ibm.com), Reto Hermann (rhe@zurich.ibm.com), Peter Trommler (trp@zurich.ibm.com), Roland Weber (rolweber@de.ibm.com)
    See Also:
    opencard.opt.iso.fs.CardFileInputStream, opencard.opt.iso.fs.CardFileOutputStream, opencard.opt.iso.fs.CardRandomByteAccess, opencard.opt.iso.fs.CardRandomRecordAccess, CardFilePath, getPath(), FileAccessCardService, FileSystemCardService, File, File.exists(), File.renameTo(java.io.File), File.list(), File.list(java.io.FilenameFilter), File.canRead(), File.canWrite(), File.pathSeparator

    • Field Detail

      • file_info

        protected CardFileInfo file_info
        The information about the file represented.

    • Constructor Detail

      • CardFile

        public CardFile​(FileAccessCardService service)
         throws java.io.FileNotFoundException,
                OpenCardException
        Creates a root card file. The new card file represents the top level directory, that is the master file (MF) of the smartcard's file hierarchy. This constructor replaces the mount method formerly found in FileSystemCardService.
        Parameters:
        service - the file service to use for accessing the smartcard
        Throws:
        java.io.FileNotFoundException - if the file to represent could not be found
        OpenCardException - if anything else went wrong

      • CardFile

        public CardFile​(FileAccessCardService service,
                CardFilePath abspath)
         throws java.io.FileNotFoundException,
                OpenCardException
        Creates a card file object for the specified absolute path.
        Parameters:
        service - the underlying file service
        abspath - the absolute path to the file to represent
        Throws:
        java.io.FileNotFoundException - if the file to represent could not be found
        OpenCardException - if anything else went wrong

      • CardFile

        public CardFile​(FileAccessCardService service,
                java.lang.String abspath)
         throws java.io.FileNotFoundException,
                OpenCardException
        Creates a card file object for an absolute path given as string.
        Parameters:
        service - the underlying file service
        abspath - a string holding the absolute path to the file to represent
        Throws:
        java.io.FileNotFoundException - if the file to represent could not be found
        OpenCardException - if anything else went wrong

      • CardFile

        public CardFile​(CardFile base,
                CardFilePath relpath)
         throws java.io.FileNotFoundException,
                OpenCardException
        Creates a card file for the specified relative path. The relative path is appended to the absolute path of the card file specified as base. If the relative path consists of a single component, the specified base card file object is considered to be the parent file of the newly created one.
        Parameters:
        base - the file representing the base directory
        relpath - the path to the file, relative to the base directory
        Throws:
        java.io.FileNotFoundException - if the file to represent could not be found
        OpenCardException - if anything else went wrong

      • CardFile

        public CardFile​(CardFile base,
                java.lang.String relpath)
         throws java.io.FileNotFoundException,
                OpenCardException
        Creates a card file for the relative path specified as string. The relative path is converted from a string to a CardFilePath. Then, the constructor expecting a path is invoked.
        Parameters:
        base - the file representing the base directory
        relpath - the path to the file, relative to the base directory
        Throws:
        java.io.FileNotFoundException - if the file to represent could not be found
        OpenCardException - if anything else went wrong
        See Also:
        CardFile(opencard.opt.iso.fs.CardFile, opencard.opt.iso.fs.CardFilePath)

      • CardFile

        public CardFile​(CardFile base,
                CardFilePathComponent comp)
         throws java.io.FileNotFoundException,
                OpenCardException
        Creates a card file for the specified path component. The path component is interpreted as a relative path. It is appended to the path of the file specified as the base, and the base is stored as the parent of the newly created card file object.
        Parameters:
        base - the file representing the base directory
        comp - the file in the base directory that will be represented
        Throws:
        java.io.FileNotFoundException - if the file to represent could not be found
        OpenCardException - if anything else went wrong

      • CardFile

        protected CardFile​(CardFilePath path,
                   FileAccessCardService service)
            throws java.io.FileNotFoundException,
                   CardServiceException,
                   CardTerminalException
        Creates a card file, for internal purposes. This is the generic constructor on which all other constructors are mapped. The file service is passed as the second argument instead of the first to distinguish this constructor from the public one.
        The path given as argument is stored immediately. If it has to be cloned to protect it from being modified, that has to be done by the caller. That's why this constructor is internal.
        Parameters:
        path - the absolute path to the file represented
        service - the file service to use for accessing the smartcard
        Throws:
        java.io.FileNotFoundException - If the file does not exist on the smartcard.
        CardServiceException - If the underlying file service encountered an error.
        CardTerminalException - If communication to the smartcard failed.

    • Method Detail

      • getCanonicalPath

        public final CardFilePath getCanonicalPath()
        Returns the canonical path of the file represented. The path returned is not allowed to be modified. It is an absolute path, so it is a suitable argument for the methods in the interfaces FileAccessCardService and FileSystemCardService.
        A canonical path consists only of components that can be interpreted by the underlying file service. These components are file ids and, optionally, short file ids and application ids. The canonical path never contains symbolic path components, even if support for these components is added in a derived class. That is the reason why this method has been declared final.
        Returns:
        the absolute, canonical path to the file represented
        See Also:
        getAbsolutePath()

      • getAbsolutePath

        public CardFilePath getAbsolutePath()
        Returns the absolute path of the file represented. In this class, the absolute path is the same as the canonical path. If support for symbolic path names is added in a dervied class, the absolute path may contain symbolic components, while the canonical path may not.
        Returns:
        the absolute path to the file represented
        See Also:
        getCanonicalPath()

      • getPath

        public final CardFilePath getPath()
        Returns the path of the file represented. This method is identical to getCanonicalPath, except for the name which is less clumsy. The path returned is not allowed to be modified. It is a suitable argument to methods in the interfaces FileAccessCardService and FileSystemCardService.
        Returns:
        the absolute, canonical path to the file represented
        See Also:
        getCanonicalPath(), FileAccessCardService, FileSystemCardService

      • getName

        public java.lang.String getName()
        Returns the name of the file represented. The name does not include the path to the file. If support for symbolic names is added in a derived class, a symbolic name is returned.
        Returns:
        the name of the file

      • isDirectory

        public final boolean isDirectory()
        Checks whether the file represented is a directory. Directories are also referred to as dedicated files (DF).
        Specified by:
        isDirectory in interface CardFileInfo
        Returns:
        true if the file represented is a directory, false otherwise
        See Also:
        CardFileInfo.isDirectory()

      • isFile

        public final boolean isFile()
        Checks whether the file represented is a non-directory file. This method is complementary to isDirectory.
        Returns:
        true if the file represented is not a directory, false otherwise
        See Also:
        isDirectory()

      • isDF

        public final boolean isDF()
        Checks whether this card file represents a dedicated file (directory). This method is identical to isDirectory, but has a shorter name that uses SmartCard terminology.
        Returns:
        true if the file represented is a DF, false otherwise
        See Also:
        isDirectory()

      • isEF

        public final boolean isEF()
        Checks whether this card file represents an elementary file. This method is identical to isFile, but has a shorter name that uses SmartCard terminology.
        Returns:
        true if the file represented is an EF, false otherwise
        See Also:
        isFile()

      • isCyclic

        public final boolean isCyclic()
        Checks whether the file represented is a cyclic file.
        Specified by:
        isCyclic in interface CardFileInfo
        Returns:
        true if this file is cyclic
        See Also:
        CardFileInfo.isCyclic()

      • isVariable

        public final boolean isVariable()
        Checks whether the file represented is a variable record file.
        Specified by:
        isVariable in interface CardFileInfo
        Returns:
        true if this file is a variable record file
        See Also:
        CardFileInfo.isVariable()

      • getHeader

        public final byte[] getHeader()
        Returns the header of the file represented. In case this method is removed from the interface CardFileInfo, it will be removed here, too. Currently, it must be available since this class implements that interface. However, the preferred method to get the file header from a card file is getFileInfo().getHeader().
        Specified by:
        getHeader in interface CardFileInfo
        Returns:
        the header of the file
        See Also:
        getFileInfo(), CardFileInfo, CardFileInfo.getHeader()

      • getFileAccessService

        protected final FileAccessCardService getFileAccessService()
        Returns the underlying file access card service.
        Returns:
        the underlying service for file access

      • getFileSystemService

        protected final FileSystemCardService getFileSystemService()
        Returns the underlying file system card service. If the underlying file service is not an instance of FileSystemCardService, null is returned.
        Returns:
        the underlying service for file system operations, or null if not available

      • resolvePath

        protected CardFilePath resolvePath​(CardFilePath path)
        Provides a hook for resolving symbolic path components. This method is meant to be overridden in derived classes that support symbolic path components. It is invoked by the constructors of this class. It's argument is a path that has been provided to one of them. It should return a path in which all symbolic components have been resolved and which satisfies the conditions described in getCanonicalPath.
        The path provided as argument must not be changed. The path returned will not be changed. The implementation provided here just returns the argument.
        Parameters:
        path - a path that may contain symbolic components
        Returns:
        a resolved path
        See Also:
        getCanonicalPath()

      • getParent

        public CardFile getParent()
        Return the parent CardFile. This method operates on the path name of the file. Note that it can climb above the CardFile that has been used as the base for creating this one. If the root of the directory structure is reached, or if an error occurred, null is returned.
        Returns:
        the parent file, or null if an error occurred

      • exists

        public boolean exists​(CardFilePath relpath)
        Tests whether a given file exists. The file to test for has to be specified by a path that is relative to the file represented by this card file object.
        Parameters:
        relpath - path to the file to check for existance
        Returns:
        true if the file exists, false if it doesn't

      • getFileInfo

        public final CardFileInfo getFileInfo()
        Returns information about the file represented. Since the interface CardFileInfo is implemented by this class too, the information typically needed is accessible directly. This method is intended to provide access to card or implementation specific information. It returns the information obtained by an invocation of getFileInfo in the interface FileAccessCardService. It should be used if the header of the represented file must be accessed, and it has to be used if the object returned by the file service has to be down-casted.
        Returns:
        the information returned by the underlying file service
        See Also:
        FileAccessCardService.getFileInfo(opencard.opt.iso.fs.CardFilePath)

      • hashCode

        public int hashCode()
        Returns a hash code for this object.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        a hash code

      • toString

        public java.lang.String toString()
        Returns a human-readable string representation of this card file object.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a string representing this card file object