G'day:
Context
In Lucee 5.0 (so: ages ago) and ColdFusion 2021 (so: you know… just now), support for static properties and methods was added to CFML. This isn't a feature that you'd use very often, but it's essential to at least know about it. And it's bloody handy, and makes your code clearer sometimes. I had reason to be googling for docs / examples today, and what's out there ain't great so I thought I'd write my own "probably still not great" effort.
OK so that's the bar set suitably low. Let's get on with it.
What?
What are static properties and methods. I'm going to start from the other end of things. What are general properties and methods? They're properties and methods of an object; you know, one of those things one gets as the result of calling new MyComponent() (or from a createObject call if yer old skool). An object is a set of properties and methods that maintain a current state: values specific to that object.
son = new Person("Zachary")
dad = new Person("Adam")
We have two instances of the Person CFC: one for Zachary and one for me. The behaviour - ie: methods - of these Person objects is defined in Person.cfc, but when one calls an object method on a given object, it acts on the state of that specific object. So if one was to call son.getName(), one would get "Zachary"; if one was to call dad.getName(), one would get "Adam". The implementation of getName is the same for both son and dad - as defined by Person - but their implementation acts on the values associated with the object ("Zachary" and "Adam" respectively). You know all this stuff already, but it's just to contextualise things.
So what these object-based properties and methods are to an object; static properties and methods are to the class (the CFC itself). To get that, one has to have clear in one's mind that objects - instances of a class - are not the same thing as the class. Also it's important to understand that a CFC is not simply a file of source code: it still gets loaded into memory before any objects are made, and it is still a data structure in its own right, and it too can have its own properties, and methods to act on them.
We saw above examples of calling methods on an object. We can also call methods on the class itself, without needing an object. EG:
dog = Animal::createFromSpecies("canis familiaris")
Here we have an Animal class - and that is a reference to Animal.cfc, not an object created from Animal.cfc - and it has a factory method which we use to return a Dog object. Internally to createFromSpecies there might be some sort of look-up table that saying "if they ask for a 'canis familiaris', return a new Dog object"; the implementation detail doesn't matter (and I'll get to that), the important bit is that we are calling the method directly on the Animal class, not on an object. We an also reference static properties - properties that relate to the class - via the same :: syntax. I'll show a decent example of that shortly.
How?
Here's a completely contrived class that shows static syntax:
// Behaviour.cfc
component {
static {
static.defaultMyVarValue = "set in static constructor"
static.myVar = static.defaultMyVarValue
}
static.myVar = "set in pseudo-constructor"
public static function resetMyVar() {
static.myVar = static.defaultMyVarValue
}
}
There's a coupla relevant bits here.
The static constructor. This is to the class what the init method is to an object. When the class is first loaded, that static constructor is executed. It can only reference other static elements of the class. Obviously it can not access object properties or object methods, because when the static constructor is executed, it's executed on the class itself: there are no objects in play. the syntax of this looks a bit weird, and I don't know why this was picked instead of having:
public static function staticInit() {
static.defaultMyVarValue = "set in static constructor"
static.myVar = static.defaultMyVarValue
}
That's more clear I think, and doesn't require any new syntax. Oh well.
Note that when the class is first initialised the pseudo-constructor part of the CFC is not executed. That is only executed when a new object is created from the class.
A static method can only act on other static elements of the class, same as the static constructor, and for the same reason.
I demonstrate the behaviour of this code in its tests:
import testbox.system.BaseSpec
import cfmlInDocker.miscellaneous.static.Behaviour
component extends=BaseSpec {
function run() {
describe("Tests for Behaviour class", () => {
beforeEach(() => {
Behaviour::resetMyVar()
})
it("resets the test variable when resetMyVar is called", () => {
behaviour = new Behaviour()
expect(behaviour.myVar).toBe("set in pseudo-constructor")
expect(Behaviour::myVar).toBe("set in pseudo-constructor")
Behaviour::resetMyVar()
expect(behaviour.myVar).toBe("set in static constructor")
expect(Behaviour::myVar).toBe("set in static constructor")
})
it("doesn't use the pseudo-constructor for static values using class reference", () => {
expect(Behaviour::myVar).toBe("set in static constructor")
})
it("does use the pseudo-constructor for static values using object reference", () => {
behaviour = new Behaviour()
expect(behaviour.myVar).toBe("set in pseudo-constructor")
})
})
}
}
I need that resetMyVar method there just to make the testing easier. One thing to consider with static properties is that they belong to the class, and that class persists for the life of the JVM, so I want to make the initial state of the class for my tests the same each time. It's important to fully understand that when one sets a static property on a class, that property value will be there for all usages of that class property for the life of the JVM. So it persists across requests, sessions and even the lifetime of the application itself.
Why?
Properties
That Behaviour.cfc example was rubbish. It gives one no sense of why on might want to use static properties or methods. Here's a real world usage of static properties. I have a very cut down implementation of a Response class; like one might have in an MVC framework to return the value from a controller that represents what needs to be sent back to the client agent.
// Response.cfc
component {
static {
static.HTTP_OK = 200
static.HTTP_NOT_FOUND = 404
}
public function init(required string content, numeric status=Response::HTTP_OK) {
this.content = arguments.content
this.status = arguments.status
}
public static function createFromStruct(required struct values) {
return new Response(values.content, values.status)
}
}
Here we are using static properties to expose some labelled values that calling code can use to create their response objects. One of its tests demonstrates this:
it("creates a 404 response", () => {
testContent = "/bogus/path was not found"
response = new Response(testContent, Response::HTTP_NOT_FOUND)
expect(response.status).toBe(Response::HTTP_NOT_FOUND)
expect(response.content).toBe(testContent)
})
Why not just use the literal 404 here? Well for common HTTP status codes like 200 and 404, I think they have ubiquity we could probably get away with. But what about a FORBIDDEN response. What status code is that? 403? Or is it 401? I can never remember, can you? So what wouldn't this be more clear, in the code:
return new Response("nuh-uh, sunshine", Response::HTTP_FORBIDDEN)
I think that's fair enough. But OK, why are they static? Why not just use this.HTTP_FORBIDDEN? Simply to show intended usage. Do HTTP status codes vary from object to object? Would one Response object have a HTTP_BAD_GATEWAY of 502, but another one having a HTTP_BAD_GATEWAY value of 702? No. These properties are not part of an object's state, which is what's implied by using the this scope (or variables scope). They are specific to the Response class; to the concept of what it is to be a Response.
Methods
That Response.cfc has a static method createFromStruct which I was going to use as an example here:
it("returns a Response object with expected values", () => {
testValues = {
content = "couldn't find that",
status = Response::HTTP_NOT_FOUND
}
response = Response::createFromStruct(testValues)
expect(response.status).toBe(testValues.status)
expect(response.content).toBe(testValues.content)
})
But it occurred to me after I wrote it that in CFML one would not use this strategy: one would simply use response = new Response(argumentCollection=testValues). So I have a request class instead:
// Request.cfc
component {
public function init(url, form) {
this.url = arguments.url
this.form = arguments.form
}
public static Request function createFromScopes() {
return new Request(url, form)
}
}
This is the other end of the analogy I started with an MVC controller. This is a trimmed down implementation of a Request object that one would pass to one's controller method; encapsulating all the elements of the request that was made. Here I'm only using URL and form values, but a real implementation would also include cookies, headers, CGI values etc too. All controller methods deal in the currency of "requests", so makes sense to pass a Request object into them.
Here we have a basic constructor that takes each property individually. As a rule of thumb, my default constructor always just takes individual values for each property an object might have. And the constructor implementation just assigns those values to the properties, and that's it. Any "special" way of constructing an object (like the previous example where's there's not discrete values, but one struct containing everything), I use a separate method. In this case we have a separate "factory" method that instead of taking values, just "knows" that most of the time our request will comprise the actual URL scope, and the actual form scope. So it takes those accordingly.
That's all fairly obvious, but why is it static? Well, if it wasn't static, we'd need to start with already having an object. And to create the object, we need to give the constructor some values, and that… would defeat the purpose of having the factory method, plus would also push implementation detail of the Request back into the calling code, which is not where that code belongs. We could adjust the constructor to have all the parameters optional, and then chain a call to an object method, eg:
request = new Request().populateFromScopes()
But I don't think that's semantically as good as having the factory method. But it's still fine, that said.
My rationale for using static methods that way is that sometimes creating the object is harder than just calling its constructor, so wrap it all up in a factory method. Now static methods aren't only for factories like that. Sometimes one might need to implement some behaviour on static properties, and to do that, it generally makes sense to use a static method. One could use an object method, but then one needs to ask "is it the job of this object to be acting on properties belonging to its class?" The answer could very well be "no". So implement the code in the most appropriate way: a static method. But, again, there could be legit situations where it is the job of an object method to act upon static properties. Code in object methods can refer to static properties as much as they need to. Just consider who should be doing the work, and design one's implementation accordingly.
A note on syntax
I could not think of a better place to put this, further up.
I've shown how to call static methods and access static properties via the class, it's: TheClassName::theStaticMethodName() (or TheClassName::theStaticPropertyName). However sometimes you have an object though, and legit need to access static elements of it. In this situation use the dot operator like you usually would when accessing an object's behaviour: someObject.theStaticMethodName() (or someObject.theStaticPropertyName). As per above though, always give thought to whether you ought to be calling the method/property via the object or via the class though. It doesn't matter, but it'll make your code and your intent clearer if you use the most appropriate syntax in the given situation.
Outro
Bottom line it's pretty simple. Just as an object can have state and behaviour; so can the class the object came from. Simple as that. That's all static properties and methods are.
Righto.
--
Adam
Oh. There are official docs of sorts: