com.sun.dtv.io
Class FileProperties

java.lang.Object
  com.sun.dtv.io.FileProperties

public final class FileProperties

extends Object

Used to associate properties (or meta data) with a file identified by its pathname on a given file system. As defined in Properties, properties are a collection of (key,value) String pairs.

This package defines classes that extends the behavior of the implementation of the java.io package. By such, the implementation of java.io on a given platform that follows this specification must enforce the file management and access model defined in both FileProperties and FileAccessRights.

Pathname

A pathname that ends in "/*" (where "/" is the file separator character, File.separatorChar) indicates a directory and all the files contained in that directory. A pathname that ends with "/-" indicates a directory and (recursively) all files and subdirectories contained in that directory. The special pathname "<<ALL FILES>>" matches all files.

A pathname consisting of a single "*" indicates all the files in the current directory, while a pathname consisting of a single "-" indicates all the files in the current directory and (recursively) all files and subdirectories contained in the current directory.

Properties

The following properties must be supported by the implementation and be available for every file existing on the file system:

com.sun.dtv.persistence-level

On platforms with limited storage resources, or where specific storage areas may act as cache, this property allows to define a retention level or priority when it comes to storage scarceness. The value is a String representing a positive integer value between 0 and Integer.MAX_VALUE where the higher the value, the more likely the associated file is meant to be retained i.e. lower leveled files are meant to be removed first. However it is left to the platform to define the actual retention policy based on the value defined by this property.
default: "0"
least common denominator: the max of all persistence levels

com.sun.dtv.expiration-date

On platforms with limited storage resources, or where specific storage areas may act as cache, this property allows to define a date after which the associated file is considered to be expired. The value is a String representing a positive integer corresponding to the number of milliseconds since the standard base time known as "the epoch", namely January 1, 1970, 00:00:00 GMT. This number will be casted by the implementation as a long. This value corresponds to the output of Date.getTime() and the input for Date.Date(long). The value may also be the empty string ("") to express 'never' (i.e. a date indefinitely in the future).
default: ""
least common denominator: the latest of all dates within a set of expiration dates

com.sun.dtv.access-rights

Particularly on platform with no or basic support for access rights, this property allows to associate a set of advanced access right related information with a file. The value is a String representing the access rights which format must corresponds to the output of FileAccessRights.getActions()
default: "rw"
least common denominator: the least of every single rights within a set of access-rights. Detailed ruling is found in FileAccessRights

This property tree may be extended by applications and third party libraries, however new properties must follow the same convention for their name as for creating new java package name that is: taking the Internet domain name of your organization, such as example.com. Then reverse this name, component by component, appending a prefix for your tree or package name: com.example.voting. Conventions used beyond the reversed domain name is left to the discretion of any given company.

The domain name org.isdtv is reserved for properties defined in this specification.

Uniqueness

Every collection of properties associated with a given file must guarantee the uniqueness of any given key. This is taken care by the Properties class on which this FileProperties class is based on.

From the implementation point of view, every file identified by a path must have at most one associated collection of properties.

From the application point of view, every file identified by a path must have one and only one associated collection of properties. This is achieved by having the implementation providing a default collection of properties when being request to retrieve the properties of a file for which no properties where stored with (see load(String)).

See Also:

Properties, FileAccessRights

Method Summary

static Properties	load(String path) Loads a copy of the collection of properties associated with a (set of) file/directory identified by path.
static void	store(String path, Properties properties) Associates the collection of properties passed in properties to the file identified by path and stores it persistently.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

store

public static void store(String path,
                         Properties properties)
                  throws NullPointerException,
                         IOException,
                         ClassCastException,
                         FileNotFoundException

Associates the collection of properties passed in properties to the file identified by path and stores it persistently.

The argument path is the pathname of a (set of) file/directory to which properties is associated with. Any subsequent property association must overwrite the previous property set so that any path is uniquely associated with one set of properties.

No later then when this method returns, the platform must have stored persistently the properties. The implementation should use the corresponding Properties.store(OutputStream, String) method to process this request.

If path does not exist, then the association cannot be fulfilled and the implementation must indicate that by throwing a FileNotFoundException.

If the collection of properties is incomplete with respect to the mandatory properties described above, it is left to the implementation to generate them at storage or at retrieval time.

Parameters:

path - the pathname of the file/directory

properties - the properties to associate with that file/directory

Throws:

NullPointerException - if any of the argument passed is null.

IOException - if writing this property list to the specified output stream throws an IOException.

ClassCastException - if any of the properties stored in the property has either a key or value that is not a String.

FileNotFoundException - if file/directory referenced by path does not exists.

load

public static Properties load(String path)
                       throws NullPointerException,
                              FileNotFoundException,
                              IllegalArgumentException

Loads a copy of the collection of properties associated with a (set of) file/directory identified by path.

The path argument follows the same definition as in store(String, Properties). When this method is applied on a set of files/directories, it must return the least common denominator of that set of properties.

If a file corresponding to a given path had no collection of properties associated yet, the implementation must provide transparently a new Properties object where the values of the properties are set to the default values defined in the description of that class.

Parameters:

path - the pathname of the file/directory

Returns:

A copy of properties for the given path.

Throws:

NullPointerException - if path is null.

FileNotFoundException - if path does not point to any existing file.

IllegalArgumentException - if path is an invalid path and does not conform the format given in the class description.