Since many people may only be considering the feature now (either only now moving to 6.1 or 7, or 8), I want to share some resources if you're new to it. (The question came up on a list, and I offered the info there, so thought I'd pass it along here.)

First, there are a couple of articles from that time 6.1 frame:

"Introducing Multiple Server Instances in ColdFusion MX 6.1", by Tim Buntel

"Using Multiple Instances with ColdFusion MX Enterprise 6.1" video

Now, CF7 did introduce the new Instance Manager within the Admin, and that (and instances in general) is covered in the CF manual:

Configuring and Administering ColdFusion MX (Chapter 7, "Using Multiple Server Instances")

Finally, there is also a new Adobe article as of CF7:

http://www.adobe.com/products/coldfusion/whitepapers/pdf/cfmx7_mulitpleinstances.pdf

There are certainly other articles folks have done in the CFDJ or at CommunityMX.com, but these should get you started.

Even though it's old news to some, it does seem that like many things, use of instances is something that may have been missed by folks. I've been contemplating a new user group presentation on the topic. Nothing new for CF8, but it seems people are considering things now that they may have ignored when 6, 6.1, or 7 came out (which is why I did my daylong class at CFUnited on what was new in 6 and 7 that folks may have missed).

One last point, if those don't make it: if you're running on Windows, don't try to create an instance with a JVM heap greater than about 1.3 GB. Though Windows should allow 2GB per app, this is just a number many found that beyond which CF won't start. Hope that all helps.

The message above does show the allowed IP addresses, but what if you need that list programmatically for any reason? Since I couldn't find it discussed anywhere, and I discovered the feature today, I just figured I'd share it in case it helps anyone searching in the future.

Along the way, I also explain for any who need to know, both what the "allowed IPs" limits are and how they've changed in 5, 6, and 7, as well as how to reset the allowed IP addresses.

Background

Most folks know that the Developer Edition of ColdFusion is intended for just local (as opposed to production) development. But to be specific, it's limited not JUST to requests from your localhost but both localhost and 1 other IP address (in CFMX 6 or 6.1), or localhost and 2 other IP addresses in CFMX 7.

Once that limit is reached, if you or anyone else tries to access a CF page from an IP address other than localhost or that 1 (in 6/6.1, or 2 in 7) permitted to that point, the user will get a message:

A License Exception has been thrown.

You tried to access the developer edition from a disallowed IP (nnn.nnn.nnn.nnn). The developer edition can only be accessed from 127.0.0.1 and two additional IP addresses. The additional IP addresses are: yyy.yyy.yyy.yyy,zzz.zzz.zzz.zzz

Of course, in a real message the nnn, yyy, and zzz would be real numbers, and in CFMX 6/6.1 it would list only "one additional IP address".

But the key point for the purpose of this blog entry is that the end of the message lists the IP address(es) that have "gotten in", such that any requests from other IP addresses will fail to run and will get the error message.

So it's sometimes useful to know the list of allowed IP addresses, but what if you need to access it programmatically? And how do you reset it to allow other IP addresses to get in?

Accessing that List of Allowed IP Addresses Programmatically

If you have need to know the list of allowed IP address(es) programmatically for any reason, the following code using the undocumented and unsupported ServiceFactory will show it:

Unfortunately, there is no equaivalent to this in CF Admin API (in CF 7 or 8).

Resetting the Allowed IP Address(es)

Finally, some have wondered how they can reset the list of permitted IP addresses. Just as in CF5 (where you could access the developer edition from any 1 IP address, either localhost or another), in CFMX 6.1 and 7 you just need to restart the server. That will clear the list of allowed addresses.

In CFMX 6.0, however, you needed to actually edit a license.properties file while the server was stopped (as I blogged about back in 2002. Thankfully, that was fixed in 6.1.

For more information on that, as well as for a documented reference of the localhost/localhost+1 licensing in CF 4.5/5/6.0/6.1, see http://www.adobe.com/cfusion/knowledgebase/index.cfm?id=tn_17832.

For documented reference to the localhost+2 support in CF 7, see the bottom of the table at http://www.adobe.com/products/coldfusion/productinfo/product_editions/#s2.

Of course, the error message itself also clearly explains it in CFMX 6 and 7.

Introduction: Why You Would Want to

As background, someone reported having a problem calling a web service from CFML, and a solution suggested was that the person reload or refresh the web service using the CFMX Admin console (in the "Data & Services" > "Web Services" nav bar tab. There, you'll find any web services that have been called from CF (which is often a surprise to folks that they're tracked there). For each listed web service, there are 3 buttons and the middle one does a refresh (which means it goes and grabs the WSDL and builds a local java proxy stub, which is used when you then invoke the web service).

But one may then wonder how to do that programmatically, without having to open the Admin console. In CFMX 6.1, you could use the undocumented ServiceFactory, as I'll show below to those still using that. But since that's being deprecated, you really ought to learn the new CF7 approach.

The CF 7 Admin API Approach

As of CFMX 7, we are expected to use the new Admin API, a set of CFCs provided with CFMX 7, which offer a formal, secured API for accessing functionality otherwise offered in the Admin console.

So how would one do that to refresh a web service? Well, there is an extensions.cfc in the Admin API (a set of CFCs in the webroot's /CFIDE/adminapi/ directory), and it has a reloadWebService method that's just the trick. How did I know that? You can call the built-in CFC documentor by browsing the CFC directly:

Before you can call that, though, note that you do need to "login" to the Admin API by calling the login method of the administrator.cfc first. (Check out its docs to learn more.)

But to save you that effort, here's some code. (As always there are several ways to call a CFC and its methods (using CFINVOKE or CFOBJECT, or createObject either within CFSCRIPT or not), but here's at least one approach.):

Note that you need to specify your own admin password in the first line, and in the last line you need to specify a web service name and its WSDL URL.

What's with this notion of passing in a web service "name"?

As you contemplate that code, you will certainly know what the WSDL URL is, since it's the same one you'd use in a CFINVOKE or CFOBJECT/createobject call of the web service itself. But what's the "name" requested here? Well, that can trip you up and it deserves further discussion, as it has several ramifications as I'll explain here.

The name is the name shown in the Admin console for the given web service. The trick/trap is that if you never open and change the Admin console entry for this web service, then the name will simply be the same value as the WSDL URL. But there's more to understand.

First, if you didn't know it, one can edit that "name" in the Admin console, and then one can even use that "name" as an alternative (or "alias") to the web service WSDL URL when invoking the web service from CFML. That's a whole separate subject which I've covered in user group talks in the past.

But assuming that no one has modified the web service name (or for reasons I'll explain in a moment, if you are not using such an alias name when you invoke the web service), then you can presume the name and WSDL URL to be the same. As an example, one could change the last line above to:

Getting Web Service Names Programmatically

Now may wonder, "can I get the web service name programmatically?" You can. But here's where it gets a little confusing. There is an available getwebservices method of the extensions.cfc. And according to the docs, you can either pass in the "name" of the webservice, or leave it off to get all web services. If we don't know the name, then we may think we'd want to use the latter approach. But I find that it doesn't quite work as straightforwardly as it seems.

First, I tried calling getwebservices() without a name:

Sadly, it returned an empty dump as a result. Yet I had several web services listed in my admin console. Here's the thing: none had a name. I then renamed one of them (to "test"), and tried it again, and suddenly the call did return an array of structures (1, in my case) with the name and WSDL URL.

Hmm. So it seems instead that the getwebservices() ought perhaps instead be named getnamedwebservices(), since it only returns web services whose names have been changed (been given an alias).

Still, though, if I do pass in a name, as the docs suggest, then I do indeed get the same result:

Now, you may wonder: "if I can't a listing unless I know the name, or can only get a list of 'all' of them if they are named, then how might I get the info for ones that have no name or whose name I don't know?"

Good question. And guess what I've found? A couple of important things.

First, I've found that you can also pass in the WSDL URL, even for a web service that's been renamed with an alias like "test", such that this works:

Again, that's not the web service name but the WSDL URL. And the resulting dump shows the name and that URL. So the API docs on this are a little misleading.

Be sure to refresh the "right" webservice: the one you'd really try calling

But perhaps a more important thing is that I found that you can have a web service entry for the SAME WSDL URL but with different names/aliases. Why is this important? Because you want to make sure you refresh whichever one you're using.

This goes back to my point above when I introduced the refreshWebService method: you need to give it the name as YOU call the web service, otherwise you'll be refreshing a different proxy stub and won't see the benefit you expect.

If you use the WSDL URL when you invoke the web service, then that will create a proxy stub with that "name", and therefore you want to use that as the "name" when you refresh it.

If you rename a web service in the Admin console, and then use that when you invoke the web service, then you want to use that as the "name" when you refresh it.

Refreshing Web Services Using the ServiceFactory

Since some folks reading this may not have moved to CF 7, let me show how you could do the same using CFMX 6/6.1 (or indeed 7, since it still works there). It's important to note, however, that using the ServiceFactory is not only not documented but it's also not supported. It has security problems (since there's no need to provide the admin password as you must in the Admin API). Also, it may eventually be obsoleted or otherwise restricted.

Still, since it's been documented by others in the past and is readily available on the web, I'll offer it here:

Now, you'll notice that I've indicated that the value passed into the refreshWebService method is the webservicename. That's because it works just like the Admin API reloadWebService discussed at the top here. Be sure to specify the name as you would use it in the invocation of the web service (whether an alias or the full URL).

How to Confirm That Refreshing is Working

As you try these three approaches (Admin button, Admin API, and ServiceFactory), you will probably benefit greatly from being able to see for sure that the refresh/reload is updating the java proxy/stub class files. Where do you find them? They're stored in a "stubs" directory under your CFMX install directory, such as C:\CFusionMX\stubs or C:\CFusionMX7\stubs.

Then, under that, you will find directory names such as WS141836989, or a name that's the same as the alias/name you give to a web service in the Admin console. Inside those directories you will find other subdirectories, eventually finding some that hold the .class files representing the objects available in the web service. It's those .class files whose date/time stamp you want to see changing when you do a refresh/reload.

I'll note that there's no mapping or indication of that WSnnnn directory name, to know which one holds the web service you're interested in. I guess you just have to find the right one by looking for one whose class names map to the web service object you're calling. (If anyone knows a better connection, please do share it.)

Finally, I think it may be worth clarifying that when you do a refresh/reload of a web service using the approaches above, you need to have first made a call to that web service from CFML (or entered it manually in the admin console).

Hope all that's helpful.

Summary of Notes for Adobe Folks

Before I end, in case any Adobe folks are listening, here is a restatement (and expansion) of the couple of observations I made about wrong or undocumented functionality. This is for both the docs group and the engineers, since this is also about internal API documentation returned by the CFCs and their functionality:

• getwebservices() only returns web services that have a name that was changed, whereas the API doc says it returns "all web services", so it either is working incorrectly or ought to be called getnamedwebservices instead
• though not documented, getwebservices("wsdlurl") works also. The API docs say that it should only take a name (and I tested this against a web service where I had renamed it, so it was not getting it "by name")
• if you do consider renaming the getwebservices() method to be called getnamedwebservices(), you might then also want to rename getwebservices(name) to getwebservice (singular), since it just gets one webservice
• it would be nice to be able to refresh ALL webservices that use a given WSDL URL at once, perhaps by new method that accepts URL rather than name (and works for all occurrences of that URL in the cache, whether named with an alias or not)

I have a few questions/observations for others who have run it or may consider it, and they apply to 7 and 6.1 users. Did you notice the update. and the various new features it adds, like integrated NT authentication for SQL Server, and a new JDBC Spy feature for any DBMS? More on them in a moment.

First, is it needed for 7.02? It doesn't say so (but being from Oct 2005 could explain that). While it may seem we should presume it was included in 7.02, I think not. Some features it adds (below) are not in the C:\CFusionMX7\lib\macromedia_drivers.jar (whose date is also from 2004, at least on my 7.02 install.)

Second, as for 6.1, it's not clear but do we need to apply it if we have the latest 6.1 updater (6,1,0,83762 )? Again that build's macromedia_drivers.jar also lacks some of the files added by this updater, so I would assume so. I applied the update to my CFMX 6.1 updater release including also the important updating of the Sequelink ODBC Server as indicated in the technote. Don't miss that, if you're running on 6.1 (not needed on 7). After restarting, things are working.

I should note that I did find that suddenly my CF5 server (also running on this same dev box) suddenly, and for the first time ever since this box was created a few months ago, started raging with a persistent 55% cpu utilization for ntconsolejava.exe.I certainly would have assumed that the problem was in my CFMX 6.1 services, but by process of elimination it was the stopping of "ColdFusion Management Repository Server" (from CF5) that did the trick. That runs a JRun instance in the CF5 server. I can't see how this would be connected, but I point it out in case it happens to others. I don't know what to do about it. I may just stop my CF5 server until I ever need it. I suppose I cuold also just set the management service to manual. I don't recall what the mgt service did in CF5. A quick review of the docs shows it had to do with archiving and admin reporting.

But perhaps more important, as for the features it adds, did anyone notice the "sql server nt authentication" it enables? It seems that would solve a useful problem, but I could not get it to work. I followed all the steps including extracting the DLL (it's in the zip) and creating an "other" datasource type with the provided "authenticationmethod" in the JDBC URL. Has it worked for anyone?

Note also the interesting new spy feature, which can provide some useful diagnostics (think SQL Profiler, but for any DB and all the info tracked in a log file on the CF server). I was able to get it working successfully with a SQL Server database (using the "other datasource type" as explained in the technote), but when I tried to add it to an odbc dsn against an Access DB, using the connection string approach listed, nothing happened (no spy log created, until I used the "other datasource approach).

I should warn that the technote indicates a couple of times that you should not try to put these new connection string values into the "connection string" field of a DSN, instead creating an "other" datasource type and providing them on the JDBC URL for that DSN. When I made the mistake, I found that I could not query any ODBC datasources nor could I even start the CFMX Admin or get debugging on any page. All complained that the "DataSource service is not available.". I found no neo-query.bak to recover from, so was quite stuck. A careful analysis of the new-query file found that inappropriate CRLF character codes had made their way into the file (As 0a and 0d values that made for bad xml). I removed them (not trivial to do correctly) to get things back in order, so FOREWARNED IS FOREARMED.

Note as well that the updates offer various fixes for SQL Server, Oracle, and Informix. It's also an update that pure JRun 4 users can/should run. I will point out that one blogger has found a change in behavior regarding multiple statements on a single SQL line: http://www.feed-squirrel.com/blog/index.cfm/2006/6/8/CREATE-TABLE-from-CF-7.

See the technote (linked at the top here) to learn more. I've also opened a question in the Adobe forums with this same info: http://www.adobe.com/cfusion/webforums/forum/messageview.cfm?catid=143&threadid=1180864&enterthread=y, as I can't assume as many people read my blog as will read that.

I'll be curious to hear (here or there) what others have experienced and what they think of these new features.

Thanks to Steven Erat for pointing this out.

For those who have seen my presentation on CFML web services (at CFUNited and over the past few years in other venues), this has long been a sore spot for me. So glad to see it fixed.