Packaging Assembling Tool User's Guide
Supported Formal Public Identifier (FPI) in CCM Deployment descriptors
OpenCCM tools support the following FPIs in CCM descriptors:
In CORBA Software Descriptors:
<!DOCTYPE softpkg PUBLIC "-//OMG/DTD CORBA
Software Descriptor 3.0//EN"
In CORBA Component Descriptors:
<!DOCTYPE corbacomponent PUBLIC "-//OMG/DTD
Component Assembly Descriptor 3.0//EN"
In Component Assembly Descriptors:
<!DOCTYPE componentassembly PUBLIC "-//OMG/DTD
Component Assembly Descriptor 3.0//EN"
In Component Property Files: <file>.cpf
<!DOCTYPE properties PUBLIC "-//OMG/DTD
Component Property File 3.0//EN"
Supported tags in CCM Deployment descriptors
The Software Package Descriptor:
This descriptor provides every information concerning a particular package:
IDL reference, various implementations for specific languages, OS, compilers...
Again, the OpenCCM's deployment tool does not need/support each of the tags from
the CCM specification. Meta information such as title, license, author,... are not
used by the deployment tool, but should be filled in order to
At current stage, the
ccm_deploy tool supports ONE
implementation tag; that means you should need more than one CSD file
in case of testing various OS, for example.
The important tags are the
code. They refer to the JAR file containing
your business code, and to the public static
create_home method of the
The CORBA Component Descriptor:
This descriptor is not currently supported by the OpenCCM deployment tools.
The Component Assembly Descriptor:
This is the main descriptor you must take care about when setting up
a distributed application. It allows you to point out which packages will be involved,
which network hosts will be the targets for the homes (as Component Servers,
or DCI Nodes), and which connections to do at deployment time.
See here for a full documentation about the CAD descriptor, each of its XML tag with information about how to use it with the OpenCCM deployment tool.
The Property File Descriptor:
Setting properties on components is done using this meta descriptor. In CCM
specification, you should be able to refer a properties file anywhere in the
Assembly Descriptor, at home level or component level, or in the
Software Package Descriptor, at package level or
The OpenCCM's deployment tool remains quite limited on properties. First, it
only looks for a
propertyfile reference into the
Assembly Descriptor, at component level. Second, it does not accept
simple tags, with each possible primitive type
specified by the CCM (
Using OpenCCM's Packaging and Assembling Tools
OpenCCM provides Graphical User Interfaces to help developers
writing the meta information needed by a CCM XML deployment. This GUI
is based on the external ObjectWeb tool
which produces base graphic elements that can be assembled in a whole
editor for XML files based on any DTD. Here is a snapshot of the tool
while editing the assembly descriptor for the Dining Philosophers
An improved version of the tool can be downloaded and built from a
distinct module. Please, find
here how to
get the software and build it.
This graphical tool is launched with following command (see here for other available options) :
$ ccm_assembling [ <file> ]
This will display the OpenCCM's Packaging/Assembling Tool
, where one can use the graphical menus to open any
file, modify them, and save them. Optional argument can be
any file of these types, and is directly opened in the editor tool.
file argument can be a CCM archive as well, in case
some existing Assembly ARchive (
AAR) or Component
CAR) need to be re-opened and tuned.
ATTENTION, the content will be unzipped in the current
working directory, overwriting any existing file that would match the
path. When calling
ccm_assembling from your application
directory (e.g. one of the
demo/xxx directory from
META-INF/* files will be replaced
with those contained in the opened CCM archive (which are generally
The initiated GUI is an extended version of default Apollon frame.
It allows edition of XML files based on each DTD of the CCM
deployment specification (
properties). Following capture shows opened the
File menu :
Using this File menu, users can select classical
New, Open, Save
operations, managing the opened XML descriptors displayed in the GUI
CCM menu offers the specific operations to
Creation and Edition of a Software Package Descriptor
When creating a new descriptor, the extension given to the file
tells the tool which kind of descriptor is being created from
scratch. In case an unknown extension is given to the file, a
warning message will appear in the console, and no file will be
created. Following capture shows the edition of a newly created
The Context Menu
A right click on the root element
displays the menu associated to this element. Each possible
additions are listed in the first part of this menu, compliant
with the specification of this descriptor. This avoids any
invalid file with respect to the DTD.
The second part of the menu consists of the other tasks
relevant to a descriptor : Actually, this part is not present
in the context menus associated to sub-elements. These
operations will be described as special ones for all
The SOFTPKG Root Panel
This figure shows too the GUI panel associated to the selected
root element of a Software Package Descriptor. A custom widget
allows the user to enter the version number of this package,
following the CCM specified format w,x,y,z.
On each panel, a Validate button ensures that
each entered information will be kept in the edited descriptor
and saved to the disk. At current stage, this button only saves
the values ; in future versions, it will warn the user in case
of misuse in the panel.
Following capture shows a completed descriptor (here for a
philosopher package from the Dining Philosophers demonstration) :
The Description Panel
Associated GUI panel to a
allows the providing of a small text, in place of a single
line. This conforms to the DTD which specifies PCDATA as a
multiple lines text.
External Information Associated to a Software
The Browser tree displays some information that facilitates
the edition and reading of CCM Package descriptors. For
IDL name of the Component is visible
directly in the Browser, so that the user has an overview just
reading the tree.
In the same manner, the
displays the IDs associated in the tree, so that a software
package can be quickly read when looking for a specific
For the providing of external descriptors linked to a Software
Package Descriptor, the package designer can ship them in the
package archive, or just link them with a URL (XML tag
). In case the files are shipped in the archive, the
Packaging Tool provides a file browser to select existant files
in the file system:
This GUI custom panel contains a Choose file
button, that displays a Java File Selector opened on the current
directory. The designer can then easily point the right file (in
this example, a CORBA Component Archive
CAR), to avoid
any mispell in the file name.
The IMPLEMENTATION element
Providing of information about the implementation of a
Software Package is a major part in the descriptor. This
element must be specific to each variant of an implementation,
regarding the supported Operating System, processor, runtime,
compiler, or of course, the implementation language.
To avoid confusion between each
branch, the tree displays the unique identifiant directly on
the node. To complete the overview of this branch which can
have numerous sub-elements of same kind, the name each one
contain is displayed in the tree too.
Here is a snapshot of the OpenCCM implementation for the
philosopher package :
Fixed Attributes Values
As seen on the capture above, the CCM specification limits the
range of possible values for some of the XML attributes. This
is the case for the
type attribute in the
code providing an implementation. These possible
values are proposed in a custom GUI scrolling list, so that
selection of a bad value is made impossible.
Creation and Edition of a CORBA Component Descriptor
This descriptor is originally specified as generated by a CIDL
compiler. Anyway, there's the possibility to tune the generated
file manually using the Packaging/Assembling Tool.
The generation feature will be present in future releases of the
OpenCCM platform, so at current stage, the package designer has to
fully provide the CORBA Component Descriptor by hand.
A few custom GUI panels are available for the edition of the CORBA
Component Descriptor. When providing a Property File (CPF), the
usual file browser helps to select the right one in the file
system, to be included in the archive.
Here is a snapshot of the Tool editing the Fork Manager CCD
descriptor, from the Dining Philosophers demo.
Creation and Edition of a Component Assembly Descriptor
Edition of the Component Assembly Descriptor constitutes the
proper assembling of a distributed application, by selecting
involved components, setting them on remote hosts, and setting the
connections between each of them.
Figure above shows how the same feature as for the edition of
Software Package Descriptor (CSD), i.e. displaying an overview in
the tree, is used for the edition of assembly descriptors. In this
case, the assembly designer can see useful information for each of
the packages he/she points to while building the Component
for each component, which is to be used in placements, and the
homeplacement IDs as well.
When opening the context menu associated to a
componentfile element, an extra operation can be
found. Open the Software Package will use
the pointer defined in sub-element
to open the referenced file (
Several behaviour are possible. The designer can use pre
existing files which must be referenced using the file
browser of a
fileinarchive panel. In this case,
Open the Software Package will simply open
these files and add them to the tree for edition.
An other proceeding, even if being in opposition to the CCM
separation of concerns, is to write the package descriptors
at same time that the assembly. ATTENTION,
the contextual menu action will not accept references to non
existent files. The only way to create new XML files is to
use the File menu. Once created and saved,
Choose file button to select it as a
As nested elements of the
homeplacement tag, the
componentinstantiation list represents each instance
that the home will have to bring alive during initial deployment.
On this example, the assembly designer has chosen to put every
philosopher on the same
destination, and to register
some of them with the CosNaming Service (
elements). These operations are simply done by the addition
of sub-elements ; for example, the designer adds as many
componentinstantiation branches as he/she needs. For
each, the user adds as many
componentproperties sub-branches he/she wants.
The tool keeps displaying entered names in the tree, so that the``
view of the whole things stays clear. It's usefull when setting
applications engaging a lot of components.
Following demonstrated panel represents the selection of the
component kind. Effectively, a
homeplacement refers to
a single component file declared in the assembly descriptor. To
help the designer and avoid errors, the Tool provides a dynamic
list, that contains any possible component package declared in the
assembly descriptor. In our Dining Philosophers example, three of
them are defined:
Following figure presents how are managed collocations of homes on
destination. Actually, these kinds of XML
elements are authorised as
partitioning children, so
that the Assembly Designer just has to follow the menus without
fear of invalid syntax.
Being a child for
where to deploy these components. There are no automated means for
entering the right destination, regarding the format or the proper
content. Assembly Designers must handle this by hand, following the
destination in OpenCCM given
OpenCCM 0.9 Assembling Tool still manages
connections between component instances as individual
elements that need to be fed sequentially. In order to facilitate
their writing, though, some custom GUI lists are provided for
involved parties selection. Here is a snapshot of the tool, while
doing the edition of a
As it can be seen on this capture, the Assembly Designer can make
selections in scrolling lists amongst components to connect
together. Content of these lists changes according to the state of
the descriptor : it refers to instances declared in the
Identification of connections, while not usefull in proper CCM
deployment, is more important considering the visual impact and
interactivity. In large applications with huge amounts of
connections, each of them should be more easily identifiable while
editing, AND deploying. OpenCCM's Deployment Infrastructure uses
these identifiers to point out damaged and/or impossible
Creation and Edition of a Property File Descriptor
This descriptor contains a few different XML elements. It allows
to set up properties at various levels: for a component instance,
for an implementation, for a package, for a CORBA Component... Each
of these refers to Property Descriptors, which can be opened in the
Tool to be tuned.
Here is a snapshot of the Packaging/Assembling tool while edition
of some specific value for a philosopher name (from Dining
Philosophers). Setting a
simple property imposes to
type amongst precise list :
This is the only customised GUI for the Property File Descriptor.
Saving XML and Building Archives
This operation will reload the existing descriptor file from
disk. The tool looses then any change made since last saved
This is the basic save operation that will backup the current
state of descriptor on disk. The file name used is always known
in advance, since the user has to provide one when choosing to
write a New descriptor in menu.
Same backup as basic Save File, but here a
dialog opens so that the user can choose a different filename.
Generating Package Archive
This operation can be called through the context menu of
Software Package Descriptors. Its goal is to build a ZIP
archive containing everything needed to use the package
Any provided information like
descriptors, IDL, code libraries, licenses or any resources
will be added to the ZIP file.
Result is a Component ARchive file (
after the Software Package Descriptor (
element's name attribute, with the
.CAR extension. File will be put in the current
Generating Assembly Archive
This operation can be called through the context menu of
Component Assembly Descriptors. It acts as the package archive
generator, using the ID attribute from the
root element of the
CAD file and adding the
.AAR extension to the output file. Processed
informations within the assembly include local dependencies
that are to be shipped with the assembly archive, such as
componentfiles or any
elements pointing files to be located inside the
Using Command Line Tools
The OpenCCM Packaging Assembling Tool provides command line tools to build Component ARchives (.CAR) and Assembly ARchives (.AAR). When the Meta information files are ready in an application's
META-INF/ directory, these tools allow the archives creations with a single console command.
aar_maker scripts are shortcuts to special options of the
ccm_assembling script :
$ ccm_assembling --help
Usage: ccm_assembling [-h|--help] [--version] [--silent] [-CAR] [-AAR] [Additional]
-h, --help Display this information and exit
--version Output version information and exit
--silent Silent output messages
-CAR Builds Component ARchives from Software Package descriptors
-AAR Builds Assembly ARchives from Component Assembly Descriptors
Packaging/Assembling Tool providing a GUI and console-based engines (default is GUI).
car_maker is a shortcut for 'ccm_assembling -CAR'
aar_maker is a shortcut for 'ccm_assembling -AAR'
[additional] arguments should be descriptor files to be opened or used for CAR/AAR creation.
For example, in OpenCCM's dinner demonstration's directory, building a Philosopher package would be :
$ ccm_assembling -CAR META-INF/philosopher.csd
$ car_maker META-INF/philosopher.csd
The command reads the Component Software Package Descriptor (.CSD) and creates a .CAR ZIP file in the
archives/ directory. Any resource referenced as to be found in the archive will be resolved and added to the Component ARchive file.
Assemblies of components (.CAD) can be packaged as well :
$ ccm_assembling -AAR META-INF/DiningPhilosophers.cad
$ aar_maker META-INF/DiningPhilosophers.cad
Please note that the usage of these console tools implies that any referenced resource in the descriptor is available in the same relative location. For example, a .CSD file pointing a
my_component.jar library in an
archives/ directory within the .CAR file will expect this
archives/my_component.jar to be present in the current working directory.