tmt_file_io

tmt_file_io

tmt_file_io

A stateless CFC that support different kind of file I/O tasks. The main goal here is making the code easy to read/understand/maintain, ensure proper locking and exceptions handling and, more in general, provide a rich set of APIs. Performances optimisation was not considered a top priority. Since I was frustrated by the inconsistencies in the way cfdirectory handles the datelastmodified field, the methods that return a query object use ISO 8601 as date format. I also added four additional fields: fullpath, pathfrombase, canread and canwrite. The first two are especially handy whenever you use recursive directory lists. ColdFusion 6.1 or above required

Metadata

Instantiating 

	        

	    
	


appendFile()
Appends text to a file

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              filePath
	              string
	              Yes
	              
	              
	              Absolute file path
	            

			
	            

	              fileContent
	              string
	              Yes
	              
	              
	              Content of the file to be created
	            

			
	            

	              fileCharset
	              string
	              No
	              [runtime expression]
	              
	              Charset used. Default to a predefined value
	            

			
          
        

	
canRead()
Tests whether the application can read the given abstract pathname

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              path
	              string
	              Yes
	              
	              
	              Abstract pathname
	            

			
          
        

	
canWrite()
Tests whether the application can modify the given abstract pathname

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              path
	              string
	              Yes
	              
	              
	              Abstract pathname
	            

			
          
        

	
checkDirectoryPath()
Throw an exception if directory path does not exist

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              directoryPath
	              string
	              Yes
	              
	              
	              Absolute directory path
	            

			
          
        

	
checkFilePath()
Throw an exception if file path does not exist

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              filePath
	              string
	              Yes
	              
	              
	              Absolute file path
	            

			
          
        

	
copyDirectory()
Copy a directory, including all its contents

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              source
	              string
	              Yes
	              
	              
	              Absolute directory path
	            

			
	            

	              destination
	              string
	              Yes
	              
	              
	              Absolute directory path of a directory where the contents will be moved
	            

			
          
        

	
copyFile()
Copy a file

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              source
	              string
	              Yes
	              
	              
	              Absolute file path of the file to copy
	            

			
	            

	              destination
	              string
	              Yes
	              
	              
	              Pathname of a directory where the file will be copied. If not an absolute path, it is relative to the source directory
	            

			
	            

	              fileCharset
	              string
	              No
	              [runtime expression]
	              
	              Charset used. Default to a predefined value
	            

			
          
        

	
countFileLines()
Counts the lines of text contained inside a file

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              filePath
	              string
	              Yes
	              
	              
	              Absolute file path
	            

			
	            

	              fileCharset
	              string
	              No
	              [runtime expression]
	              
	              Charset used. Default to a predefined value
	            

			
          
        

	
createDirectory()
Creates a directory, including any necessary but nonexistent parent directories. 
Note that if this operation fails it may have succeeded in creating some of the necessary parent directories

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              directoryPath
	              string
	              Yes
	              
	              
	              Absolute directory path
	            

			
          
        

	
deleteDirectory()
Delete a directory, including all its contents

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              directoryPath
	              string
	              Yes
	              
	              
	              Absolute directory path
	            

			
	            

	              throwIfMissing
	              boolean
	              No
	              false
	              
	              Raise an exception if the directory doesn�t exists. Default to false
	            

			
          
        

	
deleteFile()
Delete a file

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              filePath
	              string
	              Yes
	              
	              
	              Absolute file path
	            

			
	            

	              throwIfMissing
	              boolean
	              No
	              false
	              
	              Raise an exception if the file doesn�t exists. Default to false
	            

			
          
        

	
getAbsolutePath()
Turn any system path, either local or absolute, into a fully qualified one

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              path
	              string
	              Yes
	              
	              
	              Abstract pathname
	            

			
          
        

	
getDirectoryList()
Get a directory listing, directories only

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              directoryPath
	              string
	              Yes
	              
	              
	              Absolute directory path
	            

			
	            

	              recursive
	              boolean
	              No
	              false
	              
	              Recursively list nested directories. Default to false
	            

			
          
        

	
getDirectoryPaths()
Get an array of directory paths contained inside a given directory

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              directoryPath
	              string
	              Yes
	              
	              
	              Absolute directory path
	            

			
	            

	              recursive
	              boolean
	              No
	              true
	              
	              Recursively list nested directories. Default to true
	            

			
          
        

	
getDirectorySize()
Get the size of a given directory

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              directoryPath
	              string
	              Yes
	              
	              
	              Absolute directory path
	            

			
          
        

	
getFileList()
Get a directory listing, files only

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              directoryPath
	              string
	              Yes
	              
	              
	              Absolute directory path
	            

			
	            

	              recursive
	              boolean
	              No
	              false
	              
	              Recursively list nested directories. Default to false
	            

			
          
        

	
getFilePaths()
Get an array of files paths contained inside a given directory

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              directoryPath
	              string
	              Yes
	              
	              
	              Absolute directory path
	            

			
	            

	              recursive
	              boolean
	              No
	              true
	              
	              Recursively list nested directories. Default to true
	            

			
          
        

	
getFileSize()
Returns the size of the file

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              filePath
	              string
	              Yes
	              
	              
	              Absolute file path
	            

			
          
        

	
getFullList()
Get a full directory listing, both files and directories

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              directoryPath
	              string
	              Yes
	              
	              
	              Absolute directory path
	            

			
	            

	              recursive
	              boolean
	              No
	              false
	              
	              Recursively list nested directories. Default to false
	            

			
          
        

	
getFullPaths()
Get an array of paths contained inside a given directory, both files and directories

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              directoryPath
	              string
	              Yes
	              
	              
	              Absolute directory path
	            

			
	            

	              recursive
	              boolean
	              No
	              true
	              
	              Recursively list nested directories. Default to true
	            

			
          
        

	
getInfo()
Return a structure containing information about the given abstract pathname

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              path
	              string
	              Yes
	              
	              
	              Abstract pathname
	            

			
          
        

	
getLastModified()
Returns the time that the file or directory denoted by this abstract pathname was last modified

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              path
	              string
	              Yes
	              
	              
	              Abstract pathname
	            

			
          
        

	
getList()
Get a file and/or directory listing

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              path
	              string
	              Yes
	              
	              
	              Abstract pathname
	            

			
	            

	              type
	              string
	              No
	              
	              
	              Either File or Dir
	            

			
	            

	              recursive
	              boolean
	              No
	              false
	              
	              Recursively list nested directories. Default to false
	            

			
          
        

	
getPaths()
Get an array of file and/or directory paths contained inside a given directory

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              path
	              string
	              Yes
	              
	              
	              Absolute directory path
	            

			
	            

	              type
	              string
	              No
	              
	              
	              Either File, Dir or an empty string (if you want both). Default to an empty string
	            

			
	            

	              recursive
	              boolean
	              No
	              true
	              
	              Recursively list nested directories. Default to true
	            

			
          
        

	
getPathSeparator()
Return The system-dependent default name-separator character

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
None

          
        

	
getRelativePath()

	Return the relative path from startPath to destinationPath.
	Paths can be system paths (C:\myroot\mydir\myfile.cfm) or url (http://www.mydomain/myfile.cfm).
	Different kinds of paths (system and url) can't be mixed

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              startingPath
	              string
	              Yes
	              
	              
	              Full starting path
	            

			
	            

	              destinationPath
	              string
	              Yes
	              
	              
	              Full destination path
	            

			
          
        

	
init()

	Pseudo-constructor, it ensure settings are properly loaded inside the CFC. 
	There no need to call it, since the CFC is stateless, 
	but it can be handy if you want to set a character encoding inside the CFC other than the default

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              charset
	              string
	              No
	              [runtime expression]
	              
	              Character encoding used by the current instance of the CFC
	            

			
          
        

	
isDirectory()
Tests whether the given abstract pathname is a directory

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              path
	              string
	              Yes
	              
	              
	              Abstract pathname
	            

			
          
        

	
isFile()
Tests whether the given abstract pathname is a file

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              path
	              string
	              Yes
	              
	              
	              Abstract pathname
	            

			
          
        

	
isHidden()
Tests whether the given abstract pathname is hidden

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              path
	              string
	              Yes
	              
	              
	              Abstract pathname
	            

			
          
        

	
moveDirectory()
Move a directory, including all its contents

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              source
	              string
	              Yes
	              
	              
	              Absolute directory path
	            

			
	            

	              destination
	              string
	              Yes
	              
	              
	              Absolute directory path of a directory where the contents will be moved
	            

			
          
        

	
moveFile()
Move a file

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              source
	              string
	              Yes
	              
	              
	              Absolute file path of the file to copy
	            

			
	            

	              destination
	              string
	              Yes
	              
	              
	              Pathname of a directory where the file will be moved. If not an absolute path, it is relative to the source directory
	            

			
	            

	              fileCharset
	              string
	              No
	              [runtime expression]
	              
	              Charset used. Default to a predefined value
	            

			
          
        

	
readFile()
Read a text file and return a string

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              filePath
	              string
	              Yes
	              
	              
	              Absolute file path
	            

			
	            

	              fileCharset
	              string
	              No
	              [runtime expression]
	              
	              Charset used. Default to a predefined value
	            

			
          
        

	
readFileLines()
Read a file and return its content as an array of lines

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              filePath
	              string
	              Yes
	              
	              
	              Absolute file path
	            

			
	            

	              fileCharset
	              string
	              No
	              [runtime expression]
	              
	              Charset used. Default to a predefined value
	            

			
          
        

	
renameDirectory()
Rename a directory

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              directoryPath
	              string
	              Yes
	              
	              
	              Absolute directory path
	            

			
	            

	              newDirectory
	              string
	              Yes
	              
	              
	              New name
	            

			
          
        

	
renameFile()
Rename a file

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              filePath
	              string
	              Yes
	              
	              
	              Absolute file path
	            

			
	            

	              newFile
	              string
	              Yes
	              
	              
	              New name
	            

			
          
        

	
setReadOnly()
Marks given abstract pathname so that only read operations are allowed

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              path
	              string
	              Yes
	              
	              
	              Abstract pathname
	            

			
          
        

	
urlToJavaFile()
Turn a file path into a java.io.File object

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              fileURL
	              string
	              Yes
	              
	              
	              File path
	            

			
          
        

	
writeFile()
Write to a text file

		
Arguments

        

          
            

              Name
              Type
              Required
              Default
              Options
              Description
            

          
          
	
	            

	              filePath
	              string
	              Yes
	              
	              
	              Absolute file path
	            

			
	            

	              fileContent
	              string
	              Yes
	              
	              
	              Content of the file to be created
	            

			
	            

	              throwIfMissing
	              boolean
	              No
	              false
	              
	              Raise an exception if the file doesn�t exists. Default to false
	            

			
	            

	              fileCharset
	              string
	              No
	              [runtime expression]
	              
	              Charset used. Default to a predefined value