Converting existing projects to Maven
Posted by Superadmin on August 15 2022 09:59:42

Converting existing projects to Maven

Last Updated: 2021-03-06

You can convert existing Java™ EE projects to Maven.

Before you begin

Important: Applicable to Liberty profile, full profile

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.
Related tasks:
Creating Maven projects
Importing projects
Setting POM entries for projects that target WebSphere Application Server

Setting recommended preferences

About this task

To use your workspace for Maven projects, first set the recommended 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) as in the following image, the EAR has a content folder other than the root of the 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

 

 

 

 

Adding modules to an EAR project

Last Updated: 2021-03-06

You can add modules that are Maven projects or Maven archives to an EAR project.

About this task

Important: Applicable to Liberty profile, full profile

Procedure

  1. Access the Add dependency dialog. Open the POM editor by double-clicking the pom.xml file. Click the Dependencies tab, then click Add.
  2. Enter values for the module. Enter the Group Id and Artifact Id of the module that you want to add. Alternatively, you can use the filter field to search for the module.
  3. Select the module, and click OK.
  4. Configure the module in the maven-ear-plugin. Click the pom.xml tab to work directly with the POM source. Configure the module. The following example shows a configuration for a web module. For a list of supported modules, see http://maven.apache.org/plugins/maven-ear-plugin/modules.html. 
    <plugin>
   <artifactId>maven-ear-plugin</artifactId>
   <version>2.7</version>
   <configuration>
      <version>6</version>
      <modules>
         <webModule>
            <groupId>sample</groupId>
            <artifactId>webapp</artifactId>
				   <!-- More configuration can be set here -->
         </webModule>
      </modules>
   </configuration>
</plugin>
  5. Save the pom.xml file.
  6. Update the project. Right-click the EAR project, and select Maven > Update Project. Click OK when you are finished.
  7. Verify that the module was added to the deployment assembly. Right-click the project and select Properties. Click Deployment Assembly.
  8. If the EAR has a deployment descriptor file, META-INF/application.xml, verify that the module was added to this file.
 

Adding dependencies to other modules

Last Updated: 2021-03-06

You can add dependencies to other modules by setting the addClasspath element to true in the pom.xml file or by using the POM editor.

About this task

Important: Applicable to Liberty profile, full profile

Procedure

  1. Set addClasspath to true in the pom.xml source.
    1. Open the pom.xml file and access the source view. To access the source view, right-click the pom.xml file in the project and select Open With > Maven POM Editor. Click the pom.xml tab.
    2. Find the correct <plugin> section to update. Look for the <plugin><artifactID> section that corresponds to your project type. For example, a web project that was converted to a Maven project has the artifactID set to maven-war-plugin. A converted EJB project will have the artifactID set to maven-ejb-plugin. The following example shows the <plugin> section with the artifactID maven-war-plugin: 
      <plugin>
   <artifactId>maven-war-plugin</artifactId>
   <version>2.2</version>
   <configuration>
      <warSourceDirectory>WebContent</warSourceDirectory>
      <failOnMissingWebXml>false</failOnMissingWebXml>
   </configuration>
</plugin>
    3. Update the <configuration> section to set addClasspath to true. Add the following code inside the configuration section: 
      <archive>
   <manifest>
      <addClasspath>true</addClasspath>
   </manifest>
</archive>
      The following example shows a completed section for a maven-war-plugin artifact with addClasspath set to true. 
      <plugin>
   <artifactId>maven-war-plugin</artifactId>
   <version>2.2</version>
   <configuration>
      <warSourceDirectory>WebContent</warSourceDirectory>
      <failOnMissingWebXml>false</failOnMissingWebXml>
      <archive>
         <manifest>
            <addClasspath>true</addClasspath>
         </manifest>
      </archive>
   </configuration>
</plugin>
  2. Use the Dependencies tab of the POM editor to add the dependency. Click the Dependencies tab. Click Add to access the select dependency dialog. Enter the values for the module that you want to add as a dependency. Click OK when finished.
    Note: When a dependency is added to a web project, the dependency is included by default in WEB-INF/lib location. If the maven-war-plugin is configured to add the class path to the MANIFEST.MF file, then every dependency is included in both the MANIFEST.MF file and the WEB-INF/lib location. If you want the dependency to be included only in the MANIFEST.MF file, mark the dependency as optional. To mark a dependency as optional, in the Dependencies tab, select the dependency, click the Properties button. In the properties, check the Optional box and click OK.
 

Adding libraries to the EAR library directory

Last Updated: 2021-03-06

About this task

Important: Applicable to Liberty profile, full profile

Procedure

  1. Open the pom.xml file in the POM editor by double-clicking the file. Click the pom.xml tab to work directly with the source.
  2. Set the lib directory to be used in the EAR project. Add the element <defaultLibBundleDir> to the configuration of the maven-ear-plugin as in this example: 
    <plugins>
   <plugin>
      <artifactId>maven-ear-plugin</artifactId>
      <version>2.7</version>
      <configuration>
         <version>6</version>
         <defaultLibBundleDir>lib</defaultLibBundleDir>
      </configuration>
   </plugin>
</plugins>
  3. Save the pom.xml file.
  4. Use quick fixes to resolve any errors. After you save the pom.xml file, you might see the following errors in the Problems or Markers view:
    • Library Directory "<PATH_TO_LIB_FOLDER>" does not exist.
    • Project configuration is not up-to-date with pom.xml. Run Maven->Update Project or use Quick Fix.
    Right-click the errors and select Quick Fix to resolve the errors.
  5. Place JAR files in the lib directory. If the lib directory is specified for the EAR project in the <defaultLibBundleDir> element, then all dependencies to JAR artifacts are bundled in the lib directory by default. However, if you want to place a JAR file in a different location, you can use the <jarModule> element to specify a different location.
    For example, the following fragment of pom.xml shows that the EAR project uses lib as the default directory to bundle JAR files: 
    <plugin>
   <artifactId>maven-ear-plugin</artifactId>
   <version>2.7</version>
   <configuration>
      <version>6</version>
      <defaultLibBundleDir>lib</defaultLibBundleDir>
    In the following example, the pom.xml file has a dependency to a shared library that is packaged in lib and a dependency to an EJB client JAR file that is bundled at the root of the EAR file. Without further changes, both are bundled in the lib directory by default. 
    <dependencies>
  	<dependency>
      <groupId>testapp</groupId>
      <artifactId>ejbclient</artifactId>
      <version>0.0.1-SNAPSHOT</version>
   </dependency>
   <dependency>
      <groupId>testapp</groupId>
      <artifactId>SharedLib</artifactId>
      <version>0.0.1-SNAPSHOT</version>
   </dependency>
</dependencies>
    The following example shows how to change the location of the EJB client JAR file: 
    <plugin>
   <artifactId>maven-ear-plugin</artifactId>
   <version>2.7</version>
   <configuration>
      <version>6</version>
      <defaultLibBundleDir>lib</defaultLibBundleDir>
      <modules>
         <jarModule>
            <groupId>testapp</groupId>
            <artifactId>ejbclient</artifactId>
            <bundleDir>/</bundleDir>
         </jarModule>
      </modules>
   </configuration>
</plugin>
    This example shows that the default bundle directory for JAR files is lib, but the EJB client JAR file for <artifactId>ejbclient</artifactId> is in the root of the project. The bundle directory is indicated with <bundleDir>/</bundleDir>.