The purpose of the Flash RAM is to allow variables to be persisted seamlessly from one request and be picked up in a subsequent request(s) by the same user. This allows you to hide implementation variables and create web flows or conversations in your ColdBox applications. So why not just use session or client variables? Well, most developers forget to clean them up and sometimes they just end up overtaking huge amounts of RAM and no clean cut definition is found for them. With Flash RAM, you have the facility already provided to you in an abstract and encapsulated format. This way, if you need to change your flows storage scope from session to client scope, the change is seamless and painless.

Every handler, plugin, interceptor, layout and view has a flash object in their variables scope already configured for usage. The entire flash RAM capabilities are encapsulated in a flash object that you can use in your entire ColdBox code. Not only that, but the ColdBox Flash object is based on an interface and you can build your own Flash RAM implementations very easily. It is extremely flexible to work on a concept of a Flash RAM object than on a storage scope directly. So future changes are easily done at the configuration level.

Our Flash Scope also can help you maintain flows or conversations between requests by using the discard() and keep() methods. This will continue to expand in our 3.X releases as we build our own conversations DSL to define programmatically wizard like or complex web conversations. Also, the ColdBox Flash RAM has the capability to not only maintain this persistence scope but it also allows you to seamlessly re-inflate these variables into the request collection or private request collection, both or none at all.

There are times where you need to store user related variables in some kind of permanent storage then relocate the user into another section of your application, be able to retrieve the data, use it and then clean it. All of these tedious operations are definitely doable but why reinvent the wheel if we can have the platform give us a tool for maintaing conversation variables across requests. The key point for Flash RAM is where will the data be stored so that it is unique per user. ColdFusion gives us several persistent scopes that we can use and we have also created several flash storages for this purpose. Since the ColdBox flash scope is based on an interface, the flash scope storage can be virtually anywhere. You will find all of these implementations in the following package: coldbox.system.web.flash. In order to choose what implementation to use in your application you need to tell the ColdBox.cfc which one to use via flash configuration structure:

Configuration

// flash scope configuration
flash = {
    scope = "session,client,cluster,cache,or full path",
    properties = {}, // constructor properties for the flash scope implementation
    inflateToRC = true, // automatically inflate flash data into the RC scope
    inflateToPRC = false, // automatically inflate flash data into the PRC scope
    autoPurge = true, // automatically purge flash data for you
    autoSave = true // automatically save flash scopes at end of a request and on relocations.
};

Below is a nice chart of all the keys in this configuration structure so you can alter behavior of the Flash RAM objects:

Core Flash Implementations

The included flash implementations for ColdBox are:

Configuration Properties

Each RAM implementation can also use properties in order to alter its behavior upon construction via the properties configuration struct. Below are the properties our core implementations can use:

Session Flash Settings

• none

Cluster Flash Settings

• none

Client Flash Settings

• none

Mock Flash Settings

• none

Cache Flash Settings

• cacheName : The cache provider name declared in CacheBox

// flash scope configuration
flash = {
    scope = "cache",
    properties = { cacheName="cluster" }
};

The ColdBox Flash capabilities are very flexible and you can easily create your own Flash Implementations by doing two things:

1. Create a CFC that inherits from coldbox.system.web.flash.AbstractFlashScope

2. Implement the following functions: clearFlash(), saveFlash(), flashExists(), and getFlash()

Implementable Methods

Caution It is the developer's responsibility to provide consistent storage locking and synchronizations.

All of the methods must be implemented and they have their unique purposes as you read in the description. Let's see a real life example, below you can see the flash implementation for the session scope:

As you can see from the implementation, it is very straightforward to create a useful session flash RAM object.

There are several ways to interact with the ColdBox Flash RAM:

• Using the flash scope object (Best Practice)

• Using the persistVariables() method from the super type and ColdBox Controller

• Using the persistence arguments in the relocate() method from the super type and ColdBox Controller.

All of these methods interact with the Flash RAM object but the last two methods not only place variables in the temporary storage bin but actually serialize the data into the Flash RAM storage immediately. The first approach queues up the variables for serialization and at the end of a request it serializes the variables into the correct storage scope, thus saving precious serialization time. In the next section we will learn what all of this means.

Flash Scope Object

The flash scope object is our best practice approach as it clearly demarcates the code that the developer is using the flash scope for persistence. Any flash scope must inherit from our AbstractFlashScope and has access to several key methods that we will cover in this section. However, let's start with how the flash scope stores data:

1. The flash persistence methods are called for saving data, the data is stored in an internal temporary request bin and awaiting serialization and persistence either through relocation or termination of the request.

2. If the flash methods are called with immediate save arguments, then the data is immediately serialized and stored in the implementation's persistent storage.

3. If the flash's saveFlash() method is called then the data is immediately serialized and stored in the implementation's persistent storage.

4. If the application relocates via relocate() or a request finalizes then if there is data in the request bin, it will be serialized and stored in the implementation's storage.

Caution By default the Flash RAM queues up serializations for better performance, but you can alter the behavior programmatically or via the configuration file.

Info If you use the persistVariables() method or any of the persistence arguments on the relocate() method, those variables will be saved and persisted immediately.

To review the Flash Scope methods, please and look for the correct implementation or the AbstractFlashScope.

Info Please note that the majority of a Flash scope methods return itself so you can concatenate method calls. Below are the main methods that you can use to interact with the Flash RAM object:

clear()

Clears the temporary storage bin

clearFlash()

Clears the persistence flash storage implementation

discard()

Discards all or some keys from flash storage. You can use this method to implement flows.

exists()

Checks if a key exists in the flash storage

get()

Get a value from flash storage and optionally pass a default value if it does not exist.

getKeys()

Get a list of all the objects in the temp flash scope.

getFlash()

Get a reference to the permanent storage implementation of the flash scope.

getScope()

Get the flash temp request storage used throughout a request until flashed at the end of a request.

isEmpty()

Check if the flash scope is empty or not.

keep()

Keep flash temp variable(s) alive for another relocation. Usually called from interceptors or event handlers to create conversations and flows of data from event to event.

persistRC()

Persist variable(s) from the ColdBox request collection into flash scope. Persist the entire request collection or limit the variables to be persisted by providing the keys in a list. "Include" will only try to persist request collection variables with keys in the list. "Exclude" will try to persist the entire request collection except for variables with keys in the list.

put()

The main method to place data into the flash scope. Optional arguments control whether to save the flash immediately, inflate to RC or PRC on the next request, and if the data should be auto-purged. You can also use the configuration settings to have a consistent flash experience, but you can most certainly override the defaults. By default all variables placed in flash RAM are automatically purged in the next request once they are inflated UNLESS you use the keep() methods in order to persist them longer or create flows. However, you can also use the autoPurge argument and set it to false so you can control when the variables will be removed from flash RAM. Basically a glorified ColdFusion scope that you can use.

putAll()

Pass an entire structure of name-value pairs into the flash scope (similar to the put() method).

remove()

Remove an object from the temporary flash scope so it will not be included when the flash scope is serialized. To remove a key from the flash scope and make sure your changes are effective in the persistence storage immediately, use the saveNow argument.

removeFlash()

Remove the entire flash storage. We recommend using the clearing methods instead.

saveFlash()

Save the flash storage immediately. This process looks at the temporary request flash scope, serializes it if needed, and persists to the correct flash storage on demand.

Info We would advice to not overuse this method as some storage scopes might have delays and serializations

size()

Get the number of the items in flash scope.

More Examples