Document Properties
Kbid25L733
Last Modified12-Jul-2016
Added to KB17-Apr-2014
Public AccessEveryone
StatusOnline
Doc TypeReferences
Product
  • ICM 7.6
  • ICM 7.7
  • ICM 7.8
  • ICM 7.9
  • ICM 7.10

Reference - Component Framework

1 Introduction

The Component Framework uses XML declarations of contracts, implementations and instances. Related documents are the concept and cookbook of the component framework.

2 XML Definition - COMPONENTS

The <COMPONENTS> tag is the body tag for component definitions.
The XML declaration, encoding and namespace are added automatically when creating a new component definition.

2.1 Syntax

<?xml version="1.0" encoding="UTF-8"?>
<components xmlns="http://www.intershop.de/component/2010"/>

2.2 Attributes

2.2.1 scope

This attribute is optional.
The attribute scope defines a default scope to instantiate contained instances. Currently available are app and global.

<components scope="global|app" />

Note

If no scope is defined within the instance definition, the component framework applies the default value global.

3 XML Definition - CONTRACT

Contracts define the API for a component.
Defining contracts is as "simple" as writing JAVA interfaces. Thereby, it is possible to split the interfaces to requirement interfaces and provided interfaces. For example, usually getter and setter are put together in one interface to configure the instance.
You can remove these types of methods from the provided interface.

Note

The provided interface should declare what the instance is doing. It should not declare what is needed to fulfill this functionality.

The <CONTRACT> tag allows to define a component contract.

Note

Currently, only JAVA interfaces are supported.

3.1 Syntax

  1. To create a contract, firstly create a interface definition.
  2. Define the contract.
<?xml version="1.0" encoding="UTF-8"?>
<components xmlns="http://www.intershop.de/component/2010">
  <contract name="[name]" class="[classname]"/>
</components>

3.2 Attributes

3.2.1 name

This attribute is required.

  • name of contract

3.2.2 class

This attribute is required.

  • name of Java interface, abstract class or primitive class

4 XML Definition - IMPLEMENTATION

The <IMPLEMENTATION> tag allows to define an implementation of a contract.

4.1 Syntax

<?xml version="1.0" encoding="UTF-8"?>
<components xmlns="http://www.intershop.de/component/2010">
  <implementation name="[name]" implements="[contract-name]" factory="[factory-name]" class="[class-name]" start="nameOfStartMethod" stop="nameOfStopMethod">
    <!-- multiple implements can be listed -->
    <implements contract="[contract-name]" />
    <requires name="[property-name]" contract="[contract-name]" cardinality="[1..1|0..1|1..n|0..n]" />
  </implementation>
</components>

4.2 Attributes

4.2.1 name

This attribute is required.

  • name of the implementation

4.2.2 factory

This attribute is optional.

  • name or class name of the component factory (default: JavaBeanFactory)

4.2.3 implements

This attribute is required.

  • name of the contract

4.2.4 class

This attribute is optional when using a factory which already have the class attribute. When using the JavaBeanFactory the attribute is required.

  • name of the class which implements the contract

4.2.5 start

This attribute is optional.

  • name of the method to start the component, start is called after all requirements are fulfilled

4.2.6 stop

This attribute is optional.

  • name of the method to stop the component, stop is called if the context is stopped

5 XML Definition - REQUIRES

The <REQUIRES> tag allows to define the requirements of the implementation.
The <REQUIRES> tag is a child element of the <IMPLEMENTATION> tag. For a syntax example see syntax of <IMPLEMENTATION>.

5.1 Attributes

5.1.1 name

This tag is required.

  • name of the property (used by JavaBeanFactory to define the names of setter/adder (with capital first letter))

5.1.2 contract

This tag is required.

  • name of the contract

5.1.3 cardinality

This tag is optional (default: 1..1).

  • cardinality of the property (used by JavaBeanFactory to define if a setter or adder is used)
    • 1..1 required
    • 0..1 optional
    • 1..n required many
    • 0..n optional many

6 XML Definition - IMPLEMENTS

The <IMPLEMENTS> tag allows to define the names of additional implemented contracts (extension to the attribute implements of <IMPLEMENTATION> tag).
The <IMPLEMENTS> tag is a child element of the <IMPLEMENTATION> tag. For a syntax example see syntax of <IMPLEMENTATION>.

6.1 Attribute: contract

This attribute is required.

  • name of the contract

7 XML Definition - INSTANCE

The <INSTANCE> tag allows to define a component configuration for a component instance.

7.1 Syntax

<?xml version="1.0" encoding="UTF-8"?>
<components xmlns="http://www.intershop.de/component/2010">

  <!-- an instance for an implementation without requirements -->
  <instance name="[name]" with="[implementation-name]" />

  <!-- an instance for an implementation with directly fulfilled requirements -->
  <instance name="[name]" with="[implementation-name]">
    <!-- fulfill the requirement with a constant -->
    <fulfill requirement="[property-name]" value="[constant]"/>
    <!-- fulfill the requirement with another instance -->
    <fulfill requirement="[property-name]" with="[instance-name]" />
  </instance>

  <!-- outside of instance tag -->
  <fulfill requirement="[property-name]" of="[instance-name]" with="[instance-name]" />
  <fulfill requirement="[property-name]" of="[instance-name]" value="[constant]" />

  <!-- instance inside of fulfill tag -->
  <instance name="[name]" with="[implementation-name]">
    <!-- with attribute of fulfill tag is implicit - filled with inner instance element(s) -->
    <fulfill requirement="[property-name]">
      <!-- name of instance is optional - anonymous instances are allowed here -->
      <instance with="[implementation-name] requirement="[property-name]" with="[instance-name]" />
      </instance>
      <!-- recursive declaration of instances and fulfillment -->
      <instance with="[implementation-name]">
        <fulfill requirement="[property-name]">
          <instance with="[implementation-name]" />
        </fulfill>
      </instance>
    </fulfill>
  </instance>

  <!-- replace an instance with a new one, the old is available via the name - value of delegate attribute -->
  <replace name="[name]" with="[implementation-name]" delegate="[renamed-instance-name]">
    <fulfill requirement="[delegate-property-name]" with="[renamed-instance-name]" />
    <!-- other fulfill tags ... -->
  </replace>

</components>

7.2 Attributes

7.2.1 name

This attribute is optional.

  • name of the component instance

Note

If you use <INSTANCE> tag as a child element of <COMPONENTS> tag, the name attribute is required for wiring.
It is recommended to use anonymous instances if you do not need the instance twice for wiring.

7.2.2 with

This attribute is required.

  • name of the implementation

7.2.3 scope

This attribute is optional.
The attribute scope defines the context in which an instance is created. So it is possible to create different instances for different applications.

<instance name="[aName]" with="[anImplementation]" scope="global|app" />

Note

If no scope is defined within the instance definition, the component framework applies the value set in the components tag. If the components tag does not have a scope the default value is global.

7.2.3.1 global

A single instance of the implementation is created. The instance is available from all applications.

7.2.3.2 app

The framework creates an instance of the implementation for each application. An instance is created exclusively for the current application and cannot be accessed by any other application.

8 XML Definition - FULFILL

The <FULFILL> tag allows to define the wiring or simple configuration of the component instance.
The <FULFILL> tag can be used both as a child element of <INSTANCE> tag and outside as a child element of the <COMPONENTS> tag.
For syntax examples see syntax of <INSTANCE> .

8.1 Attributes

8.1.1 requirement

This attribute is required.

  • name of the property

8.1.2 of

One attribute out of with, of or value is mandatory.

  • name of the configuration key (the value is retrieved from the configuration framework)

8.1.3 with

One attribute out of with, of or value is mandatory.

  • name of the instance (the value is fulfilled with an instance)

8.1.4 value

One attribute out of with, of or value is mandatory.

  • constant definition (constants can be of type String, Integer, Boolean, Long, BigDecimal, Double, Float, Enums and any class which has a constructor with a string parameter)

9 XML Definition - REPLACE

The <REPLACE> tag allows to define replacement of an existing instance.
For a syntax example see Syntax of <INSTANCE>.

9.1 Attributes

9.1.1 name

This attribute is required.

  • name of the component instance (like <INSTANCE> tag)

9.1.2 with

This attribute is required.

  • name of the implementation (like <INSTANCE> tag)

9.1.3 delegate

This attribute is required.

  • new name of an existing instance

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