Thursday, January 20, 2005

Changing your Creator package names

WARNING: This blog entry was imported from my old blog on (which used different blogging software), so formatting and links may not be correct.

In Creator, your project name is used as the java package path,
and as the web application context name.

What if your project has grown and you want to change the name, either
because you don't think webapplication24 is very professional
sounding in your context name (which shows up in the web app URL), or because
you don't like to see myfirstsimpletest as the package name on all your now complex page beans?

Unfortunately, there's no support in the IDE to do this yet. Which means
you have to do it by hand.
It's actually pretty straightforward, and there are no surprises; you just
need to change all references in the project from the old name to the new
name. However, if you make any mistakes, it is difficult to track down
the problem. Pages will refuse to open, etc., because under the covers
the IDE may fail to locate the page bean for a JSP since it uses the
package path to do the mapping, for example. Therefore, be careful,
and I don't take any responsibility for any damage to your files, or
mood, as a result of trying the below steps. Worked for me, your mileage
may vary.

First thing's first: Make a backup of your project. If things go wrong,
you'll want to be able to start over - but starting over with the
rename operation, not starting over creating your project from scratch!

And while I have the red paint out:

Don't open your project in the IDE until you are completely
done! If there are inconsistencies in the project, the IDE will
attempt to "fix" it, and suddenly you end up with multiple
getApplicationBean methods,
the project file referring to both the old and the new package name, etc.

When you create a project, Creator takes your project name and
creates a "package name" out of it. This package name is used
in all the Java beans in your project, it's used as the deployment
context root, etc. The package name is derived by lowercasing
your project name, and removing all non-identifier characters from it, such
as punctuation, whitespace, etc. Therefore, "My Project" becomes
"myproject". I'll use "myproject" as my sample old name in the
following code fragments, and "New Name" as the new Project name
(which means "newname" will be the new package name and context root).

    1. Exit the IDE.

    2. Rename the project directory - from My
      to New Name.

    3. Now comes the most labor intensive portion of the project transformation:
      you'll need to change the java package name, which will involve updating
      all the java files. You can either use an IDE which supports refactoring
      to do this (Creator doesn't yet, but NetBeans does, as does a number of
      other IDEs). If you use an IDE be careful though to make sure it doesn't
      perform any other changes to your code.

      If you do it by hand, the steps involved are:

      • Rename the java package folder, from
        src/src/myproject to src/src/newname

      • For each Java file, update three things: the package declaration
        (first statement in the file) from package myproject;
        to package newname;, and update the return types
        and casts in the getApplicationBean1 and
        getSessionBean1 methods (4 lines to change). (These
        are not present in all files.)

    4. Next, update src/web/WEB-INF/managed-beans.xml.
      Change the managed-bean-class entries in the
      obvious way:




    5. If you have customized web.xml or faces-config.xml
      (this is not common unless you are an expert user) make sure any references
      to the old names in these files are updated.

    6. Delete the following directories:

      • project-data/private/Windows/

      • build/

    7. Update project-data/


    8. Modify project-data/project.prj. Be careful!!

      <folder name="myproject">
      <file name=""/>


      <folder name="newname">
      <file name=""/>

    9. Then change the other references from "My Project" and "myproject"
      to "New Name" and "newname":

      <project name="My Project" type="WebApp">
      <attr name="displayName" stringvalue="My Project"/>
      <attr name="defaultPackage" stringvalue="myproject"/>
      <attr name="contextPath" stringvalue="/myproject"/>


      <project name="New Name" type="WebApp">
      <attr name="displayName" stringvalue="New Name"/>
      <attr name="defaultPackage" stringvalue="newname"/>
      <attr name="contextPath" stringvalue="/newname"/>

If you've done all the above steps, do a final search through
your code to make sure that all references to "My Project"
and "myproject" have indeed been updated. Now try loading your
project. It should both load and correctly deploy.
In my case I had introduced
a typo in one of the source files, so I got the new error list
on project load (which was added in patch 6, so make sure you
have the latest bits).

You may have noticed in the last step that there is a separate entry
in project.prj for the
contextPath. If all you care about is changing the context
path which shows up in the project's URL when deployed, you
MAY be able to just change this entry in the project file and
leave all your code with the old package name. I have not tried that - so
I have no idea if it works. If anyone tries it, let me know and I'll
report your findings.

1 comment:

  1. Thanks Tor,
    This is exactly what I am looking for. However, your solution is not for JSC 2. Can you explain how to rename the package in JSC 2? Really appreciate your help.