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 7.

Cartridges are the building blocks and deployment containers of an Intershop-7-based application. Cartridges can be installed (deployed) on an Intershop 7 server in order to make the functionality implemented by the application units available on the server.

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

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 Intershop 7. All new applications to extend and/or customize Intershop 7 must abide by the organizational principles that the cartridge concept imposes, no matter whether the application is simple or complex.

Reference

Cartridge Structure

Directory Structure

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

The following files in <IS_SOURCE>/<cartridge_name>/staticfiles/share are deployed to <IS_SHARE>:

Cartridge Meta Data

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

Starting from version 7.4.6 CI Gradle build tools are used to manage dependencies at source code level. The server will contain ivy files with specific version numbers. See section Cartridge Meta Data at Runtime for details.

apply plugin: 'java-cartridge'
intershop {
    displayName = 'Platform - Core Infrastructure'
    description = 'The core infrastructure cartridge'
}
dependencies {
    compile project(':component') // dependencies inside of multi project
    compile 'javax.inject:javax.inject' // external dependencies, depending on version of gradle tools
}

Versions are defined at central point of a multi project cartridge via version or filter plugin. The filter plugin reads and provides all versions of the given element (set, assembly). For more information see Concept - Gradle Build Tools.

version.com.intershop.3rd_oracle = 11.2.0.3.+
filter.com.intershop.infrastructure.set.p_infrastructure = 1.1.0.1

Cartridges at Runtime

Cartridge Engine

The cartridge engine (pf_cartridge) is responsible to load the meta data of cartridges listed in <IS_SHARE>/system/cartridges/cartridgelist.properties at startup of particular Java applications like the Intershop Application Server, DBInit and DBMigrate tool:

cartridges = tools pf_cartridge pf_objectgraph pf_objectgraph_guice servletengine ...

For more detailed information please refer to Concept - Gradle Assembly Tools and Cookbook - Gradle Assembly Tools.

Cartridge Meta Data at Runtime

Apache Ivy is used to manage the meta data of a cartridge during runtime. The corresponding file is located at:

• ${IS_SOURCE}/<cartridge_name>/ivy.xml
• ${IS_SHARE}/system/cartridges/<cartridge_name>/release/ivy.xml

<ivy-module version="2.0" xmlns:e="http://ant.apache.org/ivy/extra">
    <info organisation="com.intershop" module="core" revision="${version.number}.${build.number}"
          status="SNAPSHOT" publication="20121129123548">
        <description>The core infrastructure cartridge</description>
        <e:displayname>Platform - Core Infrastructure</e:displayname>
    </info>
    <configurations>
        <conf name="runtime" visibility="public" description="Runtime configuration" />
        <conf name="compile" visibility="public" description="Compile time configuration" extends="runtime" />
    </configurations>
    <publications>
        <artifact name="core" type="jar" conf="compile"/>
    </publications>
    <dependencies>
        <dependency org="com.intershop" name="tools" rev="${version.number}" conf="runtime->runtime;compile->compile" />
        <dependency org="com.intershop" name="pf_cartridge" rev="${version.number}" conf="runtime->runtime;compile->compile" />
        ...
        <dependency org="com.intershop" name="messaging" rev="${version.number}" conf="runtime->runtime;compile->compile" />
        <dependency org="com.intershop" name="businessobject" rev="${version.number}" conf="runtime->runtime;compile->compile" />
    </dependencies>
</ivy-module>

Lifecycle of the Cartridge Controller (Deprecated)

In the administrative properties it is possible to define a lifecycle class for the cartridge (<IS_SHARE>/system/config/cartridges/<cartridge>.properties: intershop.cartridges.<cartridge>.classname), which needs to be derived from com.intershop.beehive.core.capi.cartridge.Cartridge providing appropriate lifecycle methods. This controller is responsible for managing the lifecycle of global objects that depend on the lifecycle of the application server.

Cartridge Development

Architectural Layers and Cartridge Types

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

7.8 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	Development	Initialization	Application Suite	Application	User Interface	Adapter	Business	Platform	Common Library
Development Cartridge
Initialization Cartridge
Application Suite Cartridge
Application Cartridge
User Interface Cartridge
Adapter 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 make a distinction easier it is recommended to prepend an identifier for the vendor into the cartridge name, like (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 backoffice applications)
• sld_ch_partner_plugin, sld_ch_consumer_plugin (defines the specific functionality of a particular channel)