Consortium    Solutions    Middleware    Forge    MyObjectWeb 
ObjectWeb Consortium

Advanced - Powered by Google


Project Links
· Home
· Download
· Documentation
· Mailing Lists
· Wiki
· Partners
· License
· History
· Related projects

Developers' Corner
· How to Contribute
· Workplan
· Resources
· CVS Repository
· Bug Tracking
· ObjectWeb Forge Site
· User Mailing List
· Team Mailing List

· Team
· Contacts

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: <package>.csd

    <!DOCTYPE softpkg PUBLIC "-//OMG/DTD CORBA Software Descriptor 3.0//EN" "" >

  • In CORBA Component Descriptors: <component>.ccd

    <!DOCTYPE corbacomponent PUBLIC "-//OMG/DTD Component Assembly Descriptor 3.0//EN" "" >

  • In Component Assembly Descriptors: <assembly>.cad

    <!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: <package>.csd

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

    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 fileinarchive and entrypoint contained in code. They refer to the JAR file containing your business code, and to the public static create_home method of the implementation.

  • The CORBA Component Descriptor: <component>.ccd

    This descriptor is not currently supported by the OpenCCM deployment tools.

  • The Component Assembly Descriptor: <assembly>.cad

    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: <file>.cpf

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

    The OpenCCM's deployment tool remains quite limited on properties. First, it only looks for a propertyfile reference into the Component Assembly Descriptor, at component level. Second, it does not accept only accepts simple tags, with each possible primitive type specified by the CCM (boolean, char, double, float, short, long, octet, string, ulong, ushort).

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 Apollon, 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 demonstration.

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.

Packaging/Assembling Tool editing the Dining Philosophers assembly descriptor

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 .CAD, .CSD, .CCD, .CPF file, modify them, and save them. Optional argument can be any file of these types, and is directly opened in the editor tool.

The file argument can be a CCM archive as well, in case some existing Assembly ARchive (AAR) or Component ARchive (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 OpenCCM), existing META-INF/* files will be replaced with those contained in the opened CCM archive (which are generally the same).

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 (softpkg, corbacomponent, componentassembly and properties). Following capture shows opened the File menu :

Packaging Tool editing the Dining Philosophers assembly descriptor

Using this File menu, users can select classical New, Open, Save operations, managing the opened XML descriptors displayed in the GUI tree. The CCM menu offers the specific operations to handle archives.

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 my_package.csd file.

Packaging Tool editing a new Software Package Descriptor

  • The Context Menu

    A right click on the root element my_package.csd 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 descriptors here .

  • 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) :

Packaging Tool editing the philosopher package descriptor

  • The Description Panel

    Associated GUI panel to a description element 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 Package

    The Browser tree displays some information that facilitates the edition and reading of CCM Package descriptors. For example, the 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 implementation list displays the IDs associated in the tree, so that a software package can be quickly read when looking for a specific implementation.

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 link ). In case the files are shipped in the archive, the Packaging Tool provides a file browser to select existant files in the file system:

Packaging Tool editing the Dining Philosophers assembly descriptor

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 implementation 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 :

Packaging Tool editing the Implementation info for a 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.

Packaging Tool editing the criptor

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.

  • Component Files within an Assembly

Editing of the componentfiles element in Dining Philosophers

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 Assembly: the identifier 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 fileinarchive to open the referenced file (CSD or CAR ).

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, use the Choose file button to select it as a valid componentfile.

Context Menu with Direct Access to CSD files

  • Homeplacements

Placement of the Philosophers' Home and Instances

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 (registerwithnaming 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 register..., 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:

Selection of Component File Reference for a Home

  • Managing of Host and Process Collocations

Following figure presents how are managed collocations of homes on a same 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.

View of collocations, and a DESTINATION element


Being a child for homeplacement or hostcollocation, the destination indicates 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 specification of destination in OpenCCM given here.

  • Connecting Component Instances

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 connectinterface element:

Feeding of a CONNECTINTERFACE element

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

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

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 select its type amongst precise list :

Edition of a Property File Descriptor

This is the only customised GUI for the Property File Descriptor.

Saving XML and Building Archives

  • Revert File

    This operation will reload the existing descriptor file from disk. The tool looses then any change made since last saved version.

  • Save File

    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.

  • Save As...

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

    Any provided information like fileinarchive descriptors, IDL, code libraries, licenses or any resources will be added to the ZIP file.

    Result is a Component ARchive file (CAR), named after the Software Package Descriptor (CSD) root element's name attribute, with the .CAR extension. File will be put in the current working directory.

  • 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 componentproperties elements pointing files to be located inside the Assembly ARchive.

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.

The car_maker and 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.

Copyright © 1999-2005, ObjectWeb Consortium | contact | webmaster | Last modified at 2005-07-07 02:04 PM