Introduction

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

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.

Syntax

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

Attributes

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" />

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.

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

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>

Attributes

name

This attribute is required.

• name of contract

class

This attribute is required.

• name of Java interface, abstract class or primitive class

XML Definition - IMPLEMENTATION

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

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>

Attributes

name

This attribute is required.

• name of the implementation

factory

This attribute is optional.

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

implements

This attribute is required.

• name of the contract

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

start

This attribute is optional.

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

stop

This attribute is optional.

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

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

Attributes

name

This tag is required.

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

contract

This tag is required.

• name of the contract

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

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

Attribute: contract

This attribute is required.

• name of the contract

XML Definition - INSTANCE

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

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>

Attributes

name

This attribute is optional.

• name of the component instance

with

This attribute is required.

• name of the implementation

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" />

global

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

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.

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

Attributes

requirement

This attribute is required.

• name of the property

of

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

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

with

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

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

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)

XML Definition - REPLACE

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

Attributes

name

This attribute is required.

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

with

This attribute is required.

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

delegate

This attribute is required.

• new name of an existing instance