Converting existing projects to Maven

You can convert existing Java™ EE projects to Maven.

Before you begin

Important: Applicable to Liberty, WebSphere® Application Server traditional

Back up your workspace so that you can return to the original project state if necessary.

About this task

The suggested order of tasks for converting projects is as follows:

  1. Set recommended preferences.
  2. Convert non-EAR projects.
  3. Convert EAR projects.
    1. Create a content folder.
    2. Convert the EAR project.
    3. Add modules to an EAR.
    4. Add dependencies to other modules.
    5. Add libraries to the EAR library directory.

Setting recommended preferences

About this task

To use your workspace for Maven projects, first set the recommended preferences. For more information about preferences, see Setting Maven preferences.

Procedure

  1. Access the Maven project settings preferences.
    Click Windows > Preferences > Java EE > Maven > Maven Project Settings.
  2. Click Set all Maven values.
    The preferences that represent the best practices for Maven configuration are set.
  3. Click OK to complete setting the preferences.

Converting web, EJB, connector, application client, utility, web fragment and ejb client projects

About this task

When you convert a project, keep in mind the dependencies that you have to other artifacts and how the artifacts are accessed by the project. In non-Maven projects, this information is specified in project metadata and the MANIFEST.MF files directly. However, in Maven projects, dependencies are specified in the pom.xml file. For example, the artifacts can be accessed through the MANIFEST.MF file or deployed in library directory of the EAR that contains the project. For web projects, artifacts can be deployed in the WEB-INF/lib directory.

First, use the deployment assembly page to gather the dependencies information.
  1. Right-click the project.
  2. Select Properties > Deployment Assembly.
  3. Click the Manifest Entries tab. Make note all of the entries that are referenced by the project.
  4. For web projects, also click the Deployment Assembly tab. Make note all of the projects and JAR files with a deploy path that begins with WEB-INF/lib.
Note: If the EAR project that contains your projects has EAR facet version 5 or 6, then your project might be referencing classes from projects or JAR files in the library directory of the EAR file. Make note of these references as well.

After you gather the required information, you can convert the project to Maven.

Procedure

  1. Right-click the project and select Configure > Convert to Maven Project.
  2. Complete the Maven POM dialog.
    Enter a Group Id, Artifact Id, and Version or accept the defaults. Optionally, enter a Name and Description. For Packaging, choose according to the following project types:
    Web projects
    war
    EJB projects
    ejb
    Connector, Utility, web fragment, and EJB client projects
    jar
    Application client projects
    app-client
  3. Click Finish to complete the dialog.
    The POM editor opens. If there are references to other projects that were lost, you might see compilation errors.
  4. Clean up compilation errors.
    Convert the projects that you want to reference to Maven, and then add Maven dependencies to those projects. See Adding dependencies to other modules.
  5. Update the project.
    After you change the project, right-click the project and select Maven > Update Project.

Converting EAR projects

About this task

Converting EAR projects involves several tasks:
  1. Create a content folder.
  2. Convert the EAR project.
  3. Add modules to an EAR.
  4. Add dependencies to other modules.
  5. Add libraries to the EAR library directory.
Perform the following steps to complete these tasks.

Creating a content folder

About this task

When an EAR project is created in WebSphere® Application Server Developer Tools using the default workspace preferences, the content directory of the EAR is empty, which means that everything in the root folder of the project is included in the EAR file. If the project does not have a content folder, you must create a content directory.

Procedure

  1. Check whether the EAR has a content folder.
    1. Right-click the project and select Properties > Deployment Assembly.
    2. If you see a content folder that is mapped to / (root), the EAR has a content folder other than the root of the project. You can skip the following steps and go to the section Converting the EAR project.
      Content folder not root
    3. If you see that the root of the project is mapped to root as in the following image, the project does not have a content directory:
      Content folder is root
  2. If the project does not have a content folder, click Cancel on the Deployment Assembly page and follow these steps to create one:
    1. Right-click the EAR project and select New > Folder.
      In Folder name, enter the name of the folder structure. For Maven projects, the recommended folder structure is src/main/application. Click Finish.
      Create folder structure
    2. Access the deployment assembly page.
      Right-click the project and select Properties > Deployment Assembly.
    3. Select the entry that maps the root of the project to the root of the EAR and click Remove.
    4. Click Add, select Folder, and click Next.
    5. Select the folder that you created and click Finish.
      For example, if you created the recommended folder structure, select the application folder that is under src/main.
      Select folder
    6. Check the structure.
      In the deployment assembly section, you now have the folder that you created mapped to the root of the project. The following image shows the example if you created a src/main/application folder.
      Folder that is mapped to root
    7. Click OK to complete the deployment assembly mapping.
    8. Move all of the resources that you want to be included in the EAR from the root of the project to the folder that you created.
      For example, if you used the recommended folder structure src/main/application, and the EAR has a deployment descriptor, move the META-INF folder from the root of the EAR file to the application folder.

Converting the EAR project

About this task

When you convert a project, keep in mind the dependencies that you have to other artifacts and how the artifacts are accessed by the project. In non-Maven projects, this information is specified in project metadata and the MANIFEST.MF files directly. However, in Maven projects, dependencies are specified in the pom.xml file. Note the modules that are part of the EAR, the libraries that are shared to other modules using the library directory (for EARs version 5 or newer), or other dependencies.

First, use the deployment assembly page to gather the dependencies information:
  1. Right-click the project.
  2. Select Properties > Deployment Assembly.
  3. Make note of the modules that are part of the EAR.
  4. Make note of the EAR library directory value if the EAR is version 5 or later.
  5. Make note of the JAR files and projects in the library directory. To identify these files, look for JAR files and projects that have a deploy path that begins with the value of the library directory.
Note: Before you convert the project, save a copy of the EAR's deployment descriptor file, META-INF/application.xml, if it exists. Saving a copy is necessary because during the conversion the existing deployment descriptor is replaced by an empty deployment descriptor.

Procedure

  1. Right-click the project and select Configure > Convert to Maven Project.
  2. Complete the Maven POM dialog.
    Enter a Group Id, Artifact Id, and Version or accept the defaults. Optionally, enter a Name and Description. For Packaging, enter ear.
  3. Click Finish.
    The POM editor opens.
    Note: If the EAR had a deployment descriptor, then a new, empty deployment descriptor is generated. If the original deployment descriptor contained elements such as security roles, configure the elements in the pom.xml file. For more information, see: Maven EAR plugin
  4. Update the project.
    After you change the project, right-click the project and select Maven > Update Project.
  5. To complete the EAR conversion, you must complete the following three tasks:
    1. Adding modules to an EAR project
    2. Adding dependencies to other modules
    3. Adding libraries to the EAR library directory