Technotes

This can occur when switching in the Debug View from FusionDebug to the Java application.

The expression which has been evaluated by FusionDebug is incorrectly assumed by JDT to be a Java expression. This is an issue with the JDT plugin, rather than a FusionDebug issue.

I’ve added the debugging settings required by FusionDebug to my servers configuration file /opt/jrun4/bin/jvm.config and now my server does not start any more.

When I start the server with

/opt/jrun4/bin/jrun start

I get the following error message:

Error [98] in bind() call!
<<<<<<< support.html
FATAL ERROR in native method: No transports initialized
err:: Address already in use
Socket transport failed to init.
Transport dt_socket failed to initialize, rc = -1.

This is caused by the attempt to start all servers sharing the same configuration (which is the default). The port number you have defined in the debug settings can only be used by one server at a time. Therefor either start only the server you want to debug, e.g.

/opt/jrun4/bin/jrun start cfusion

or use separate JVM configuration files for each server. Read the Adobe technote to get the details on how to do that.

This issue is caused by Eclipse’s own implementation of the Java Debug Interface (JDI) which does not accurately reflect the Sun reference JDI implementation. Because of the way Eclipse manipulates the Java classpath, any Eclipse application (e.g. FusionDebug) attempting to load a JDI implementation will reference the Eclipse classes, instead of the Sun implementation.

We have provided links to the relevant Eclipse bugs below.

Eclipse Issues

Problems with FusionDebug on Mac OS X can be reduced to two Eclipse issues:

• Eclipse supplies their own JDI implementation which is incompatible with the Sun JDI Specification (Eclipse Bug 101686)
• This issue may not occur on Eclipse 3.1 or earlier because it was masked by a classpath issue which has been subsequently fixed (Eclipse Bug 89111)
  • This is a Mac-specific bug with Eclipse’s classpath, which was set incorrectly and caused Eclipse JDT (normal Java) debugging to be unavailable. This would allow our supplied-JDI implementation to function correctly.
  • The fix for this issue (a correct Classpath which references the Eclipse JDI implementation) allows Eclipse JDT debugging to function, but unmasks bug 101686, which causes FusionDebug to malfunction.

Immediate Workaround

This workaround creates a second Eclipse bundle which does not use the Eclipse JDI implementation. This will unfortunately disable Eclipse JDT (normal Java) debugging, but will allow FusionDebug to function. The remainder of Eclipse properties (workspace, configuration, formatting etc.) will remain identical between the bundles. The original bundle can be used for JDT debugging, if required.

• Create a copy of your Eclipse installation with a modified classpath. This will make Eclipse find the Sun JDI implementation.
  • Locate your root Eclipse installation.
  • Within this folder, copy the Eclipse.app bundle, renaming the copy to EclipseFD.app
  • Open the EclipseFD.app bundle (Right click/Ctrl-click on EclipseFD -> Show Package Contents)
  • Navigate to Contents -> MacOS and edit the eclipse.ini file
  • Remove the line which begins -Xbootclasspath/p:../../../plugins/org.eclipse.jdt[…]
  • Save this file.

Caveat: This will disable JDT (normal Java) debugging within Eclipse. For this functionality, use the original Eclipse.app bundle.

If you are using a standard Eclipse install, or the FusionDebug standalone bundled IDE, but not Flex Builder, carry out procedure FDS – 92 linked below.

If this does not rectify the problem, you may need to alter the Lingon startup command for ColdFusion to include the Java options to enable debugging. The startup command should read as follows:

/System/Library/Frameworks/JavaVM.framework/Versions/1.4.2/Home/bin/java 
-server -Djava.compiler=NONE -Xnoagent -Xdebug 
-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8777 
-Djava.awt.headless=true -jar /Applications/JRun4/lib/jrun.jar -start cfusion

N.b. this is all a single line. This Java configuration listens on port 8777 for debugging connections. Make sure your FusionDebug Debug Configuration within Eclipse reflects this in the connect tab.

The FusionDebug Eclipse Plugin installs its own launcher to enable starting Eclipse in the FusionDebug perspective.

If you have used the plugin launcher (the ‘red bug’ icon) to start Eclipse and then use the File->Switch Workspace function it does not restart automatically. Please manually restart Eclipse in this case.

No. Simply call the page in the web browser as you normally would. The port configured in jvm.config is for the internal debugging data and is not related to the web server or web browser.

There are two places where users often experience issues when configuring FusionDebug 1.0.

The first is with the Webroot folder; this value must be the path to the folder on the actual CF server. e.g. the value should not be the name of a share Q:\CFusionMX7\wwwroot, it should actually be: C:\CFusionMX7\wwwroot where the files are placed on the server.

The second issue tends to be that FusionDebug may pick the wrong source file to display, if you map your project to the webroot folder and have mulitple files of the same name in different folders. However this is very simple to fix, and can be done so by turning on the Search for Duplicate Source Files checkbox on source code tab of the Fusion Debug Launch Control.

Breakpoints Don’t Fire: Setting Webserver Folder and Eclipse Project Structure

Problem:

• Breakpoints don’t fire at all
• Breakpoints don’t fire in CFM/CFC pages in subfolders

Two of the most important options in FusionDebug are Webserver Folder, and Eclipse folder structure mirrors webserver. This article discusses how to configure these options in detail.

FusionDebug uses the information in the Configuration Dialog (accessible from the Run -> Debug menu) to accurately set breakpoints. If the information in this dialog is not configured correctly, FusionDebug may report that a breakpoint has been set, but it never fires: the associated page always runs to completion.

Solution:

In most cases, this problem can be solved by correctly configuring the Webserver Folder and Eclipse folder structure options in FusionDebug. Once these options are correctly configured, the configuration usually doesn’t need to be subsequently changed.

FusionDebug needs to know exactly where on your ColdFusion server the files are located, and how folders are structured. It uses these options, together with your Eclipse folder structure, to accurately set breakpoints and select the correct files when breakpoints fire.

Please note that FusionDebug 2 has an enhanced source code lookup system.

This is a known bug of the FusionDebug Setups on Linux and Solaris platforms not saving meta data about the installation in the Java Preferences User Backing Store if the Java Preferences System Backing Store in directory /etc/.java/.systemPrefs does not exist or is write protected.

Workaround

If the Setup does not detect a previously installed version you can install on top of the existing version to update it.

Background information

FusionDebug Setup and FusionDebug itself make use of the Java Preferences API to read and write data about the installation and other parameters from and to the so called Java Preferences Backing Store on the destination computer.
On Windows the location of the Backing Store is in the Windows Registry, on MacOS, Linux and Solaris the location of the Backing Store is typically the file system. The Backing Store itself is made up of a System and a User part that reside in different locations.

Windows

On Windows the System Backing Store is located in the registry in [HKEY_LOCAL_MACHINE\Software\JavaSoft\Prefs] whereas the User Backing Store is located in [HKEY_CURRENT_USER\Software\JavaSoft\Prefs].

MacOS

On MacOS the System Backing Store is a set of *.plist files in the directory /Library/Preferences, the User Backing Store is a set of *.plist files in the directory $HOME/Library/Preferences.

Linux and Solaris

On Linux and Solaris the System and the User Backing Store are a hierarchy of XML files. There can be multiple locations for the System Backing Store. If the directory /etc/.java/.systemPrefs exists and is writable it will be used as the System Backing Store, otherwise the directory $JAVA_HOME/jre/.systemPrefs will be tested. If this directory is writable or can be created it will be used as the System Backing Store. If this does not work no System Backing Store will be available.
The User Backing Store is located in the directory $HOME/.java/.userPrefs.

Depending on the privileges of the user that runs the Setup, data about the installation is stored in one of the two possible places described above. FusionDebug Setup first tries to access the System Backing Store and uses the User Backing Store if it cannot write to the System Backing Store. Due to a bug in a third party API which is used by the FusionDebug Setup this does not work correctly on Linux and Solaris.

There are three possible causes here:

• Ensure that FusionDebug has actually completed the step. If the Debug View still shows the CF page is “(Stepping)”, wait until this completes. Sometimes this can take a few seconds, depending on whether the page has been run previously.

• ColdFusion may have optimized the CFC constructor call away, or placed it on a line other than the original source code line. Try performing “Step Into” from the line prior to the tag which constructs the CFC.

Another thing that can make stepping seem not to work exhibits itself while control is stopped on a given breakpoint. Despite subsequent requests to step through code, no new lines seem to be reached in the file editor, but if you watch the stack trace pane you see the line numbers properly stepping through the code. The problem occurs because you have opened the file using the file system rather than an Eclipse “project”. FusionDebug only works with Eclipse projects, please open the file by clicking on it from within the Eclipse project instead of using the Eclipse File->Open File… menu.

This can occur if you haved used Eclipse’s Software Updates -> Manage Configuration dialog to revert your FusionDebug installation from 2.0.0 to 1.0.0. The original FD2 Trial license (serial number FD200TST) is still installed.

Additionaly, if you had time remaining on the original FusionDebug 1.0.0 license, this will also have expired.

To continue using FusionDebug 1.0.0, the FusionDebug 2.0.0 trial license must be activated. Once this is done, the original FusionDebug 1.0.0 license file can be re-installed and activated again.

If you later switch from 1.0.0 to 2.0.0, you can continue with your 2.0.0 trial license without problems.

The server configuration wizard

• tracks the changes that it makes,
• backs up the original configuration
• can undo the changes during an uninstallation.

If you are comfortable editing JRun’s jvm.config file, the change to enable FusionDebug is quite simple and can be performed in a few minutes. The Server Configuration Wizard simply provides a comprehensive graphical tool to accomplish the same thing.

Some classes of array data (notably binary arrays loaded from CFFILE tags) are truncated to 256-bytes in order to prevent Eclipse becoming unresponsive handling very large quantities of data. The ‘Expressions’ and ‘Variables’ views both update their displays to notify you when this truncation has occurred by appending “Truncated: showing 1 to 256 of X” where ‘X’ is the real length of the array.

The Inspect Expression popup also truncates this data but does not notify you when the truncation has occurred. This is due to a limitation of the Eclipse platform’s Popup mechanism. Once a tree element has been drawn, it is impossible to update it without re-displaying the popup, and for this reason the “Truncated” message is not shown.

FusionDebug can access any variables that are available in any server-side scope, for example Variable, Application, Session, Form, URL etc.

You should be able to find all of the values submitted on the flash form in the FORM scope of the Variable View.

Any CF page or code which runs through the ColdFusion engine may be debugged:

• Normal ColdFusion CFM, CFC, module, cfinclude or sub-tag pages
  • Sub-pages, including CFCs, modules and included pages will generate one frame each in the Debug View, allowing variables to be viewed for each frame, and which function, file and line number corresponds to the call
  • CFCs will also expose the special Function Local Scope (var, in cfset)
• Framework components
• ColdFusion code called from AJAX frameworks
• Flex CF code
• ColdFusion Asynchronous Gateway code
• .. etc.

The following code may not be debugged using FusionDebug:

• Native C or C++ CFX tags
• Java code,
• Java, COM, Web Service or objects created with cfobject
• JSP pages, or sections of CF pages which contain Java or JSP calls

The thread list in Debug View is in suspend order. The most recently-suspended thread appears last. Stepping a thread does not count as a resume for the purposes of ordering, and does not cause the thread order to change. Resuming a thread which later hits a breakpoint causes that thread to correctly reappear at the end of the list, since it has subsequently suspended on a breakpoint.

Although FusionDebug supplies this data correctly to Eclipse, Eclipse 3.1 sometimes changes the order of these threads. This behavior is not the case in Eclipse 3.2.1.

Since Eclipse updates contain a large number of stability, performance and functionality fixes, we recommend customers always use the newest Eclipse platform available.

Pages, CFQUERY, CFLOCK, CFTRANSACTIOn etc. may time out when they are paused using FusionDebug.

When FusionDebug suspends on a breakpoint, any timeouts set in the ColdFusion MX Administrator are still in effect and will cause the appropriate error message.

Suspending due to a breakpoint extends the normal duration of these tags, and will prevent other pages from continuing if they are waiting for the same locked resource. The ColdFusion server will see these pages as long-running requests, and apply the normal timeout to them, if this feature is enabled in the ColdFusion Administrator.

This feature is disabled by default in CF 6.1, but enabled in CF 7 and 8.

The page request timeout can be overridden on a per-page basis using CFSETTING RequestTimeOut.

FusionDebug won’t connect to my ColdFusion instance, failing with message: “FusionDebug could not connect to the target system (machine:port)”.

• Check you have enabled Java debugging on a port that is available, and that ColdFusion MX or JRun has started up correctly.
• If you are using a non-standard port (not 8000), make sure you have correctly entered that port in the configuration dialog.
• Make sure there are no firewalls or port restrictions in the network path between you and the target system.
• If you are using a multiserver or J2EE install, make sure the JRun Administration instance has not started, as this will often claim the debugging port before the ColdFusion instance.

Mac OS X users should check and run procedures FDS-92 and FDS-51, linked below. All platforms should check technote FDS-93 and its associated linked technotes.

Sometimes certain elements in the variables view will open themselves immediately when collapsed.

This is a known Eclipse 3.1 bug (number 110206, available here) and was fixed in Eclipse 3.2. We do not recommend Eclipse 3.1 as a FusionDebug platform, and would urge you to upgrade to the latest Eclipse release, or to a FusionDebug complete IDE installer.

Often, stepping ahead using FusionDebug will make this issue go away.

FusionDebug is able to work alongside DreamWeaver and any other editor you might be used to. There’s no requirement to perform development work inside FusionDebug. You can switch to FusionDebug to debug whenever required. Simply create a Project within FusionDebug/Eclipse which points to your existing source code.

If you’re having synchronization problems, where FusionDebug/Eclipse doesn’t see changes you made in your regular editor, consider enabling automatic refresh within Eclipse:

Windows -> Preferences -> General -> Workspace – select Refresh automatically.

To make FusionDebug/Eclipse refresh the workspace when it starts up, select Refresh workspace on startup from the General -> Startup and Shutdown page.

This may occur when CFEclipse is also installed, either separately or using the FusionDebug bundled installation.

Both CFEclipse and the Eclipse platform itself claim these shortcuts: F5 on CFEclipse and Eclipse means ‘refresh browser’ and F8 on CFEclipse means ‘Open Scribble Pad’.

These keys always have their debugging meanings (Step Into and Resume, respectively) when the Debug View is focused.

If you want to configure these keys so they will continue to work when a CFEclipse editor is active, please use the following procedure.

• Select Window -> Preferences
• In the Preferences window, on the left open General and select Keys.
• In the Key Sequence area, place the cursor in the Name field and press the F5 key.
• Eclipse shows you all the commands bound to that key.
• Select the CFML Editor context line, and click the Remove button just below.
• Select the In Windows line, and again click the Remove button.
• Place the cursor in the Key Sequence ‘Name’ field, and use backspace to delete the F5 mapping.
• With the cursor still in the Name field, press the F8 key.
• Select the CFML Editor context line, and click the Remove button.
• Finally click Apply then OK.

CFEclipse may by default have no currently line highlight color selected. Changing this makes it much easier to see which line you are currently debugging.

Select the Eclipse Window -> Preferences menu.

From the Preferences dialog, open the CFEclipse node, and click on Editor. In the Appearance -> Color Options select Current line highlight and choose a color other than white. Apply this change.

You don’t need CFEclipse to use FusionDebug.

However, we do recommend CFEclipse, and our install packages will offer it as a bundled component. CFEclipse provides a comfortable, comprehensive environment for working with ColdFusion within Eclipse. We’re sure you will like it if you give it a try!

Please contact FusionDebug Support at , and we’ll do everything we can to get you up and running as soon as possible.

Activation is a measure to help protect against unauthorized copying of the software.

By default, FusionDebug is installed with a 20-day trial license. Once you have bought and uploaded a full license, you will have a further 10 days in which to activate it. After the software is activated, it need not be activated again until re-installed.

Under some circumstances the trial license initialization can fail and it expires immediately.

Please contact FusionDebug Support at to get a free trial license via email.