Context Docs: Creating a Context Programmatically
The fastest way to learn the features of a Context is to create and use one. There are two distinctly different ways to create a valid Context, the programmatic method and the declarative method. We'll be covering the former in this section.
Instantiation
Let's create a simple "vanilla" PluggableContext instance;
Easy enough right? However what we've created so far is pretty useless. It doesn't know about any CFC's and it doesn't have any plugins to determine it's behavior. The first step to making this context meaningful and in turn, useful - is to tell it about a collection of CFC's. It needs a root. The root is a system directory path that contains the CFC's in question. It of course can be any valid system directory path. This information can be provided to the context by either a constructor argument named root or by invoking the setRoot() method;
Is the same as;
A very important process is fired off when you initialize the context root; The Context peeks recursively into that directory and it's sub-directories for any CFC's - components AND interfaces and creates a reflective instance of ComponentClass for each one. At the same time, it's creating an internal registry of each ComponentClass instance. This is how the Context "understands" the collection of CFC's to which you point it.
Adding Behavior with Plugins
This process though, does not in and of itself create any real useful behavior within the Context. That's the job of the Plugin. In order to create a truly useful context, you must provide it with one or more Plugin instances. For the purposes of this demonstration, we're going to be working with the NeodymiumPlugin . This plugin provides automatic context dependency injection. We're going to use this plugin because it is a plain, non-http Plugin implementation.
Let's create an instance of that plugin;
You'll notice that we did a couple of things here - not only did we create an instance of the NeoydymiumPlugin component, but we also gave it to the parent context. Now if you're working along side this tutorial in a .cfm file with the provided code, than you noticed that when you refreshed the page it took a little while longer to come back, that's because the NeoydymiumPlugin was traversing the context contents (CFC's) and creating what it needed to automatically wire your context objects when needed.
But we're not done just yet. Once you're done instantiating and injecting the plugins into the Context, you need to finalize it by invoking the finalize() method. This method invokes the corresponding finalize() AND postContextConstruct() methods on each registered Plugin, in the order in which the Plugins were registered with the context - this is important information if you plan on creating your own custom plugins at some point in time, but for now all you need to know is that invoking the finalize() method on the context is required in order to expect the correct behavior;
Understanding the Mutable API of the Context
Your context is ready to use! But how do you use it exactly? The behavior of the context is directly affected by each and every Plugin type that has been registered. This is accomplished in a few different ways, the first of which is by registering ObjectDecorator instances with the central ObjectFactory, you can learn a little more about this approach in the plugin section. This happens to be the approach that the NeodymiumPlugin takes to ensure it has a say in how context class instances are created (wired in this case). So - it affects the context behavior by wiring objects so that when you invoke the getObjectInstance() method on our context, you get an object with all required dependencies injected (see the Neodymium documentation for more information.);
The mutable API of the Context is created by each public method exposed by a Plugin as long as it is NOT a method provided by the Plugin interface AND as long as that public method does not contain dollar-signs. Creating a public method with dollar-signs inside of your Plugin is a mechanism to prevent the plugin from augmenting the Context API unecessarily. Taking those two rules into account, you can now invoke any method directly on the Context instance that is exposed by any registered plugin and the context will delegate that invocation to the correct Plugin to perform the requested task.
As you can see, creating a simple instance of a Context is fairly easy, however the Context is much more flexible than what we've demonstrated so far. It also supports the concept of disparate environments and configurations and while this type of configuration can be done programmatically (and if you'd like to take that approach - please continue reading the API documentation), this task is much, much easier to do when taking the declarative approach, which we'll cover in the next section.
Programmatic Context Considerations
As you've likely noticed while participating in this tutorial, the Context is re-created on every page refresh. Context construction is a resource intensive process that really only needs to happen once during the life of any application that may use it. This means of course that it's your job as the developer of the consuming code to implement whatever caching mechanism you see fit to ensure that Context initialization happens only when necessary. When working with HTTPContext instances, an Application.cfc file is provided as a convenience which can be extended and provides a default implementation for HTTPContext initialization and caching.