FileStatistics class

The FileStatistics class allows retrieving certain statistics about file contents for a number of supported file formats. The class does not allow modifying file contents.

Each FileStatistics instance references a particular file, which may be any file on the local file system (whether it is a job or not). The FileStatistics class does not support folders.

Constructing

FileStatistics( file-path : String ) : FileStatistics

Constructs a FileStatistics instance associated with a file specified through its absolute file path. If the specified path references a folder rather than file, the constructed instance behaves as if the referenced file doesn't exist.

Getting file system attributes

The functions in this section work independently of the file's file format.

getPath( ) : String

Returns the absolute file path.

getName( ) : String

Returns the filename including filename extension if present.

getNameProper( ) : String

Returns the filename excluding filename extension.

getExtension( ) : String

Returns the filename extension, or the empty string if there is none.

getMacType( ) : String

Returns the Mac file type code as a 4-character string if available, otherwise the empty string.

getMacCreator( ) : String

Returns the Mac creator code as a 4-character string if available, otherwise the empty string.

isType( ext : String ) : Boolean

Returns true if the file matches the specified file type, specified as a filename extension, and false otherwise. A file matches if its filename extension and/or its Mac file type (after conversion) match the specified filename extension.

This function does not examine the file contents.

isFile( ) : Boolean

Returns true if the file exists, false otherwise.

getByteCount( ) : Number

Returns the size in bytes of the file, or zero if the file doesn't exist.

getCreated( ) : Date

Returns the creation time of the file, or null if the file doesn't exist.

getModified( ) : Date

Returns the last modification time of the file, or null if the file doesn't exist.

Accessing embedded metadata

getEmbeddedDataset( ) : Dataset

Returns a read-only embedded metadata dataset object with the XMP data model for the metadata embedded in the file, or null if the file doesn't exist. If the file exists but it has no supported embedded metadata, the function returns a valid but empty dataset.

The backing file path for the dataset points to the file. Metadata may be embedded in the file as an XMP packet and/or as binary EXIF or IPTC tags. Metadata fields from multiple sources are synchronized into a unified XMP data model. See supported file formats for more information.

This function behaves similarly to the Job.getEmbeddedDataset() function; it supports the same file and metadata formats and performs the same synchronizations. The advantage is that it can be used with any file (for example, to iterate over all files inside a job folder). It does not however allow metadata updates (it always returns a read-only dataset) and it does not support folders (i.e. it doesn't look for an appropriate backing file inside a folder).

Recognizing file format

The functions in this section recognize file format by looking at the file contents. The current implementation supports the following formats:

getFileFormat( ) : String

Returns the format of the file contents (as one of the strings in the first column of the table above), or the empty string if the format is not recognized or if the file doesn't exist. This function checks for all supported file formats, so it may be a bit slow.

isFileFormat( format : String ) : Boolean

Returns true if the file exists and its contents has the specified format (as one of the strings in the first column of the table above); otherwise it returns false. This function is faster than getFileFormat() since it has to check for only a single file format.

Getting contents statistics

The functions in this section interpret the file contents to obtain certain file-format-specific statistics. The requested statistic is specified through its name (as defined for each format in subsequent sections). Each statistic has a well-defined data type (listed with its description). It is recommended to use the "get" function with the appropriate data type, but reasonable conversions between data types are supported.

The functions return the null object (as opposed to an empty string or a zero number) if:

• The file doesn't exist.

• The requested statistic is unknown or unsupported for the file format.

• The requested statistic is not present in the file or is not applicable to the file.

• The result can't be converted to the requested data type.

getString( query : String ) : String

Returns the requested statistic as a string.

getStringList( query : String ) : String[ ]

Returns the requested statistic as a list of strings.

getNumber( query : String ) : Number

Returns the requested statistic as a number.

getBoolean( query : String ) : Boolean

Returns the requested statistic as a Boolean.

getDate( query : String ) : Date

Returns the requested statistic as a date-time.

Data type conversions

A string list is converted to another data type by converting the first string in the list (if the list is empty, the conversion is not supported). Any other data type is converted to a string list by converting it to a string and forming a list of one item.

Supported statistics

PDF media boxes

The FileStatistics class offers the following additional statistics for the PDF file format:

PDF/X version key

The FileStatistics class offers the following additional statistics for the PDF file format:

PDF page content

The FileStatistics class offers the following additional statistics for the PDF file format.

Obtainging the information for these statistics requires parsing the complete page contents, so it might be time consuming.