New version of GlassFish Eclipse plugin - migration guide

Who is this guide intended for

This short step-by-step guide should help users that have installed GlassFish Tools plugin for Eclipse to update to the new version. The new version contains many changes, like

  • dropping GlassFish 2.x support
  • changing structure of server adapters
  • changing names and structure of provided project facets
  • adding GlassFish 4 support

Before and after the update the user needs to take neccesery actions to adapt his workspace and projects to these changes. These action unfortunately can't be taken automatically during the update process.

Update GF tools plugin


Before we start to update the plugin, backup your Eclipse installation and workspaces that your are using. In case something goes wrong, you can easily restore your environment.

Where to update from?

You could have installed your current version of GlassFishTools plugin either from OEPE bundle or from update site (current one The OEPE package contains oficial releases (more stable, tested) of GF plugins and new releases come one or two times per year. The update sites on contain developer builds that are released as needed, typically a lot more often then OEPE. You can download from whatever meets your needs.

What to do before updating the plugins?

Since we changed structure of server adapters, after the update your currently registered GF runtimes and servers won't work with the new version of plugin. So you need to unregister both GF runtimes and servers. The easiest way to do that is following:

  1. Open Eclipse preferences. Go to Server->Runtime Environments section.
  2. Remove all GlassFish server runtimes. Remove the runtime from targeted projects and remove also affected servers when Eclipse asks you.

Now you they are probably many errors reported in your workspace. We will resolve them after update.

The second big change touches the facets structure. The old GlassFish Deployment Descriptors Files facet (hereinafter referred to as sun.facet) is not defined in new version anymore so it would become unusable and (what is even worse) almost unremovable after the update. So for every project that used sun.facet (it could be web, EJB or EAR project) do:

  1. Right-click the project and open Properties.
  2. Go to Project Facets section.
  3. Uncheck the sun.facet and click OK or Apply button.

If you forgot to remove sun.facet from some project, do not worry, there is a way how to do it even after update but it is more tricky.

Last thing you need to do before the update is uninstalling all GlassFish 3.1.x Application Server runtime plugins. You can keep GlassFish Application Server runtime plugin. Steps:

  1. Go to About Eclipse section.
  2. Click "Installation details" button.
  3. Uninstall all GlassFish 3.1.x Application Server runtime plugins.

How to update the GF plugins?

  1. Make sure that you have either or OEPE update site enabled.
    • Go to Preferences->Install/Update->Available Software Sites and make sure that these sites are defined and checked.
  1. If you have GlassFish Application Server runtime installed (you can check it in About Eclipse->Installation Details section), do additional step
  1. Go to Help menu and choose Check for updates.
  2. You should be offered to update (assume that you install from site):
    • GlassFish Application Server runtime (only when you have installed it before)
    • GlassFish Tools
    • Java EE 5 Documentation
    • Java EE 6 Documentation
  3. Update all these plugins in one update batch.
  4. Restart Eclipse.
  5. Optionally you can now install two new plugins:
    • GlassFish 4.0 Server Runtime plugin from site
    • Java EE 7 Documentation from OEPE or site
      After restart the GlassFish 4.0 Server Runtime plugin will register GlassFish 4.0 runtime and server, saving you work.

How to solve problems after update?

You will see probably many problems after your workspace is opened again. Let's solve them.

  1. Register again your servers. Right-click into Servers section and choose New server. All 3.1+ servers are now registered under common server type called GlassFish 3.1.x. You shouldn't loose any configuration if you use the same server and same domain as before.
  2. For every project (currently opened in workspace or opened/imported later) that targeted removed GlassFish runtimes (now probably reporting issues) do
    1. Right-click the project and open Properties.
    2. Go to Targeted Runtimes section. Check newly registered server that you want to deploy project on. Uncheck other (not existing) GlassFish runtimes. Click Apply or OK button.
    3. line-height: 13pt; padding: 0px; margin: 0px;">Go to Project Facets section. If you see warning that sun.facet could not be found you were using old facet and forgot to remove it. The sun.facet can't be now removed in GUI - just note the project. Instead of this facet you check glassfish.web (for Web projects) or glassfish.ejb (for EJB projects). Click Apply and confirm.

For every project still referencing the old sun.facet, do:

  1. Go to Navigator view.
  2. open .settings/org.eclipse.wst.common.project.facet.core.xml file.
  3. delete element that has value of facet attribute "sun.facet". Save the file.

Post a Comment:
  • HTML Syntax: NOT allowed

This blog is intended (but not limited) to inform about new features and changes done in Glassfish plugins for Eclipse and Netbeans IDEs.


« July 2016