CF10 Hidden Gem: New method to obtain ColdFusion instance name via CFML code
Note: This blog post is from 2012. Some content may be outdated--though not necessarily. Same with links and subsequent comments from myself or others. Corrections are welcome, in the comments. And I may revise the content as necessary.One of the many hidden gems in CF10 is that there's a new way to programmatically obtain the current instance name. In CF 6-9, we had to call a method in a JRun class. In CF10, they've added a new method in the Admin API.
The quick answer is that there's a getInstanceName method in the runtime.cfc of the Admin API. And yes, any user can execute this code. They do not need to BE an admin. You can use this in production code. For more, see below.
If that's enough to get you going, have at it. For more info, read on.
Why would one need this?
If you have multiple instances of CF installed (in CF 6-10), and especially if you're using load balancing, you may want to know, via code, which instance you're running within, whether for testing purposes, or for diagnostics/troubleshooting, or perhaps as part of some utility.
What was the old way?
The old way was to call a method within a java class in the JRun API. Of course, we can't do that any more in CF10, since it runs atop Tomcat. (For more on that and the differences related to it, see my talk "What's New and Different About CF 10 on Tomcat.)
Here's an example of just one way one might have called and used that Java method and class in prior releases:
What's the new way?
So the new way again is to call the CF admin API, via the getInstanceName method in the Administrator.cfc. Fortunately, it can be called exactly the same way:
(Of course, there are other ways to call such methods, using CFOBJECT, CFINVOKE, or without chaining the method on the createobject. The best choice for you depends on coding style, how many other methods you'll be calling on the object, whether you want to save the object as a shared scope variable for reuse, and so on.)
More on the Admin API
For more on using the Admin API, you could of course find it in the docs (in the "Configuring and Administering CF10" manual), specifically here.
And as I said at the open, this particular method does not require that the user calling it BE an admin user. You could safely put this code in production code that's called by any user, and it will work. (For other methods in this or other AdminAPI CFCs, if you DO need to be an Admin, then you would have to call the login method of the runtime.cfc.)
Getting more hidden gems in CF10
This new Admin API method is one of many "hidden gems" in CF10 that are not mentioned much. In fact, I can't even now find this method referred to in any of the CF10 docs. :-( If anyone finds where it's listed, please add a comment here. Thanks.
I'll note that I did mention it in a talk I've been giving recently, "Hidden Gems in CF10", which is available as both a PDF and a recording.
I also mention it in my blog entry listing over 200 new features of CF10.
Hope those may be as helpful as this tip on the new API method.
For more content like this from Charlie Arehart:Need more help with problems?
- Signup to get his blog posts by email:
- Follow his blog RSS feed
- View the rest of his blog posts
- View his blog posts on the Adobe CF portal
- If you may prefer direct help, rather than digging around here/elsewhere or via comments, he can help via his online consulting services
- See that page for more on how he can help a) over the web, safely and securely, b) usually very quickly, c) teaching you along the way, and d) with satisfaction guaranteed
Either way, I would propose that "select[ing] which instance to direct a request to" is not really a "CF feature". I'd propose it would seem a matter of web server configuration.
First, note first that when you create new instances in the CF Admin Instance Manager (in any release of CF7-10), CF creates that instance initially to run via its internal web server. You can access the instance directly using that, with whatever port it was created to use (starting with 8301 in CF7-9, or 8501 in CF10).
So you should be able to access the instance directly that way. Is that working for you?
But maybe you mean you'd like to configure an external web server (IIS, Apache, etc.) to point to a single instance, while also having put that instance into a CF cluster. Is that the case? That can be harder, since it will show the cluster rather than the instances. But I'm pretty sure that if you run that tool before putting the instances into a cluster, then CF would create a connection to that specific instance, even if it was later put into a cluster.
Of course, you need to come up with some sort of binding for that web site that would access it specifically (whether giving it an alternative port, like 81, or an alternative host header, etc.)
If you may ask any questions in reply, please do clarify if you are using IIS or Apache, and also what you've tried and/or are finding specifically, and what version of CF.
Hope that helps.