Flex Builder Refactoring “Gotchas”

Flex Builder (based on Eclipse) is a good developer environment, but one thing that stresses it more than anything is the refactoring support.  As a long-time Eclipse-based Java developer I’m very comfortable with how refactoring works for Java code and projects, so, perhaps, this has colored my view of Flex Builder’s refactoring support.

Refactoring is the fancy name for changing the structure of code.  It covers everything from renaming a property or function to renaming or moving a class, either within a project or from one project to another.  The goal of a refactoring system is to go through all code artifacts that reference the changed code and fix names and mappings so that the code still builds and runs (after all, you haven’t change the logic in your code, just names and/or locations of objects that make up the already-working system).

When would you want to refactor?  Suppose that you started working on an interface to a payroll system.  Initially, you might have a single project that contains both the code to access the payroll system and the user interface.  As the project grows, you realize that it might make sense to split the interface and UI code into separate projects – perhaps you want to have an AIR UI as well as a web-based UI, or perhaps you are just getting a new UI developer and want to minimize how much code he needs to digest as he picks up the code.  Perhaps, also, you decide that you need to change the names of some classes or methods so that they conform to a team standard, or even to reorganize the code to pull out some interfaces that help abstract some functionality to allow you to integrate this with several different interfaces.  Refactoring is the engine that makes this a lot easier.

We moved to Flex from doing UI’s in Java/SWT because we wanted to leverage the browser as an interface to our system and because we thought we could quickly try several different UI approaches.  We all had years worth of experience developing in Eclipse, so Flex Builder was very fast for us to pick up.  Unfortunately, the first time we had to refactor our code, we found that the refactoring support wasn’t what we were used to.  Some of the gotchas we hit include:

• Renaming was somewhat problematic; sometimes the name change would propagate properly, sometimes not.
• After moving a class from one project to another, sometimes the code would build, sometimes not, and if it did build, when we tried to run the application, the run-time would complain that it could not find the class.
• We could move a class from one package to another, but the package descriptor in the file did not change

There are several tricks that you can do to ensure that your code will build:

• Don’t do more than one thing at a time! Don’t move and rename a class; instead, move it, do all the checks to see that things still build and run, then rename it and do the same.  Or vice-versa.
• Always check the build path for the project. To do this:
  • Right click on the project in question and select “Properties” (it’s all the way at the bottom of the pop-up menu)
  • Select “Flex Library Build Path” in the panel on the left of the Properties window
  • Select the “Classes” button in the button bar near the top of the right-hand panel (it should be the button all the way to the left)
  • Scroll down until you find the class that you’ve moved or renamed
  • Make sure that the checkbox to the left of the item is selected.  If it isn’t, then the class is not visible outside of this project
• The order projects are loaded matters. If you move a class from one project to another, you need to make ensure that the project that contains the class is loaded before any other project that references the class.  This is especially important for any projects you either load externally or load as a runtime shared library.  To do this:
  • – Right click on the project in question and select “Properties” (it’s all the way at the bottom of the pop-up menu)
  • – Select “Flex Library Build Path” in the panel on the left of the Properties window
  • – Select the “Library Path” button in the button bar near the top of the right-hand panel (it should be the button all the way to the right). Once there, you can move a project up in load order by selecting the project and clicking the “Up” button, or you can move it down in load order by clicking the “Down” button.
• Always rename textual matches. When you rename a class, always check “Rename textual matches in strings (requires preview)”.  This catches some instances that the refactoring logic misses.
• Manually edit package names. Any time you change a package that a class is in, you have to open up the class in the editor and change the package name in the “package” descriptor right at the top of the file.  (Note: There are several bugs in the Adobe Bug and Issue Management System that are tracking refactoring problems, such as Bug FB-11318 and Bug FB-12987 – if these or other bus are important to you please register with the bug database and vote this bug up.)
• Sometimes you need to manually edit .flexLibProperties. Once in a while, after you have moved a class from one package to another, you get a stale reference to the old package.  What has happened is that the .flexLibProperties file in the old project isn’t always updated correctly.  If this happens, then you need to edit this file to remove the old export.FlexBuilder normally hides the .flexLibProperties, so the best way to find the .flexLibProprties file is to do a search for the class.  To do this:
  • Select “Edit->Find in Files…”
  • Enter the name of the class in the “Containing Text” box
  • Make sure that the “File name patterns” box contains an asterisk (*)
  • Click the “Search” button
  • The search results will appear in the “Search” view (typically in the lower right portion of your screen).  One more gotcha: there should be two .flexLibProprties files that show up – the one that’s from the old project where the class was, and the other from the new project.  Be sure to only select the .flexLibProperties from the old project.
  • Remove the line with the old class name and save the file.
  • Clean the old project.

If you use these tricks then you should be able to successfully refactor your code.