Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Cortex Web Application POMs

Cortex Web Application POMs

Cortex has a number of web applications with overlapping dependencies. To simplify the Cortex web application POMs, we created a parent webapp POM. All Cortex web apps inherit from this parent POM. This simplifies the web application POMs as it reduces the amount of duplicate code in the POMs. The parent POM defines the dependencies once and then all web application project POMs inherit from it, rather than each web application POM defining same dependencies.

Parent POM:
  • ep-cortex-dce-webapp-parent
Projects POMS:
  • ep-cortex-dce-webapp
  • ep-cortex-tutorial-dce-webapp
  • ep-cortex-stubs-webapp

Understanding Cortex Webapp POMs

POM (project object model) is an XML file containing a list of your project's dependencies. Each Cortex resource, carts, profiles, and so on, is a dependency. If you add a new resource, remove an existing resource, or swap a new one in, you need to update your project's webapp POM.

dependencies

<dependencies> lists the project's dependencies, which are the libraries required to run your project. Maven downloads and links the dependencies to your project during compilation.
Element Description
<dependency> A dependency group.
<groupId> A unique ID used to identify a project the dependency belongs to. For example, the groupID for the Elastic Path' Rest Resources project is: com.elasticpath.rest.resource.
<artifactId> The project's name. For example, the artifactID for the searches resource, which is part of the Rest Resource Project, is ep-resource-searches
<version> The dependency's version number.
<scope> Defines the dependency's transitivity and affects the classpath. Often scope for Cortex dependencies is set to: <scope>provided</scope> This tell Maven to not include these dependencies in the build. The dependencies are expected to be provided by another container at runtime, i.e. OSGi. When scope is provide, Elastic Path copies the dependencies to *.war\WEB-INF\bundles\ to allow OSGi to access them.
Scope Settings:
  • <scope>provided</scope>- Dependencies build to: ep-cortex-dce-webapp-1.9.0-SNAPSHOT.war\WEB-INF\bundles\. OSGi scans and loads dependencies into OSGi from this location.
  • no scope - When scope isn't provided, scope is automatically set to compile. Dependencies build to: ep-cortex-dce-webapp-1.9.0-SNAPSHOT.war\WEB-INF\lib\. Tomcat scans and loads dependencies from this location.
For more information on <scope>, see http://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html.

executions

<executions> lists the project's execution groups. An execution configures group configures the goals of the plugin. A plugin goal represents a specific task which contributes to the building and managing of a project.
Element Description
<execution> ep-cortex-dce-webapp-parent has an execution group configured for each Cortex resource. Having them separated into like this allows you to more easily override them in your ep-cortex-dce-webapp POM.
<goal> Defines the goal of the execution group. In most cases, the goal is : <goal>copy</goal>. This goal means the dependency in the execution group is to be copied over to the <outputDirectory> for deployment.
<outputDirectory> Defines where the execution group copies to.
<artifactItem> Defines the groupId and the artifactID for the dependency.

Example: Web Application POM


 ...                     
 <dependencies>
		<dependency>
			<groupId>com.elasticpath.tutorials</groupId>
			<artifactId>example-assets-resource-integration</artifactId>
			<version>${project.version}</version>
			<scope>provided</scope>
		</dependency>            
                      ....

    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-dependency-plugin</artifactId>
        <executions>
                              ...
        !-- Profiles resource server and CE integration -->
          <execution>
            <id>copy-profiles-resource-and-integration-OSGi-bundles</id>
            <phase>prepare-package</phase>
              <goals>
                <goal>copy</goal>
              </goals>
              <configuration>
                <outputDirectory>${war-bundle-directory}</outputDirectory>
                  <artifactItems>
                    <artifactItem>
                      <groupId>com.elasticpath.rest.resource</groupId>
                      <artifactId>ep-resource-profiles</artifactId>
                    </artifactItem>
                    <artifactItem>
                      <groupId>com.elasticpath.rest.integration.epcommerce</groupId>
                      <artifactId>ep-resource-profiles-epcommerce</artifactId>
                    </artifactItem>
                  </artifactItems>
             </configuration>
          </execution>
          <!-- Purchases resource server and CE integration -->
          <execution>
            <id>copy-purchases-resource-and-integration-OSGi-bundles</id>
            <phase>prepare-package</phase>
              <goals>
                <goal>copy</goal>
              </goals>
          <configuration>
            <outputDirectory>${war-bundle-directory}</outputDirectory>
              <artifactItems>
                <artifactItem>
                  <groupId>com.elasticpath.rest.resource</groupId>
                  <artifactId>ep-resource-purchases</artifactId>
                </artifactItem>
                <artifactItem>
                  <groupId>com.elasticpath.rest.integration.epcommerce</groupId>
                  <artifactId>ep-resource-purchases-epcommerce</artifactId>
                </artifactItem>
              </artifactItems>
           </configuration>
        </execution>

Standard POM Use Cases

  • Adding New Resources - Update your webapp POM with the new resource.
  • Adding Libraries to the Web Application POMs - When adding new libraries to your webapp, update your webapp POM with the new library. For more information, see Adding third party jars to Cortex API.

  • Disabling Out-Of-The-Box Resources - Out-of-the-box Cortex resources are defined in the dce-webapp parent POM. In some cases, this POM will be unavailable for developers to modify, so if they want to disable one of the OOTB resources they need to override it in their Cortex web application POM.

    The instructions below describe how to disable the /navigations resource as an example. Be careful when you disable an OOTB resource, as other resources may depend on it.

    To disable the out-of-the-box /navigations resource, add the following <excludeArtifactIds> element to the ext-cortex-webapp POM, as shown below in the example below. This excludes the /navigations resource from being included in the build and effectively removes it from Cortex.
        <!-- Cortex Bundles -->
    <execution>
        <id>copy-cortex-OSGi-bundles</id>
        <phase>prepare-package</phase>
        <goals>
            <goal>copy-dependencies</goal>
        </goals>
        <configuration>
            <outputDirectory>${war-bundle-directory-level-2}</outputDirectory>
            <includeScope>provided</includeScope>
            <includeGroupIds>
                com.elasticpath.rest,
                org.glassfish,
                javax.annotation,
                javax.ws.rs,
                com.fasterxml.jackson,
                io.reactivex.rxjava2,
                org.reactivestreams
            </includeGroupIds>
            <excludeGroupIds>
                com.elasticpath.rest.definitions,
                com.elasticpath.rest.resource.cortex,
                com.elasticpath.rest.integration.epcommerce,
                org.glassfish.web
            </excludeGroupIds>
            <excludeArtifactIds>
                ep-resources-navigations
            </excludeArtifactIds>
        </configuration>
    </execution>

Bundle Packaging and Load ordering

Structure 
             /
             -META-INF/
             -WEB-INF/
             --lib/
             --bundles1/
             --bundles2/
             --bundles3/
             --bundles4/
             --bundles/
The contents of the directories has been omitted.
  • lib: Standard webapp directory for 3rd party libraries required by your application, these might include libraries that are not osgi ready and need to be provided by the osgi environment
  • bundles1: The first directory the osgi framework will load. (Default empty)
  • bundles2: The second directory the osgi framework will load. (Default contains system and runtime bundles)
  • bundles3: The third directory the osgi framework will load. (Default empty)
  • bundles4: The fourth directory the osgi framework will load. (Default conains all of the api resources, apis and integrations)
  • bundles1: The last directory the osgi framework will load. (Default empty)
The bundles that load into each directory are configurable from the webapp pom. You may use the empty directories as you see fit.
Note: When deciding on which directory to use consider that after loading all bundles from a directory the osgi framework will attempt to start them, if the dependencies of a bundle are in the current or previous directories you will get a start error for your bundle.