Introduction

The Application Framework of Intershop 7 is used to develop applications consisting of Java classes, pipelines, queries, webforms, and other Intershop-specific code artifacts.
The Application Framework distinguishes between:

• Application types - define the code base (pipelines, ISML templates, ...) and
• Applications - assign this functionality to a particular data set in the database and file system.

It is very important not to confuse these two terms.
The code artifacts as well as the application types themselves are deployed into the application server within cartridges.

References

Concepts:

• Concept - Cartridges (valid to 7.4)
• Concept - Business Objects
• Concept - Configuration (valid to 7.10.11)
• Concept - REST Framework

Cookbooks:

• Cookbook - Application Framework
• Cookbook - Business Objects

Glossary

Application Types

Cartridges, see Concept - Cartridges (valid to 7.4), are common file containers, that are deployed into the Intershop application server. They can contain simple files like images and properties as well as code artifacts, like:

• Java classes and jars
• Pipelines / Pipelets
• WebForms
• EDL files
• Queries
• ISML templates
• ...

An ApplicationType defines a set of cartridges composing the code base. The CartridgeListProvider is responsible for defining this cartridge set. All dependent cartridges of this set are added to the code base, too. The resulting set of cartridges is sorted by the global cartridge list provided by the application server startup: IS_SHARE/system/cartridges/cartridgelist.properties. The lookup order is reverse to the Java class path, which means that the code artifacts of cartridges on the right side override code artifacts of cartridges on the left side of the property value.

Application Suites

Intershop 7 is distributed with several application types that interact with each other.
E.g.: The B2C webshop renders products that are managed in the B2C back office.

Further, the B2C back office is able to internally call the B2C webshop.
E.g.: to render the B2C webshop in preview mode. In order to encapsulate particular application types the application suite layer is introduced, which configures particular application types and wires them together.

So, cartridges (e.g. as_sales_organization, as_system) defining and configuring several application types compose an application suite.

The following table lists the available Application Types defined in the Intershop Commerce Management B2C/B2X.

Code Sharing Between Application Types

There are two possibilities to share code in two application types.

Using Cartridge Dependencies

Cartridges define their dependencies to other cartridges (see Cartridge Meta Data). The internal code artifact lookup recursively processes the dependencies defined by the CartridgeListProvider.
E.g., the cartridges app_sf_webshop_b2c and app_sf_webshop_smb depend on the cartridge bc_user. That is why the code of cartridge bc_user is called by both application types intershop.B2CWebShop and intershop.SMBWebShop:

The code in the bc_user cartridge simply uses the named relation UserBORepository to access the business data of user features for the current application. The creator of the application object needs to make sure that the corresponding relation is created, too.

Inheritance of Cartridge Lists

Another important possibility of code sharing is the inheritance of the existing cartridge lists. In this case an application type is also assigned to all cartridges of an existing application type. The following figure describes how it works:

In this case the application type customer.B2CWebShop is derived from application type intershop.B2CWebShop. This means that the webshop of the customer inherits all the functionality of the standard webshop of Intershop and may overwrite or extend the functionality with its own cartridge customer_sld_ch_b2c_app. This structure results in the following cartridge lists:

1. cartridgelist.properties: cartridges= ... sld_ch_b2c_base sld_ch_b2c_cm sld_ch_b2c_app customer_sld_ch_b2c_app
2. intershop.B2CWebShop: sld_ch_b2c_app -> sld_ch_b2c_cm -> sld_ch_b2c_base
3. customer.B2CWebShop: customer_sld_ch_b2c_app -> sld_ch_b2c_app -> sld_ch_b2c_cm -> sld_ch_b2c_base

ApplicationTypes are registered at the AppEngine and will be instantiated during the startup phase of the application server. An ApplicationType possesses an identifier for references within the code as well as a name and a description for visualization in different applications.

Applications

An application determines three things that are required to execute a code artifact within the Intershop application server:

• The application type defining the functionality (code base);
• The data set (the number of domains) the functionality works on;
• The session context (the site containing the session objects).

The ApplicationContext is the static execution context of an application. This results in the following diagram:

The following things are possible as a result of this design:

• Application Switch: Each site can access several applications. That is why it is possible to switch between different applications within one user session.

  Note

  Both applications need to be session-compatible because objects are shared between the applications in the session dictionary.

• Code Reuse: Code artifacts that need to be used by different applications can be reused by deploying them in separate cartridges and assigning them to the corresponding application types. Indirect dependent cartridges of assigned cartridges are automatically assigned, too.
• Data Sharing: Data can be shared between applications (e.g. Product Data in webshop and back office) by assigning the same Domain to different applications.

Domains

The data in the database and file system are assigned to data containers or repositories internally called domain. Domains are persistent objects that are stored in the database. Each domain possesses a system-wide unique name as well as a UUID. Database objects belonging to a domain use foreign keys or at least a column for storing the UUID of the domain. The data in the file system is stored in a particular directory: IS_SHARE/sites/<site>, IS_SHARE/sites/<parentsite>/units/<unit>.

There are two types of Domains: Sites (type code 3) and Units (type code 1). Units are mere data containers. They contain database data of different types and file system content, like images. In general, sites are web sites. They contain the session objects within the application server. Further, the sites are assigned to a parent site and contain an arbitrary number of units.

Relations Between Applications, Application Types and Domains

Applications and domains are persistent objects that are created during the DBInit process or at runtime of the application server (e.g., during creation of a sales organization). There are three tight relations between an application and domains:

• The method Application.getDomain():Domain returns the owning domain.
• The method Application.getSite():Domain returns the site of the application. A user can switch between applications belonging to the same site.
• The methods Application.getRelatedDomains(String):List<Domain> and Application.getRelatedDomain(String):Domain return one or more domains with a defined role within the application. See:

The named relations between applications and domains are introduced to support different business scenarios. The name of the relation represents the role of the domain within the application. From this it follows that one domain may have the same or different roles in several applications (data sharing). Furthermore, one named relation references at least one domain. This is the usual case. It is also possible to assign more than one domain to a relation. In this case they are ordered by a position.

The application types are created during startup of the application server. The applications determine their functionality by referencing the application type.

There are business scenarios requiring different relations between the code and the data of a particular type. The following combinations are possible for two applications:

1. Accessing the same data with the same code -> same domain relations with same application type
2. Accessing the same data with different code -> same domain relations with different application type
3. Accessing different data with same code -> different domain relations with same application type
4. Accessing different data with different code -> different domain relations with different application type

The following figure shows the data sharing in the back office application. The B2C back office as well as the enterprise back office use separate domains ("DefaultRepository") to store their business objects like products, prices and so on. Both applications share the same Organizations repository:

The Execution Context of an Application

The Intershop code artifacts are executed in the context of an application providing the list of cartridges for the lookup of code artifacts. The following communication diagram describes steps for the creation of an application context:

The application calls the ApplicationContextFactory object to create the minimum application context. Afterwards, the ApplicationContextFactory calls each extension implementing the extension point com.intershop.beehive.core.capi.domain.ApplicationContextListener-ApplicationContextFactory to add their feature-specific objects. For instance, the class ApplicationBOApplicationContextListener of cartridge bc_application is responsible for:

• Creating and adding the BusinessObjectContext
• Creating and adding the current ApplicationBO

to the ApplicationContext. As a result of this, all applications of an application type which references the cartridge bc_application create AppContext objects with the current ApplicationBO as well as BusinessObjectContext.

Example: ApplicationContext Creation and Release

Application application = ...;
try(ApplicationContext applicationContext = application.forceApplicationContext())
{
    // code, that executes Intershop code artifacts or business objects
    ...
}

The Lifecycles of Applications, Application Types, and ApplicationContexts

The lifecyles of applications, application types and application contexts are different. This means that the ApplicationContext objects are created for each time an application is executed, e.g., during a single web request. The application types are created during the startup of the application server and exist as long as the application server runs. Application objects are persistent objects that can be created and removed at runtime and their dynamic states can survive a restart of an application server.

There is an interface ApplicationLifecycleListener that can be used to create additional persistent objects during application creation (e.g., domains for particular business features) or clean up the same data during the removal of an application.

Application Configuration

The configuration framework supports the configuration with the scope application. The application also provides a method to get its configuration directly:

Application application = ...;
Configuration configuration = application.getConfiguration();
String value = configuration.getString("intershop.aPropertyKey");

Lookup Order of Configuration Values

The configuration framework supports application preferences similar to domain preferences. The preferences are retrieved from the configuration system.
Application-specific configurations are built from the configurations of the site, the application type and the related cartridges. The corresponding files are located in IS_SHARE/system/config/<apps|cartridges|domains>.

See also Concept - Configuration.

URL Handling

Normally, applications are web applications rendering HTML web pages for the browser of business users. The browser communicates with the web server containing the WebAdapter, which is responsible (among other things) for mapping the web requests to particular servlets of the application server in a given application server group. This section describes the different types of URLs related to applications.

Pipeline URLs

Pipelines with ending ISML Interaction Nodes are used to build HTML pages that are delivered to the browser of business users. They consist of the following parts:
<protocol>://<host>:<port>/<prefix>/web/<server group>/<site>/<locale>/<application>/<currency>/<pipeline>-<start node>.

<protocol>: "http" or "https"
<host>: The host of the web server
<port>: The port of the web server
<prefix>: Value of the system-wide configuration " intershop.urlmapping.urlPrefix" in file IS_SHARE/system/config/cluster/appserver.properties. Default: /INTERSHOP
" web": Pipelines are executed by the RequestHandlerServlet, which is mapped to the string "web" in the URL.
<server group>: The Intershop cluster can consist of several application servers. These application servers can be assigned to a group, e.g. WFS, BOS, JOB.
<site>: The name of site, e.g. SMC.
<locale>: The identifier of the locale. A "-" references the default locale of application, e.g., "en_US".
<application>: The URL identifier of the application. A "-" references the default application of the site, e.g., "webshop".
<currency>: The code of the current currency. A "-" references the default currency of the application.
<pipeline>: The name of the pipeline which should be executed.
<start node>: The name of the start node within the pipeline to be called.

Static Content URLs

CSS, JavaScript files, images and other static content is delivered through the ResourceServlet. The corresponding URL looks like this:
<protocol>://<host>:<port>/<prefix>/static/<server group>/<site>/<application>/<unit>/<locale>/<path>.

<protocol>: "http" or "https"
<host>: The host of the web server
<port>: The port of the web server
<prefix>: Value of the system-wide configuration " intershop.urlmapping.urlPrefix" in file IS_SHARE/system/config/cluster/appserver.properties. Default: /INTERSHOP
" static": Static content is delivered through the ResourceServlet which is mapped to the string "static" in the URL.
<server group>: The Intershop cluster can consist of several application servers. These application servers can be assigned to a group, e.g., WFS, BOS, JOB.
<site>: The name of site, e.g., "inSPIRED-inTRONICS-Site".
<application>: The URL identifier of application. A "-" references the default application of site, e.g., "webshop".
<unit>: The name of the unit, e.g., "inSPIRED-inTRONICS". A "-" references the site itself.
<locale>: The identifier of a locale. A "-" references the default locale of application, e.g., "en_US".
<path>: The relative path to the static file.

The given relative path is used by the lookup strategy for the requested resource, which works in this way:
Search for resource in static content directory of:

1. the unit landing pages (if servlet path info specifies a unit, otherwise go to step 4);
2. the unit (if servlet path info specifies a unit, otherwise go to step 4);
3. the site above the given unit;
4. application below the site (if servlet path specifies an application URL identifier);
5. the site;
6. all cartridges assigned to the application.

Within each of the above-listed steps there is an additional fallback strategy depending on the locale:

1. directory of specified locale (e.g., de_DE);
2. directory of the language of the specified locale (e.g., de);
3. directory of the lead locale (e.g., en_US);
4. directory of the language of the lead locale (e.g., en);
5. directory default.

REST URLs

Some applications provide a REST API. Corresponding URLs are described in the Concept - REST Framework.

URL Rewriting

The rule sets of URL rewriting functionality are application-specific. This means that there is a possibility to specify combined rule sets defined in the selected cartridges of an application. The mappings of host names to particular sites with according applications are made in the global configuration file: IS_SHARE/system/config/cluster/urlrewrite.properties. This file contains further information about the usage of the feature.

The Business API of the Application Framework

The standard applications of Intershop 7 use business objects, see Concept - Business Objects, to implement the business logic. The application framework provides two central APIs to integrate these business objects.

ApplicationBO

The business objects of an application can be accessed via the ApplicationBO, which is automatically created during application context creation as long as the application type references the cartridge bc_application. The pipelet GetApplicationBO is used to access this object within a pipeline. Internally, each application context also creates a business object context forcing the correct business object extension for particular application.

RepositoryBO

The RepositoryBO provides a business API for managing business objects of one or more types. For instance, the RepositoryBO inSPIRED-inTRONICS contains products, catalogs, promotions and other business objects. It is introduced to reuse business features in different business scenarios. Internally, the implementation AbstractDomainRepositoryBOExtensionFactory of the RepositoryBO maps to exactly one Domain.

The repositories of the business objects are accessed using the Java method ApplicationBO.getRepository(String extensionID). This method internally searches for the extension factory of type AbstractDomainRepositoryBOExtensionFactory with a given extension identifier. The factory found implements the method getRelationName() to map the extension identifier to the name of an ApplicationDomainRelation. Normally, it is the same. The resulting domain or domains contain(s) the corresponding business data. The following code snippet can be used to look for a product with a given identifier:

ApplicationBO applicationBO = ...;
ProductBORepository repository = applicationBO.getRepository(ProductBORepository.EXTENSION_ID);
ProductBO promotionBO = repository.getProductBOByID(id);

The implementation of the product repository simply needs to derive from AbstractDomainRepositoryBOExtensionFactory. This pattern makes sure that every business feature is accessed in the same way, which significantly simplifies the business API of an application. The following figure shows the relations between the ApplicationBO, RepositoryBO, Domain as well as particular business object repository:

In this example there are two business object contexts that are created for each application. All business objects use this context to determine their extensions. The implementation of the business objects use the persistent layer (ORM engine) where its objects are shared through all applications.

RepositoryBO vs. Repository(PO)