 |
 |
|
|
 |
|
Jim Schley
|
|
|
By now you're probably as excited as I am about Macromedia
ColdFusion MX. With a powerful new architecture based
on Java 2 Enterprise Edition (J2EE) and a range of
new features designed for you, the developer, there's
much to be excited about. You're no doubt asking yourself
how you get your application up and running on this
new release of ColdFusion. Ask no more. I've compiled
some information below to answer this question and
get you started in the right direction towards a successful
migration to ColdFusion MX.
|
|
|
Requirements for migrating
The key to a smooth transition to ColdFusion MX is simple
planning and testing. As you would for any software upgrade,
set aside a testing environment with your applications running
on it. Apply the software upgrade to this testing environment
and test the effects of the upgrade. Line up the following
resources to ensure a well-executed migration.
|
|
Hardware
|
|
Earmark a server as the testing environment for your
migration. Ideally, this should be within a dedicated
QA (quality assurance testing) environment that mirrors
your production server. Less optimally, you can use
a developer machine to test the upgrade of a less
complex application. The important concept here is
that you should not run an upgrade on a production
environment without first upgrading the test environment
and following the steps I outline later.
Upgrading a production server without first thoroughly
testing your application on the new platform can lead
to unexpected behavior that can adversely affect the
operation of your application. No changes to a production
environment should ever be made, be it software upgrade
or code modifications, without testing the effects
of those changes in a test environment where end users
will be unaffected.
|
|
Documentation
|
|
Proper software engineering practices dictate that
you have comprehensive documentation written about
the configuration of your application environment
and the application code itself. If you don't have
any application and configuration documentation, take
this opportunity to detail how you've configured your
production environment and describe what steps would
be required to set up the application from scratch.
Use this documentation later to validate that your
migration to ColdFusion MX is successful.
Your documentation should include all settings in
the ColdFusion Administrator that are changed from
their defaults. For example, this could include settings
such as simultaneous requests. Additional settings
that typically are required to configure an application
include data sources, ColdFusion mappings, web server
mappings, directory structures, source code locations,
Verity collections and custom tag folders. If your
application requires any of these items, or others
not listed, in order for it to run successfully, you
should document them.
|
|
Quality assurance
|
| The final required resource
is a solid set of quality assurance testing processes
that verify your application is properly running. You
can use this to retest your application after you migrate
it. Apply the same QA processes you use to test routine
code changes to the application before placing them
into production. Plan on executing these QA processes
on your application after upgrading the testing environment
to ColdFusion MX and after you upgrade the production
environment to ColdFusion MX. |
|
|
Getting familiar with ColdFusion MX
Migrating your application to ColdFusion MX should be
relatively seamless. The installed product should look and
feel similar to previous releases, even though the underlying
architecture is radically different.
Understanding the new J2EE architecture
ColdFusion MX now runs as a J2EE application on a J2EE
application server. If you've had any experience with J2EE
applications servers, such as Macromedia JRun or IBM WebSphere,
you'll feel right at home. ColdFusion MX runs out of the
box on an embedded version of Macromedia JRun 4. The ColdFusion
CFML pages are compiled to Java bytecode the first time
they are browsed. The J2EE application server processes
the resulting Java class file and returns an HTTP response
to the client.
Making the administrator settings
After installing ColdFusion MX, spend time exploring
the ColdFusion MX Administrator. Although it's laid out
very similarly to the ColdFusion Administrator in previous
versions of ColdFusion Server, there have been a few subtle
changes to the user interface. It's important to be comfortable
with the Administrator so that you can validate your configurations
after your migration is complete.
Definitely familiarize yourself with the Data Sources menu
so that you can verify your database connections after the
upgrade and tweak them if necessary. You should find some
nice improvements in the user interface of this menu over
previous versions. Take a look at other menus, such as the
Mappings menu, that you know you use to configure your application.
Preparing for migration
There are a few steps you need to follow in order to
prepare for ColdFusion MX migration.
|
|
1.
|
Prepare the environment.
Put a copy of your application on the test environment
running on the same version of ColdFusion Server that
is running on your production environment. If you
are using a new environment for this testing, use
your documentation to create a mirror version of your
production environment on your test environment. Follow
your QA processes on the test environment to verify
that your application runs properly.
|
|
2.
|
Install ColdFusion MX.
Install ColdFusion MX on the test environment
system. This is a straightforward process that's similar
to installing any other piece of software, including
previous versions of ColdFusion.
Once the installation is complete, the ColdFusion
MX administrator will appear in a browser window.
After logging in with the password that you set during
the install process, you will be prompted whether
you want to migrate the settings from your existing
installation of ColdFusion. Selecting to do so will
copy all of your settings, such as your data sources,
mappings, and so forth. It's not imperative to migrate
your settings. If you don't want to, simply configure
all the settings for your application manually at
a later time, using your application documentation.
If you run the migration, write down any warnings
displayed on the screen during the installation process
to see if you must manually configure any settings
afterwards. For complete details on settings that
were migrated, look at the migration.log file in the
ColdFusion MX logs directory. (Depending on the folder
you chose to install in, you'll typically find the
log file in c:\cfusionmx\logs\ in Windows or in /opt/coldfusionmx/logs
on non-Windows systems.) The amount of time required
by the migration wizard depends on your computer's
speed and how many settings you are migrating. If
you are migrating many data sources, for instance,
this may take the migration wizard a longer amount
of time than if you had few data sources to migrate.
After the migration is complete, the ColdFusion MX
Administrator will appear. Navigate through the menus
to familiarize yourself with the new product and verify
that the ColdFusion Server settings are properly configured
for your application to run. Pay specific attention
to your data sources by verifying their configuration
using your documentation.
|
| 3. |
Run the Code Compatibility Analyzer.
ColdFusion MX ships with a tool called the Code
Compatibility Analyzer, which is your key to understanding
what changes you must make to your code for your application
to properly run in ColdFusion
MX. The analyzer detects the following code issues:
|
|
|
|
|
•
|
CFML features in your code that are unsupported
in the MX version
|
|
•
|
Deprecated CFML features that may be unsupported
in a future release
|
|
•
|
CFML features that might produce different
behaviors in the MX version
|
|
•
|
CFML syntax errors that would cause ColdFusion
to throw an error when compiling
|
|
|
|
Although the installation does not run the Code Compatibility
Analyzer automatically, I recommend you run it at this time.
The Code Compatibility Analyzer produces a report that can
help you develop your migration plan.
To run the Code Compatibility Analyzer:
|
| 1. |
Log in to
the ColdFusion MX Administrator. |
| 2. |
Click the
Code Compatibility Analyzer in the left navigation menu. |
| 3. |
Browse to
the directory where your application source code resides.
The following figure shows the CFML Code Analyzer displayed
in a browser. |
|
|
|
|
4.
|
Submit the form and review the results.
|
|
5.
|
The first items you will need to address in your
migration plan are those marked at the "error"
severity level and colored orange in the report.
|
|
|
|
|
Developing a migration plan
As I mentioned earlier, you need a solid plan of attack
to ensure your migration is successful. This migration plan
addresses issues reported by the Code Compatibility Analyzer
to ensure that your application source code is compatible
with ColdFusion MX standards
|
|
1.
|
Fix errors reported by the Code Compatibility
Analyzer in "basic" mode.
Your highest priority is fixing CFML code in pages
reported by the Code Compatibility Analyzer. The Code
Compatibility Analyzer runs in "basic" mode
by default and only reports on code that generates
errors related to CFML features or syntax that are
no longer supported in ColdFusion MX.
For more information on how to address these issues,
refer to the Migrating to ColdFusion MX manual available
as part of the ColdFusion MX documentation. This documentation
provides in-depth explanations for each error category
reported.
|
|
2.
|
Fix errors reported by the Code Compatibility
Analyzer in the "advanced" mode.
Run the Code Compatibility Analyzer in "advanced"
mode once you address the issues reported in basic
mode. Running the Analyzer in "advanced"
mode reports code that fails the following criteria:
|
|
| • |
Deprecated features that will not be supported
in future releases of ColdFusion (such as the
cfregistry
tag on Unix)
|
| • |
Features that behave differently in ColdFusion
MX than they did in previous versions (such
as the cfgraph
tag)
|
|
|
|
These items are marked at the "information"
severity level in the report. You don't necessarily
have to address these items in your migration plan,
but you should review them and assess their impact
on your application. Refer to the Migrating to ColdFusion
MX manual to help you to make this assessment.
|
| 3. |
Modify your code if necessary.
Once you've determined which code changes you
need to make for your application to run flawlessly
on ColdFusion MX, it's time to get the development
team rolling. Code modifications should be made following
your development guidelines and QA processes. It is
highly recommended that you use a source code control
system to track changes made to your code and files
in this instance; this step is recommended during
all application modifications. Test code changes thoroughly.
Once finished, test your modified code in your ColdFusion
MX test environment following your normal QA procedures.
The tips in the next section are provided to provide
you with some things to watch out for when making
these modifications.
|
|
|
Tips for updating code to for MX
Migrating your code so that it passes the stricter coding
standards of ColdFusion MX will be easier if you follow
the steps below.
|
|
Watch your code syntax
|
|
One of the biggest differences between previous versions
of ColdFusion and ColdFusion MX is that ColdFusion
MX has strict validation for CFML syntax. Invalid
tag attributes will result in errors. ColdFusion 5
and earlier versions have a switch in the ColdFusion
Administrator Settings page called "Enforce Strict
Attribute Validation" that allows you to enforce
syntax checking, improve page execution time, and
enforce proper code syntax. In ColdFusion MX, you
have no choice but to write code to this standard.
As a suggestion, it may be worthwhile to test your
application on your existing version of ColdFusion
Server with this option enabled before attempting
to migrate to ColdFusion MX.
|
|
Beware of variable dot notation
|
|
ColdFusion MX no longer allows you to place a period
in your variable names, as in:
<cfset foo.bar = 1>
which would create a variable named "foo.bar."
In ColdFusion MX, this code is considered "dot-notation"
and is reserved for use with structures. ColdFusion
MX allows the code to run without generating an error,
but instead of creating a simple variable as previous
versions would, it creates a structure called "foo"
with an element named "bar" with a value
of 1. In most cases, this will not prevent your existing
code from running, but it's an important conceptual
change to notice.
|
|
Upgrade from cfgraph to cfchart
|
The cfgraph
tag is deprecated in ColdFusion MX and is being replaced
with the new cfchart
tag because ColdFusion MX includes a new, enhanced graphing
engine behind the scenes that requires new tags with
new attributes to take advantage of all of its features.
The cfgraph tag still works on ColdFusion MX with the
attributes you used previously. However, the displayed
graph may be different due to the new graphing engine. |
|
|
Going live with ColdFusion MX
Once you have successfully completed all of your quality
assurance testing processes, and everything looks good in
the test environment, it's time to go live with ColdFusion
MX in your production environment. You can be confident
with your production upgrade.
Migrating to ColdFusion MX is straightforward if you follow
the steps outlined in this article. In summary, put a copy
of your application on a testing environment running on
ColdFusion 5 (or the version that your application is running
on in your production server). Apply the ColdFusion MX upgrade
to your testing environment and fix the CFML code based
on the results from the Code Compatibility Analyzer. Test
your application based on your existing documentation. Move
your CFML code from the test environment to your production
environment, so long as you did not use any ColdFusion MX
code syntax. Finally, upgrade that environment to ColdFusion
MX.
|
|
| About
the author
Jim has seven years experience building web
applications and has been programming with ColdFusion
since the release of version 2.0. He has built
e-commerce sites and enterprise web applications
for such customers as the U.S. Mint, the FAA,
Pfizer, Pharmacia, The BOC Group, and Schering-Plough.
Jim is an alumnus of the Johns Hopkins University
where he graduated with a Bachelor's degree in
Earth and Planetary Science. Jim is also a Microsoft
Certified Database Administrator and a Macromedia
Certified Advanced ColdFusion Developer.
Jim has worked as a technical editor and
consultant on several popular ColdFusion books.
For Macromedia, he works as Principal QA Engineer
for ColdFusion concentrating most of his efforts
on the performance of the product. |
|
|
|
