opencard.opt.iso.fs
Class CardFile
java.lang.Object
|
+--opencard.opt.iso.fs.CardFile
- 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.1.1.1 1999/10/05 15:08:47 damke Exp $
- 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
| Methods inherited from class java.lang.Object |
clone,
equals,
finalize,
getClass,
notify,
notifyAll,
wait,
wait,
wait |
file_info
protected CardFileInfo file_info
- The information about the file represented.
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 serviceabspath - 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 serviceabspath - 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 directoryrelpath - 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 directoryrelpath - 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 directorycomp - 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 representedservice - 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.
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.
- Returns:
- a hash code
- Overrides:
- hashCode in class java.lang.Object
toString
public java.lang.String toString()
- Returns a human-readable string representation of this card file object.
- Returns:
- a string representing this card file object
- Overrides:
- toString in class java.lang.Object
|
