Introduction

A cartridge is a code container for implementation artifacts like templates, pipelines, Java code etc. that provide business logic or technical functionality to Intershop Commerce Management (ICM).

Cartridges are the building blocks and deployment containers of an ICM application. Cartridges can be installed (deployed) on an ICM application server to make the functionality implemented by the application units available on the server.

Thus, cartridges are the standard mechanism for packaging and deploying.

Any objects and entities defined at the different architectural layers (persistence layer, business object layer, presentation layer) are distributed over a set of cartridges.

The cartridge concept provides a uniform and easy-to-handle way of integrating new code components into ICM. All new applications to extend and/or customize ICM must abide by the organizational principles that the cartridge concept imposes, no matter whether the application is simple or complex.

Cartridge Structure

Directory Structure

The following files in <IS_SOURCE>/<cartridge_name> are deployed to <IS_SHARE>/system/cartridges/<cartridge_name>/release:

Cartridge Meta Data

Meta data of a cartridges include the display name, version, build number and the dependency list.

plugins {
	id "java"
	id "com.intershop.gradle.cartridge-resourcelist"
	id 'com.intershop.icm.cartridge.product'
}

ext.displayName = "Adapter - Customization"

dependencies {
	cartridge "com.intershop.business:bc_mvc"
	implementation "com.google.guava:guava"
}

Version Declaration

Versions can be defined at a central place (e.g. in a versions project) with the java-platform plugin.

1.  include the versions sub-project to the customization project

include("versions")

2. declare versions as constraints. (inject constraints to other projects via code).

plugins {
	id 'java-platform'
}

dependencies {
	constraints {
		api "com.google.guava:guava:30.1.1-jre"
	}
}

def depConstraints = project.dependencies.constraints

rootProject.subprojects { subprj ->
    plugins.withType(com.intershop.gradle.icm.cartridge.CartridgePlugin) {
        depConstraints.add("api", subprj)
    }
    plugins.withType(com.intershop.gradle.icm.cartridge.DevelopmentPlugin) {
        depConstraints.add("api", subprj)
    }
}

tasks.withType(GenerateModuleMetadata) {
    enabled = false
}

publishing {
    publications {
        mvn(MavenPublication) {
            from components.javaPlatform
        }
    }
}

Cartridges at Runtime

Cartridge Engine

The cartridge engine is responsible for loading the meta data of cartridges listed in CARTRIDGE_LIST environment when Application Server is started:

CARTRIDGE_LIST: ft_icm_as

Lifecycle of a Cartridge

During startup and shutdown of the application, cartridges are registered at lifecycle hooks.

A lifecycle class for the cartridge can be defined in the administrative properties (/src/main/resources/cartridges/<cartridge-name>.properties).

The property intershop.cartridges.<cartridge>.classname is used to define the Java class for the cartridge lifecycle. This class needs to implement com.intershop.beehive.core.capi.cartridge.Cartridge providing appropriate lifecycle methods.

Life Cycle Hooks 11.0	Life Cycle Hooks <= 7.10

Cartridge Development

Architectural Layers and Cartridge Types

An Intershop application consists of the following architectural layers with corresponding cartridge types:

Cartridges must be named according to the architectural level that they represent:

The different cartridge types have well-defined allowed dependencies with each other. The cartridge type is reflected in the cartridge name.

Cartridge Dependency Rules

The dependencies can also be expressed in a matrix: the rows represent the using layer, the columns represent the used layer:

Cartridge Type	Feature	Development	Initialization	Application Suite	Adapter	Application	User Interface	Business	Platform	Common Library
Feature Cartridge
Development Cartridge
Initialization Cartridge
Application Suite Cartridge
Adapter Cartridge
Application Cartridge
User Interface Cartridge
Business Cartridge
Platform Cartridge
Common Library

Naming Conventions

Initialization Cartridges

Initialization cartridges are different from normal implementation cartridges because they are usually only used at initialization time of the system (e.g., DBInit). After all content has been prepared and is available in the database/file system, they are no longer needed. The name of an initialization cartridge should reflect the content that is initialized by the cartridge.

Examples:

• init_operations (initializes the Operations organization and the root users)
• init_smc (initializes the SMC user account, the SMC roles and permissions in the database)

Hierarchical Names

Cartridges on the same architectural level may form hierarchical structures, where some base functionality that is defined in one cartridge can be refined in additional sub-cartridges. The hierarchy is expressed in the naming of the project.

Example:

• pf_objectgraph (contains the base functionality for object graphs)
• pf_objectgraph_guice (contains the implementation of the object graph API based on Google's Guice)

The hierarchy in the cartridge name is also reflected in the Java package names of the cartridge. Each additional fragment in the cartridge name is translated to an equivalent level in the Java package name.

Example:

• com.intershop.platform.objectgraph.*
• com.intershop.platform.objectgraph.guice*

Naming of Pure Tests Cartridges

There are cartridges containing integration API tests that test a specific cartridge. The naming of these cartridges should follow the rule: <cartridge>_test, e.g.:

• bc_product and bc_product_test
• ac_ruleengine_drools and ac_ruleengine_drools_test

Naming of Customer Project Cartridges

Cartridges in customer projects should follow the same principles as Intershop cartridges.

However, to facilitate differentiation, it is recommended to prefix the cartridge name with an identifier for the vendor, e.g. (customer "XYZ"):

• xyz_bc_product
• xyz_as_sales_organization
• xyz_init_webshop

API vs. Implementation Cartridges

Any cartridge may define an API (for example, using the common CAPI package convention) and / or provide an implementation (that must be located in internal packages, as usual). There may be cartridges that only consist of API and other cartridges that only consist of implementation code, and some cartridges may contain both. There is no special naming for pure API cartridges, as every cartridge is considered to be "equal". If the purpose of an implementation cartridge is to provide the implementation for a certain technology, this should be reflected in the cartridge name.

Example:

• bc_customer (defines the business API for Customers)
• bc_customer_orm (implements the business API for customers and maps it to the ORM persistent objects)

Package Examples:

• com.intershop.component.customer (bc_customer)
  • c.i.c.customer.capi.business (business object api)
  • c.i.c.customer.capi.tools (static tooling)
  • c.i.c.customer.capi.entities (persistence entities api)
  • c.i.c.customer.capi.service (service api)
  • c.i.c.customer.internal.modules (guice modules - binding implementation to api)
  • c.i.c.customer.pipelet (pipelet descriptors and classes)
• com.intershop.component.customer.orm (bc_customer_orm)
  • c.i.c.customer.orm.internal.orm (PO persistent objects)
  • c.i.c.customer.orm.internal.impex (import, export via persistence)
  • c.i.c.customer.orm.internal.business (business layer for ORM implementation)
  • c.i.c.customer.orm.internal.modules (guice modules - binding implementation to api)
  • c.i.c.customer.orm.dbinit.data (dbinit data)
  • c.i.c.customer.orm.pipelet (pipelet descriptors and classes)

Common package name build pattern for cartridges:

1. Use the cartridge name and replace bc_ with com.intershop.component.
2. Replace all underscores with a dot, e.g., the package for bc_product_configuration will be com.intershop.component.product.configuration.

This way you can avoid conflicts with other cartridges if these cartridges use the same pattern and preferred sub-packages (capi, internal, dbinit, pipelet).

Abstractions and Reusability

When developing a new application, a developer could start on the application layer. It is perfectly okay to put all the implementation code into this application cartridge, including application definitions, templates, pipelines, business objects, persistent objects and so on.

When developing another application, this application could also be completely "self-contained". However, this approach is not very useful, since everything would have to be implemented again and again. Instead, we want to benefit from a maximum reuse of code and existing concepts. Therefore, the common approach is to create "abstractions" or "generalizations" of concepts and move them to the lower architectural layers. This also means that such abstractions must be designed for reuse in multiple different contexts.

Examples:

• sld_ch_base (defines common functionality of all channel back office applications)
• sld_ch_partner_plugin, sld_ch_consumer_plugin (defines the specific functionality of a particular channel)