Document Properties
Kbid27G261
Last Modified04-Feb-2020
Added to KB09-Oct-2015
Public AccessEveryone
StatusOnline
Doc TypeGuidelines, Concepts & Cookbooks
Product
  • ICM 7.6
  • ICM 7.7
  • ICM 7.8

Concept - Cartridge (valid to 7.8)


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

2 Reference

Cartridges and their structure and usage are extensively documented in the Intershop 7 Application Programming Guide distributed with Intershop 7 (see /docs/pdf/is7_dev_programming.pdf or in the Intershop Knowledge Base) and the Intershop Studio (see Help | Help Contents | Intershop 7 Application Programming Guide | Cartridge Development).

3 Cartridge Structure

3.1 Directory Structure

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

Source Project

Deployed

Contents

/javasource

/lib/<cartridge_name>.jar

Java code (such as business objects, persistent objects, provider classes, or pipelets)

/javasource/tests

/lib/tests

Java code (unit test cases)

/ivy.xml

/ivy.xml

The cartridge definition declaring, e.g., display name, version and build numbers, and dependencies.

/staticfiles/definition

/lib/<cartridge_name>.jar

JAXB XML schemas and configuration files used as a base to generate Java classes.

/staticfiles/cartridge/dbinit.properties

/dbinit.properties

Database initialization properties, see Concept - DBMigrate and DBInit (valid to 7.7)

/staticfiles/cartridge/migration*.properties

/migration*.properties

Migration steps executed by DBMigrate, see Concept - DBMigrate and DBInit (valid to 7.7)

/staticfiles/cartridge/config

/config

Configuration files, see Concept - Configuration (valid to 7.10.11)

/staticfiles/cartridge/components

/components

Component definitions, see Concept - Component Framework or Intershop 7 Application Programming Guide

/staticfiles/cartridge/extensions

/extensions

Extensions, see Concept - Extension Points or Intershop 7 Application Programming Guide

/staticfiles/cartridge/impex

/impex

Default configurations for import and export processes, see Concept - Impex Framework (valid to 7.8)

/staticfiles/cartridge/lib

/lib

Required libraries (usually jar files), but prefer to use gradle dependencies if possible

/staticfiles/cartridge/localizations

/localizations

Localization bundles, see Concept - Localization

/staticfiles/cartridge/pagelets

/pagelets

Pagelets provided by this cartridge, see Concept - CMS - Overview or Intershop 7 Application Programming Guide

/staticfiles/cartridge/pipelines

/pipelines

Pipelines, see Intershop 7 Application Programming Guide

/staticfiles/cartridge/queries

/queries

Queries, see Intershop 7 Application Programming Guide

/staticfiles/cartridge/static

/static

Static content like static HTML, images, and scripts (possibly locale-specific), see Intershop 7 Application Programming Guide

/staticfiles/cartridge/templates

/templates

ISML templates (possibly locale-specific), see Intershop 7 Application Programming Guide

/staticfiles/cartridge/webforms

/webforms

WebForms, see Intershop 7 Application Programming Guide

/staticfiles/cartridge/webservices

/webservices

Web Service Deployment Descriptors (wsdd)

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

Folder

Description

/system/impex

XML schema files for import and exports

/system/config/cartridges/<cartridge_name>.properties

Administrative properties of a cartridge, see Concept - Configuration (valid to 7.10.11)

/sites/*

Site specific files

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

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

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

4 Cartridges at Runtime

4.1 Cartridge Engine

ConceptCartridgesCartridgeEngine

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:

<IS_SHARE>/system/cartridges/cartridgelist.properties
cartridges = tools pf_cartridge pf_objectgraph pf_objectgraph_guice servletengine ...

The Order of Cartridges

The order of cartridges in this list is important: A cartridge can only depend on cartridges listed before itself. Also, pipelines and templates from cartridges further down in the list override/replace those from cartridges higher in the list in the context of a particular ApplicationType (see: Concept - Application Framework).

The deployment script/plugin of a cartridge must at least deploy its ivy.xml file into the cartridge folder (CARTRIDGES_DIR/<cartridge>/release). This is necessary because the cartridge engine tries to look up meta information for all entries of cartridgelist.properties when running the application server or DBInit. The CartridgeDeploymentPlugin Gradle plugin takes care of this task.

For more detailed information please refer to Concept - Gradle Assembly Tools and Cookbook - Gradle Assembly Tools (valid to 7.8).

4.1.1 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.xml of core cartridge
<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>

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

ConceptCartridgesCartridgeRuntimeStates

Please reduce the functionality inside of the cartridge class. We will remove this mechanism in future releases. Your global instances should be registered and instantiated via Dependency Injections and Object Graphs.

5 Cartridge Development

5.1 Architectural Layers and Cartridge Types

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

cartidge dependency hierarchy 7.8

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

Layer

Cartridge Type

Description

Typical Contents

Cartridge Naming

Java Package Naming

Example

Configuration LayerDemo CartridgeContains demo data for application, this data is optionalproduct xml files, images, demo content

demo_*

(deprecated naming ucm_*)

com.intershop.demo.*

demo_responsive

(ucm_demo)

 

Initialization Cartridge

Configures and initializes one or more applications in the database (like initial user accounts, organization structures, preferences etc.), this data is necessary to use the applications

import files, dbinit property files

init_*

com.intershop.init.*

init_operations

 

Application Suite Cartridge

Configures, instantiates and integrates multiple application types to form a complete business scenario

app and instance component files

as_*

com.intershop.appsuite.*

as_system

Application Layer

Application Cartridge

Provides user interfaces that can be composed to an application type

view pipelines, ISML templates, ...

app_*
(deprecated naming: sld*)

com.intershop.application.*

app_sf_webshop_smb

 

User Interface Cartridge

Provides a common user interface library which is used to develop application types based on the same technology

ISML templates, pipelines, JavaScript libraries, stylesheets, web forms, pagelets

ui_*

com.intershop.ui.*

ui_web_library

Business Layer

Business Cartridge

Provides a business API and/or an implementation for shared reusable business components

Java code, business objects and extensions, pipelets, EDL models, persistent objects, database scripts, queries

bc_*

com.intershop.component.*

bc_basket

 

Adapter Cartridge

Provides an implementation for a business API, which integrates external systems, like external search engines

Java code, jar files

ac_*

com.intershop.adapter.*

ac_payment_paypal

Platform Layer

Platform Cartridge

Implements shared platform frameworks that are needed across all architectural layers

Java code, EDL models, pipelets, Jar files

pf_*
_(deprecated without prefix)

com.intershop.beehive.* (deprecated)
com.intershop.platform.*

pf_objectgraph
pf_objectgraph_guice

 (none)Business Independent FunctionalityStandard gradle, maven project (Single Project)no prefixcom.intershop.common.*encryption

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

5.2 Cartridge Dependency Rules

Cartridge Dependency Rules

  1. Each cartridge has to explicitly declare direct dependencies to other cartridges.
  2. Circular dependencies between cartridges are forbidden.
  3. Dependencies to cartridges of same or lower architectural layer are allowed, except:
    1. Application Suite Cartridges should not depend on Initialization Cartridges.

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

 

Initialization Cartridge

Application Suite Cartridge

Application Cartridge

User Interface Cartridge

Adapter Cartridge

Business Cartridge

Platform Cartridge

Common Library

Initialization Cartridge

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

Application Suite Cartridge

(minus)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

Application Cartridge

(minus)

(minus)

(tick)

(tick)

(tick)

(tick)

(tick)

(tick)

User Interface Cartridge

(minus)

(minus)

(minus)

(tick)

(tick)

(tick)

(tick)

(tick)

Adapter Cartridge

(minus)

(minus)

(minus)

(minus)

(tick)

(tick)

(tick)

(tick)

Business Cartridge

(minus)

(minus)

(minus)

(minus)

(minus)

(tick)

(tick)

(tick)

Platform Cartridge

(minus)

(minus)

(minus)

(minus)

(minus)

(minus)

(tick)

(tick)
Common Library(minus)(minus)(minus)(minus)(minus)(minus)(minus)(minus)

As you may have noted, that common libraries must not depend on other common libraries. These components can use open source (MAVEN) available libraries. The platform is responsible to bring these libraries together.

This way it is possible to ensure that all Intershop Products (OMS, ICI, IS7) are able to use these components.

5.3 Naming Conventions

5.4 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)

5.5 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*

5.6 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

5.7 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

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

5.9 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 had 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)

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets