OpenCCM - Writing Component Assembly Descriptors

Table of Contents

  1. Component Assembly Descriptor (CAD)
  2. Root Element
    1. <componentassembly> Element
  3. Component Files Elements
    1. <componentfiles> Element
    2. <componentfile> Element
  4. Partitioning Elements
    1. <partitioning> Element
    2. <homeplacement> Element
    3. <homeproperties> Element
    4. <processcollocation> Element
    5. <hostcollocation> Element
    6. <executableplacement> Element
    7. <componentplacement> Element
    8. <existinghome> Element
    9. <invocation> Element
    10. <destination> Element
    11. <node> Element
    12. <componentinstantiation> Element
    13. <componentproperties> Element
    14. <registercomponent> Element
    15. <componentfileref> Element
    16. <componentimplref> Element
  5. Registration Elements
    1. <registerwithnaming> Element
    2. <registerwithhomefinder> Element
    3. <registerwithtrader> Element
  6. Trader Elements
    1. <traderexport> Element
    2. <traderservicetypename> Element
    3. <traderproperties> Element
    4. <traderproperty> Element
    5. <traderpropertyvalue> Element
    6. <traderquery> Element
    7. <traderpolicy> Element
  7. Connections Elements
    1. <connections> Element
    2. <connectinterface> Element
    3. <usesport> Element
    4. <providesport> Element
    5. <componentsupportedinterface> Element
    6. <componentinstantiationref> Element
    7. <existinginterface> Element
    8. <homeinterface> Element
    9. <homeplacementref> Element
    10. <connectevent> Element
    11. <consumesport> Element
    12. <emitsport> Element
    13. <publishesport> Element
    14. <connecthomes> Element
    15. <proxyhome> Element
    16. <destinationhome> Element
    17. <findby> Element
    18. <namingservice> Element
    19. <stringifiedobjectref> Element
    20. <homefinder> Element
  8. Identifier Elements
    1. <consumesidentifier> Element
    2. <emitsidentifier> Element
    3. <providesidentifier> Element
    4. <publishesidentifier> Element
    5. <usesidentifier> Element
  9. Common Elements
    1. <codebase> Element
    2. <description> Element
    3. <extension> Element
    4. <fileinarchive> Element
    5. <impltype> Element
    6. <link> Element
    7. <usagename> Element

Component Assembly Descriptor (CAD)

The goal of this document is to provide information on the way to use the Component Assembly Descriptor (CAD) to describe CCM applications. Two kinds of information will be provided.

Firstly, formal information extracted from the OMG CCM specification describes all the elements of the CAD XML DTD. These elements are illustrated by various examples.

The second kind of information deals with the OpenCCM deployment behavior and implementation status for each element. The goal of this information is to explain how the OpenCCM deployment process uses component assembly descriptors to build applications. This also brings information on the current implementation status.

Root Element

<componentassembly> Element

componentassembly
Description The componentassembly element is the root element of the Component Assembly Descriptor (CAD).
XML DTD <!ELEMENT componentassembly
  (description?
  ,componentfiles
  ,partitioning
  ,connections?
  ,extension*)>

<!ATTLIST componentassembly
  id ID #REQUIRED
  derivedfrom CDATA #IMPLIED>
Parent None.
Attributes

  • id ID:
    id is an UUID that uniquely identifies the assembly.

  • derivedfrom CDATA:
    The derivedfrom attribute is used to point to an assembly from which this assembly was derived. The derivedfrom attribute contains the id of the source assembly.

Children Elements

  • description :
    The description child is a text describing the assembly.

  • componentfiles :
    The componentfiles child is used to refer all the component files required for this assembly. This element cannot be avoid because it is needed for example to retrieve the archive of components.

  • partitioning :
    The partitioning child is used to describe how and where homes and components have to be deploy. This element cannot be avoid a component assembly must define a partition.

  • connections :
    The connections child is used to describe all the connections to establish between components. This element can be avoid, an assembly can have none connection.

  • extension :
    The extension child is used to describe vendor specific extensions.

Example <componentassembly id="ZZZ123">
  <description> Assembly example </description>
  <componentfiles>
    ...
  </componentfiles>

  <partitioning>
    ...
  </partitioning>

  <connections>
    ...
  </connections>
</componentassembly>
OpenCCM Deployment Support
Status Not fully supported:
The derivedfrom attribute is not supported.
Implementation Behavior The componentassembly processing is split in three steps. In a first time, all the component files required are read. Then in a second time, all the components are instantiated. In the last time, the component connections are established. This scheduling ensures that components are created and can be used to establish connections.
Finally, all the components are configure completed following the order in which they appear in the component assembly descriptor.
Lets note that the id attribute is used to register the assembly object in the CosNaming Service.

Component Files Elements

<componentfiles> Element

componentfiles
Description The componentfiles element is used to list all of the component files that are used in the assembly. At least one component file must be specified. Each component file is uniquely identified for reference elsewhere in the descriptor. Multiple component instances may refer to a single component file.
XML DTD <!ELEMENT componentfiles
  (componentfile+) >
Parent componentassembly
Attributes None.
Children Elements

  • componentfile :
    componentfile children are used to refer all the component files required by the assembly.

Example <componentfiles id="ZZZ123">
  <componentfile id="A">
  ....
  </componentfile>
  <componentfile id="B">
  ....
  </componentfile>
</componentfiles>
OpenCCM Deployment Support
Status Fully supported.
Implementation Behavior The componentfiles processing just traverses all the componentfile elements to require their processing.

<componentfile> Element

componentfile
Description The componentfile element refers to a component software descriptor containing information regarding a component and home implementation. componentfile are referenced by homeplacement elements.
XML DTD <!ELEMENT componentfile
  (fileinarchive
  |codebase
  |link
  )>

<!ATTLIST componentfile
  id ID #REQUIRED
  type CDATA #IMPLIED>
Parent componentfiles
Attributes

  • id ID:
    The id attribute must uniquely identify the componentfile element with in the descriptor. It will be used by homeplacement elements to found the component binary required to deploy homes.

  • type CDATA:
    The optional type attribute specifies the type of component file in a string format. If unspecified, then the file is assumed to be CORBA component. An example use of the type attribute would be to specify an EJB component file.

Children Elements

  • fileinarchive :
    The fileinarchive element is used to retrieve the file to read in an archive.
    It must be a relative path in the specified archive.

  • codebase :
    The codebase element is used to specify a resource.

  • link :
    The link element is used to specify the link to find the component file.

Examples <componentfile id="A">
  <fileinarchive name="ca.csd">
</componentfile>
or
<componentfile id="B">
  <fileinarchive name="cb.csd">
    <link href="ftp://www.xyz.com/cb.car">
  </fileinarchive>
</componentfile>
or
<componentfile id="C">
  <link href="ftp://www.xyz.com/cc.csd">
</componentfile>
OpenCCM Deployment Support
Status Not fully supported:
Children codebase and link are not supported.
The type attribute is not tested. Only CORBA components are supported.
Implementation Behavior The componentfile processing just reads the file precised in the fileinarchive element. The XML tree resulting is stored in a internal table for later uses.

Partitioning Elements

<partitioning> Element

partitioning
Description The partitioning specifies a deployment pattern of homes and components to generic processes and hosts. The pattern is expressed via collocation constraints. A particular usage of a component is always relative to a component home. Uses of component homes are recognized in the assembly as home placements. A home placement, and component instantiations relative to a home, may be collocated with other home placements and component instantiations in a process. Process and home placements may be collocated within a logical host. A home placement that is not part of a process or a hostcollocation may be deployed without constraints.
XML DTD <!ELEMENT partitioning
  ( homeplacement
  | executableplacement
  | processcollocation
  | hostcollocation
  | componentplacement
  | extension
  )* >
Parent componentassembly
Attributes None.
Children Elements
Example <partitioning>
  <homeplacement id="AaHome" >
    ...
  </homeplacement>

  <processcollocation cardinality="*" >
    ...
  </processcollocation>

  <hostcollocation cardinality="*" >
    ...
  </hostcollocation>

</partitioning>
OpenCCM Deployment Support
Status Not fully supported:
homeplacement and processcollocation children are well-supported.
executableplacement children are not supported.
Implementation Behavior The partitioning processing traverses all the children elements to require their deployment.

<homeplacement> Element

homeplacement
Description The homeplacement element describes a particular deployment of a component home. The homeplacement element may be a direct child of partitioning element which states that it has no collocation constraints; or it may be a child element of the hostcollocation or processcollocation elements that state specific host or process collocation constraints.
XML DTD <!ELEMENT homeplacement
  ( usagename?
  , componentfileref
  , componentimplref?
  , homeproperties?
  , componentproperties?
  , registerwithhomefinder*
  , registerwithnaming*
  , registerwithtrader*
  , componentinstantiation*
  , destination?
  , extension*
  ) >

<!ATTLIST homeplacement
  id ID #REQUIRED
  cardinality CDATA "1" >
Parents partitioning
processcollocation
hostcollocation
Attributes
  • id ID:
    The required id attribute is used to uniquely identify the homeplacement in a storage way. This identifier could be used for later homeinterface connections.
  • cardinality CDATA:
    The cardinality attribute specifies how many instances of this homeplacement may be deployed.
Children Elements

  • usagename :
    Human friendly name used to refer the homeplacement element.

  • componentfileref :
    Used to retrieve the component file needed to deploy and instantiate the home. This one will be used to retrieve information such as the component archive path.

  • componentimplref :
    Used to refer the component implementation to instantiate.

  • homeproperties :
    Used to specify properties to set on the home.

  • componentproperties :
    Used to specify default properties for all the componentinstantiation children.

  • registerwithhomefinder :
    Used to describe a registration into the ComponentHomeFinder service.
    A home can be registered multiple times in this service with different names.

  • registerwithnaming :
    Used to describe a registration into the CosNaming service.
    A home can be registered multiple times in this service with different names.

  • registerwithtrader :
    Used to describe a registration into the CosTrading service.
    A home can be registered multiple times in this service.

  • componentinstantiation :
    Used to describe a component instantiation.
    Several component instantiations could be done with the same home.

  • destination :
    Used to define the target location where the home will be deployed.
    It can be avoided when the homeplacement element is part of a hostcollocation or processcollocation element.

  • extension :
    Used to describe vendor specific extensions.

Example <homeplacement id="ServerHome" cardinality="1">
  <componentfileref idref="Server"/>
  <componentimplref idref="ServerImpl"/>
  <registerwithhomefinder name="ServerHome"/>
  <registerwithnaming name="ServerHome"/>
  <componentinstantiation id="Server">
    ...
  </componentinstantiation>
  <destination> NODE:MyNode </destination>
</homeplacement>
OpenCCM Deployment Support
Status Not fully supported:
The cardinality attribute is not used.
componentproperties and homeproperties children elements are not applied to configure homes and components.
Implementation Behavior The homeplacement processing is quite complex.
According to the target destination location, it is in charge to download the required archive on the target host using the associated ComponentInstallation instance.
Then it is in charge to retrieve a ComponentServer instance, e.g. created via a ServerActivator instance, to create a Container instance on it, and to install the home on it.
It uses the XML descriptor associated to the component file element in order to retrieve the archive path and the home entry point.
The registration processing are delegated to registerwithhomefinder , registerwithnaming and registerwithtrader children elements.
The component instantiations are delegated to componentinstantiation children elements.
Remarks: The downloading of archives must be down by another tool in the CCM architecture. So the download code will be removed later.

<homeproperties> Element

homeproperties
Description The homeproperties element specifies a property file for a home. The properties are used to configure the home after its instantiation. The property file may be specified by either a fileinarchive or a codebase child element.
XML DTD <!ELEMENT homeproperties
  ( fileinarchive
  | codebase
  ) >
Parent homeplacement
Attributes None.
Children Elements
Example <homeproperties>
  <fileinarchive name="META-INF/homeProperties.cpf" />
<homeproperties>
OpenCCM Deployment Support
Status Not supported.
Implementation Behavior The homeproperties does not have any implementation.
It is simply used to store the information that will be used by the home configuration processing.

<processcollocation> Element

processcollocation
Description The processcollocation element specifies a group of homes and associated component instantiations that are to be deployed to a single process.
XML DTD <!ELEMENT processcollocation
  ( usagename?
  , impltype?
  , ( homeplacement
    | extension
    )+>
  , destination?
  ) >

<!ATTLIST processcollocation
  id ID #IMPLIED
  cardinality CDATA "1" >
Parents partitioning
hostcollocation
Attributes
  • id ID:
    The id attribute uniquely identifies this process collocation in the component assembly file.
  • cardinality CDATA:
    The cardinality attribute specifies how many instances of this process collocation may be deployed.
Children Elements

  • usagename :
    Identifies by a name the processcollocation.

  • impltype :
    If impltype is specified, then each of the component instances must have implementations supporting the implementation type, else the implementation type of components depends of the target deployment platform implementation type.

  • homeplacement :
    Used to describe a home and its component instantiations. At least one homeplacement must be specified.

  • extension :
    Used to describe vendor specific extensions.

  • destination :
    Used to describe the destination host on which the process will run. This child can be avoid if the processcollocation is part of a hostcollocation.

Example <processcollocation cardinality="*">
  <usagename> Example process collocation </usagename>
  <impltype language="JAVA"/><!--optional-->
  <homeplacement id="BbHome">
    . . .
  </homeplacement>

  <homeplacement id="CcHome">
    . . .
  </homeplacement>

</processcollocation>
OpenCCM Deployment Support
Status Not fully supported:
All the children parts of the processcollocation are executed on the same host but not in a unique process.
Children usagename and impltype are not supported.
The cardinality and id attributes are not used too.
Implementation Behavior The processcollocation processing traverses all the homeplacement children and requires their deployment on a specified destination.

<hostcollocation> Element

hostcollocation
Description The hostcollocation element specifies a group of homes and associated component instantiations that are to be deployed together to a single host.
XML DTD <!ELEMENT hostcollocation
  ( usagename?
  , impltype?
  , ( homeplacement
    | executableplacement
    | processcollocation
    | extension
    )+
  , destination?
  ) >

<!ATTLIST hostcollocation
  id ID #IMPLIED
  cardinality CDATA "1" >
Parent partitioning
Attributes
  • id ID:
    The id attribute uniquely identifies this hostcollocation in the component assembly file.
  • cardinality CDATA:
    The cardinality attribute specifies how many instances of this hostcollocation may be deployed possible values are 0 or 1.
Children Elements
Example <hostcollocation cardinality="1">
  <usagename> Example of host collocation </usagename>
  <impltype language="JAVA"/><!--optional-->
  <processcollocation id="ProcessCol1">
      . . .
  </processcollocation>
  <executableplacement id="ExecutablePlac1">
      . . .
  </executableplacement>
  <homeplacement id="CcHome">
    . . .
  </homeplacement>
</hostcollocation>

OpenCCM Deployment Support
Status Not fully supported:
The cardinality attribute is not used to instantiate the hostcollocation, i.e. only one instance is build.
The child impltype is not used to check the implementation type of each children.
executableplacement and processcollocation children are not processed.
Implementation Behavior The hostcollocation processing does not support all the functionalities only homeplacement are processed. In that case the destination child must be filled to specify the destination host. This destination will overlay imbricated homeplacement or processcollocation destination.

<executableplacement> Element

executableplacement
Description The executableplacement element describes the deployment of an executable. The executableplacement element may be a direct child of the partitioning element, which states that it has no collocation constraints; or it may be a child element of the hostcollocation element.
XML DTD <!ELEMENT processcollocation
  ( usagename?
  , componentfileref
  , componentimplref
  , invocation?
  , destination?
  , extension*
  ) >

<!ATTLIST executableplacement
  id ID #IMPLIED
  cardinality CDATA "1" >
Parents partitioning
hostcollocation
Attributes
  • id ID:
    The id attribute uniquely identifies this executable placement in the component assembly file.
  • cardinality CDATA:
    The cardinality attribute specifies how many instances of this executable placement may be deployed.
Children Elements

  • usagename :
    Identifies by a name the executableplacement.

  • componentfileref :
    The componentfileref element specifies the component file.

  • componentimplref :
    The componentimplref element refers to a specific implementation in the softpkg descriptor. Let's note that the implementation referred to by componentimplref must have a code type of "Executable".

  • invocation :
    The invocation element specifies any arguments with which the executable should be invoked.

  • destination :
    The destination element is used to record where the executable placement is to be deployed.

  • extension :
    Used to describe vendor specific extensions.

Example <executableplacement cardinality="1">
  <usagename> Executableplacement1 </usagename>
  <componentfileref idref="META-INF/ComponentExample.csd">
  <componentimplref idref="componentImplem1">
  <invocation>
  . . .
  </invocation>
  <destination>
  . . .
  </destination>
</executableplacement>
OpenCCM Deployment Support
Status Not supported.
Implementation Behavior None.

<componentplacement> Element

componentplacement
Description The componentplacement element specifies components instantiations on an already existing home. The way to find the home reference is described by an existinghomeelement. Component instantiations are described with componentinstantiation elements. Be careful this tag is an OpenCCM extension of the CCM specification.
XML DTD <!ELEMENT componentplacement
  ( usagename?
  , existinghome
  , componentproperties?
  , componentinstantiation
  ) >
Parent partitioning
Attributes None.
Children Elements
Example <componentplacement>
  <usagename> myComponentPlacement </usagename>
  <existinghome>
    ...
  </existinghome>
  <componentproperties>
    ...
  </componentproperties>
  <componentinstantiation>
    ...
  </componentinstantiation>
  ...
  <componentinstantiation>
    ...
  </componentinstantiation>
</componentplacement>
OpenCCM Deployment Support
Status Not fully supported:
The child <componentproperties> is not used to configure the components.
Implementation Behavior The componentplacement retrieves the home reference and then instantiate the component.

<existinghome> Element

existinghome
Description The existinghome element specifies the way to find an home reference using an findbyelement. Be careful this tag is an OpenCCM extension of the CCM specification.
XML DTD <!ELEMENT existinghome
  ( findby
  ) >
Parent partitioning
Attributes None.
Children Elements

  • findby:
    The findby element points to an existing home that can be found within a home finder, naming service, or trader, or using a stringified object reference.

Example <existinghome>
  <usagename> myComponentPlacement </usagename>
  <findby>
    ...
  </findby>
</existinghome>
OpenCCM Deployment Support
Status Fully supported
Implementation Behavior The existing just invokes the resoltion of its findbychild and return the result.

<invocation> Element

invocation
Description The invocation element is used to specify invocation arguments for an executable placement.
XML DTD <!ELEMENT invocation EMPTY ) >

<!ATTLIST invocation
  args CDATA #REQUIRED >
Parent executableplacement
Attributes
  • args CDATA:
    The args attribute is a string containing the arguments to be used in invoking the executable. Let's note that args is just the arguments to the executable, it does not include the executable name.
Children Elements None.
Example <invocation args="param1 param2"/>
OpenCCM Deployment Support
Status Not supported.
Implementation Behavior None.

<destination> Element

destination
Description The destination element is used to record where a homeplacement , executableplacement , hostcollocation , or processcollocation is to be (or has been) deployed. This element was extended from the OMG standart specification see status for more details.
XML DTD
<!ELEMENT destination
  ( findby
  | node
  ) >
<!ATTLIST destination
  type CDATA #IMPLIED >
Parents homeplacement
executableplacement
processcollocation
hostcollocation
Attributes
  • type CDATA:
    The type attribute is a string precising the destination host type. Two standart identifiers are supported, componentserver to precise that the host is a CCM componentserver, and nodemanager to precise that the host is a a DCI node.
Children Elements

  • findby:
    The findby element points to the host home that can be found within a home finder, naming service, or trader, or using a stringified object reference.

  • node:
    The node element describes the node name to use within the DCIInformation service of the current DCIManager.

Examples <destination type="componentserver">
  <findby>
    <namingservice name="ComponentServer1"/>
  </findby>
</destination>
or
<destination type="node">
  <findby>
    <namingservice name="OpenCCM/NodeManagers/MainNode"/>
  </findby>
</destination>
or
<destination>
  <node name="MainNode"/>
</destination>
OpenCCM Deployment Support
Status Fully supported:
The destination element is fully supported, the type attribute allows to support new host type just insering new identifier. The deployment machine provides extension features to integrate the deployment support of new host types.
Implementation Behavior The type atribute must be filled to give information to the deployment machine on the host that will be involved in deployment. Two basis types are supported: type="componentserver" refers a Component Server started manually with the jcs_start <component_server_name> command. In that case the the findby element is required to precised the way to found the componentserver. type="nodemanager" refers to a node started manually with the node_start <node_name> command. This node provides ServerActivator and ComponentInstantiation interfaces. If node element is precised the default DCIInformation service of the current DCIManager is used to found it.using the name attribute of this element,.the type identifier can be ommited because the type=nodemanager is implicit. If findby element is precised the node will be founded using the service denoted. In that case the homefinder service cannot be used to found node. If type is precised when using a node element the default type="nodemanager" is replaced by the given type.

<node> Element

node
Description The node element is used to precised that the node must be found using the current DCIManager DCIInformation service. The attribute name must be used as a research key.
XML DTD
<!ELEMENT node EMPTY >
<!ATTLIST node
  name CDATA #REQUIRED >
Parents destination
Attributes
  • name CDATA:
    The name attribute is a string precising the node name that must be founded using the current DCIManager.
Children Elements None.
Examples <node name="MainNode"/>
OpenCCM Deployment Support
Status Fully supported:
Implementation Behavior The node element is just used to store the node name and precised that the node must be found using DCIInformation service of the current DCIManager.

<componentinstantiation> Element

componentinstantiation
Description The componentinstantiation element describes a particular instantiation of a component relative to a homeplacement . The componentinstantiation is a direct child of the homeplacement element.
XML DTD <!ELEMENT componentinstantiation
  ( usagename?
  , componentproperties?
  , registercomponent*
  , extension*
  , destination?
  ) >

<!ATTLIST componentinstantiation
  id ID #REQUIRED >
Parent homeplacement
Attributes
Children Elements

  • usagename :
    Identifies by a name the component instantiation.

  • componentproperties :
    Used to retrieve the XML property file needed to configure the component instance.

  • registercomponent :
    Used to describe component registration. Multiple component registrations can be described.