Working with in-memory files



Memory-based virtual file system speeds up the processing of transient data. In-memory files are not written to disk and are saved on RAM. They function similar to disk files but perform faster.

In ColdFusion, in-memory files help you to simplify the execution of dynamic code. In-memory files are supported across almost all tags and functions that take file or directory as input or output.

You use in-memory files in the same manner as files on disk, but with a prefix ram:/// to indicate that they reside on RAM. For example, ram:///a/b/dynamic.cfm.

Writing and executing dynamic CFM files

The following syntax explains how to write CFM data in to an in-memory file:
<cffile action="write" output="#cfml#" 
file="ram:///filename.cfm"/>

The following sample syntax explains how to use the in-memory CFM file:

  • For tags that take logical path, define mapping in Administrator. Execute in-memory CFM pages using the cfinclude tag:

    <cfinclude template="/inmemory/filename.cfm">

    Create a mapping for ram:/// so that it can be used in the tags. In this example, /inmemory is the mapping that points to ram:///.

  • For tags that take absolute path, specify the syntax as provided in the following example:

    <cffile action="append" file="ram:///a/b/dynamic.cfm" output="I'm appending">
Note: You cannot have Application.cfm as an in-memory file. If you have one, it is ignored.

Example

The following code describes how to write an image as an in-memory file:

<cffile action="readBinary" variable="myImage" file="#ExpandPath('./')#/blue.jpg"> 
<cffile action="write" output="#myImage#" file="ram:///a.jpg"> 
<cfif FileExists("ram:///a.jpg")> 
<cfoutput>a.jpg exists</cfoutput> 
<cfelse> 
<cfoutput>a.jpg Doesn't exists</cfoutput>     
</cfif>

Writing and instantiating dynamic CFC files

The following syntax explains how you can write CFC code in to an in-memory file:

<cffile action="write" output="#cfcData#" 
file="ram:///filename.cfc"/>

The following sample syntax explains how you can instantiate the in-memory CFC file:

<cfset cfc=CreateObject("component","inmemory.filename")/>

Here, inmemory is the ColdFusion mapping that points to ram:///.

Note: You cannot have Application.cfc as an in-memory file. If you have one, it is ignored.

Example

The following code writes a CFC as in-memory file:

<cffile action="read" file="#ExpandPath('./')#/dynamic.cfc" variable="Message"> 
<cffile action="write" file="ram:///cfc/dynamic.cfc" output="#Message#">

To invoke a component method:

<cfinvoke component="inmemory.cfc.dynamic" method ="method1" returnVariable="returnVariable"> 
<cfinvokeargument name="paramOne" value="hello"> 
</cfinvoke> 
<cfoutput>#returnVariable#</cfoutput>

Working with in-memory file system

The following sections provide information that can help you to access and use in-memory files.

Using in-memory files

  • You can call a CFC saved on RAM from a CFM file on disk. Similarly, an in-memory CFM file can call a CFC saved on disk.

  • If a CFC extends another CFC in the same directory in RAM, you can use relative path. For instance, if a.cfc and b.cfc belong to the same directory in RAM, a.cfc can extend b.cfc using relative path as shown in the following code:

    <cfcomponent name="a" extends"b"> 
… 
</cfcomponent>

  • You can use in-memory ColdFusion interfaces in the same way as you use in-memory CFCs.

Supported functions

The following file functions are supported for in-memory files:

  • FileIsEOF

  • FileReadBinary

  • Filemove

  • Filecopy

  • FileReadLine

  • FileExists

  • FileOpen

  • FileWriteln

  • FileClose

  • FileRead

  • FileDelete

  • DirectoryExists

  • FileSetLastModified

  • GetFileInfo

  • GetDirectoryFromPath

  • GetFileFromPath

  • ImageNew

  • ImageRead

  • ImageWrite

  • ImageWriteBase64

  • IsImageFile

  • IsPDFFile

  • FileSetLastModified

Example

The following syntax explains the function FileSetLastModified()

<cftry> 
<cffile action="write" file="ram:///a.txt" output="Testing the function FileSetLastModified"> 
<cfset date="12/12/2007"> 
<cfscript> 
FileSetLastModified("ram:///a.txt", "#date#"); 
sleep(1000); 
WriteOutput(#GetFileInfo("ram:///a.txt").lastmodified#); 
</cfscript> 
<cfcatch> 
<cfset PrintException(cfcatch)> 
</cfcatch> 
</cftry> 
<cf_expectedresults>{ts '2007-12-12 00:00:00'} 
</cf_expectedresults>

File operations

The following file operations are supported for in-memory files:

  • Directory-specific operations: create, delete, list, and rename.

  • File-specific operations: copy, create, write, append, delete, rename, create attributes, modes move, and read.

Example

The following code illustrates the file and directory operations:

<cfdirectory action = "create" directory = "ram://src" > 
<cfdirectory action = "create" directory = "ram://des" > 
<cfdirectory action = "rename" directory = "ram:///CurrentDir" newDirectory = "NewDir"> 
<cfdirectory action="list" directory="ram://" name="listDir" recurse="yes" > 
<cfdump var="#listDir#"> 
<cffile action="write" file = "ram://src/test.txt" output = "Release Description"> 
<cffile action="copy" source="ram://src/test.txt" destination="ram://des/final.txt" > 
<cffile action="rename" source = "ram:///src/message.txt" destination = "ram:///des/test.txt"> 
<cffile action ="move" source = "ram:///des/test.txt" destination = "c:\des\move.txt">

Document and image actions

All image and document actions can use in-memory image files as shown in the following examples:
<cfimage action="captcha" fontSize="15" width="180" height="50" text="readMe" destination="ram:///readMe.jpg" 
difficulty="medium"> 
<cfimage source="ram://aiden02.png" action="convert" destination="#ExpandPath("./")#/blue1.JPG" overwrite="yes"> 
<cfdocument format="pdf" filename="ram://Sample.pdf" overwrite="yes">Sample Text</cfdocument>

Custom tags

In-memory CFM pages and CFCs can call custom tags but the custom tags must be present in disk. In-memory custom tags are not supported.

Using in-memory files in tags

The following tags are supported for in-memory files:

  • cfcontent

  • cfdocument

  • cfdump

  • cfexchange

  • cfexecute

  • cffeed

  • cfhttp

  • cfftp

  • cfimage

  • cfloop

  • cfpresentation

  • cfprint

  • cfreport

  • cfzip

Example using the tag cfcontent

<cfcontent file="ram:///a.jpg" type="image/jpeg" deletefile="yes">

Adding permissions

ColdFusion lets you add permissions for directories/files on RAM using an existing sandbox security setup. You can only set up sandbox security for disk directories and not for RAM directories. Access to an in-memory directory/file can be restricted only through an existing local file system sandbox.

Therefore, to set up sandbox security for in-memory files, select a sandbox that you have already configured for a disk directory.

By default the ram:/// directories are included in the list of secured folders and have read, write, execute, and delete permissions set. Therefore, all RAM files have permissions by default in a sandbox. All the security restrictions that apply to disk files apply to in-memory files.

To set up Sandbox security for in-memory files,

  1. Open the Security > Sandbox Security page in the ColdFusion Administrator.

    The Sandbox Security Permissions page appears.

  2. In the Add Security Sandbox box, specify a disk directory and then click Add.

  3. In Files/Directories, specify the in-memory file path. For example, ram:///a/b (for directory) or ram:///a/b/dynamic.cfm (for file).

  4. Select the required permissions, click Add Files/Paths, and then click Finish.

For further details on sandbox security, refer to the ColdFusion Administration Guide.

Accessing VFS information

The GetVFSMetaData function lets you access VFS information.

This function returns a structure that contains the following information:

  • The in-memory file system type

  • If support for in-memory virtual file system is enabled

  • Memory limit in bytes for in-memory virtual file system

  • The used and free memory

Deleteing in-memory files

The in-memory files remain in RAM as long as the server is up. When required, clean up the files using cffile/cfdirectory with the action=delete. For example, delete all the contents in RAM directory "ram://a/b" using the following code: <cfdirectory action="delete" directory="ram:///a/b" recurse="yes">

Limitations

  • File names/Directory names on RAM are case sensitive.

  • In-memory files must be accessed using mapping or absolute path. Relative paths to files/directories are not supported.

    • Correct: ram:///a/b/

    • Incorrect: ram:///a/b/../..

  • You cannot access in-memory files using HTTP/HTTPS protocols. Instead, use ram:///<file>. For example, ram:///a/b/test.cfm.

  • DDX files and font files cannot be accessed as in-memory files.

  • The following functions are not supported for in-memory files.

    • FileSetAccessMode that sets attributes of a file in Linux/Unix

    • FilesSetAttribute that sets the attributes of a file in Windows

  • The following tags are not supported:

    • cfpdf

    • cfpdfform

  • The following scenarios are not supported:

    • The cfreport tag does not accept a template report on RAM. Therefore, the following does not work:

      <cfreport format="PDF" template="ram:///myReport1.cfr" filename="ram:///test.pdf" overwrite="yes">

      In this case, the myReport1.cfr must reside on your disk.

    • The cfimport tag does not accept tag libraries on RAM. For instance, the following does not work:

      <cfimport prefix="custom" taglib="ram:///a/b/mytags.jar">

    • Renaming across file systems (as shown in the following syntax) is not supported.

      <cffile action="rename" source="ram:///src1/message2.txt" destination="#ExpandPath('./')#/123.txt">.

      Instead, you can move the files.

    • For the cfexecute tag, the executable cannot be on RAM and must be on your local file system. But the output can be an in-memory file as illustrated in the following code:

      <cfexecute name="C:\WINDOWS\System32\netstat.exe" arguments="-e" outputFile="ram:///output.txt" timeout="1"> 
</cfexecute> 
<cfset thisPath=ExpandPath("*.*")>