Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## opencard.opt.iso.fs
Class CardFile

    java.lang.Object
      opencard.opt.iso.fs.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`.

Version:
  $Id: CardFile.java,v 1.2 2005/09/19 10:21:22 asc Exp $
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:
  `CardFileInputStream`, `CardFileOutputStream`, `CardRandomByteAccess`, `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 Summary
`protected CardFileInfo` | `file_info` The information about the file represented.

Constructor Summary
`` | `CardFile(CardFile base, CardFilePath relpath)` Creates a card file for the specified relative path.
`` | `CardFile(CardFile base, CardFilePathComponent comp)` Creates a card file for the specified path component.
`protected` | `CardFile(CardFilePath path, FileAccessCardService service)` Creates a card file, for internal purposes.
`` | `CardFile(CardFile base, java.lang.String relpath)` Creates a card file for the relative path specified as string.
`` | `CardFile(FileAccessCardService service)` Creates a root card file.
`` | `CardFile(FileAccessCardService service, CardFilePath abspath)` Creates a card file object for the specified absolute path.
`` | `CardFile(FileAccessCardService service, java.lang.String abspath)` Creates a card file object for an absolute path given as string.

Method Summary
`void` | `create(byte[] data)` Creates a file on the smartcard.
`void` | `delete(CardFilePath relpath)` Deletes a file on the smartcard.
`boolean` | `exists(CardFilePath relpath)` Tests whether a given file exists.
`CardFilePath` | `getAbsolutePath()` Returns the absolute path of the file represented.
`CardFilePath` | `getCanonicalPath()` Returns the canonical path of the file represented.
`protected FileAccessCardService` | `getFileAccessService()` Returns the underlying file access card service.
`short` | `getFileID()` Returns the identifier of the file represented.
`CardFileInfo` | `getFileInfo()` Returns information about the file represented.
`protected FileSystemCardService` | `getFileSystemService()` Returns the underlying file system card service.
`byte[]` | `getHeader()` Returns the header of the file represented.
`int` | `getLength()` Returns the length of the file represented.
`java.lang.String` | `getName()` Returns the name of the file represented.
`CardFile` | `getParent()` Return the parent `CardFile`.
`CardFilePath` | `getPath()` Returns the path of the file represented.
`int` | `getRecordSize()` Returns the record size of the file represented.
`int` | `hashCode()` Returns a hash code for this object.
`boolean` | `isCyclic()` Checks whether the file represented is a cyclic file.
`boolean` | `isDF()` Checks whether this card file represents a dedicated file (directory).
`boolean` | `isDirectory()` Checks whether the file represented is a directory.
`boolean` | `isEF()` Checks whether this card file represents an elementary file.
`boolean` | `isFile()` Checks whether the file represented is a non-directory file.
`boolean` | `isTransparent()` Checks whether the file represented is a transparent file.
`boolean` | `isVariable()` Checks whether the file represented is a variable record file.
`protected CardFilePath` | `resolvePath(CardFilePath path)` Provides a hook for resolving symbolic path components.
`java.lang.String` | `toString()` Returns a human-readable string representation of this card file object.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, notify, notifyAll, wait, wait, wait`

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

### getFileID

    public final short getFileID()

  Returns the identifier of the file represented.

  Specified by:
    `getFileID` in interface `CardFileInfo`
  Returns:
    the identifier of the file
  See Also:
    `CardFileInfo.getFileID()`

### 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()`

### isTransparent

    public final boolean isTransparent()

  Checks whether the file represented is a transparent file.

  Specified by:
    `isTransparent` in interface `CardFileInfo`
  Returns:
    `true` if this file is transparent
  See Also:
    `CardFileInfo.isTransparent()`

### 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()`

### getLength

    public final int getLength()

  Returns the length of the file represented.

  Specified by:
    `getLength` in interface `CardFileInfo`
  Returns:
    the number of bytes in the file
  See Also:
    `CardFileInfo.getLength()`

### getRecordSize

    public final int getRecordSize()

  Returns the record size of the file represented.

  Specified by:
    `getRecordSize` in interface `CardFileInfo`
  Returns:
    the size of a record in the file
  See Also:
    `CardFileInfo.getRecordSize()`

### 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)`

### create

    public final void create(byte[] data)
                      throws CardServiceInabilityException,
                             OpenCardException

  Creates a file on the smartcard. This method can be used to create dedicated as well as elementary files. The new file will be located in the directory represented by this card file. This method is available only if the underlying card service is an instance of `FileSystemCardService`. The parameter block specifying the file to be created is card-specific. For details, see `create` in the interface.

  Parameters:
    `data` - a card-specific parameter block specifying the file to create
  Throws:
    `CardServiceInabilityException` - if the underlying card service does not support creating files
    `OpenCardException` - if something else went wrong
  See Also:
    `FileSystemCardService`, `FileSystemCardService.create(opencard.opt.iso.fs.CardFilePath, byte[])`

### delete

    public void delete(CardFilePath relpath)
                throws CardServiceInabilityException,
                       OpenCardException

  Deletes a file on the smartcard. This method is available only if the underlying card service is an instance of `FileSystemCardService`.

  Parameters:
    `relpath` - the path to the file to delete, relative to this card file
  Throws:
    `CardServiceInabilityException` - if the underlying card service does not support deleting files
    `OpenCardException` - if something else went wrong
  See Also:
    `FileSystemCardService`

### 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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD