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 available for every file on the platform that are accessible to applications and be supported by the implementation:

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.

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 and no more available. 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.
management rule: a file which has expired must not be accessible and should be deleted no later than the first attempt to access the file after expiration.

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 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.
management rule: in case of storage shortage, the implementation must remove the file found with the lowest persistence-level value. Platforms may apply fine grained decision algorithms in case when multiple files are found matching the lowest level: e.g. a selection based on the file size, or based on the frequency a given application is used, or based on the soon-to-be expiration date. It is left to the implementation to define reasonably when storage shortage happens.

This property tree may be extended by applications and third party libraries. The limit on the number of properties is platform specific. 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 com.sun.dtv is reserved for properties defined in this specification.

Please note that properties defined by applications and third party libraries currently cannot define a least common denominator which could be used by the load() method. Therefore when applying load() on a set, it may happen that properties which values differ between two or more files/directories within that set, are not returned. Please refer to the description of the load method.

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)).

Management rule

Management rule as described for some properties, define how the given property influence the implementation when it comes to storage shortage and some storage needs to be freed. These rules must be respected as described and combined as required. Please also refer to Persistent Storage for further informations.

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. This only applies to properties for which a least common denominator is defined. For any given property for which a least common denominator is not defined, this method must include in the returned collection only those which value matches for every single files/directories within that set.

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.