Packaging and deployment of Trentino applications

This section is about contribution packaging, versioning and modularity

Packaging Contributions (applications)

A contribution must be a folder with the following structure: 

		
				ROOT/
				 META-INF/
				   sca-contribution.xml
				   sca-contribution.dll
				   sca-contribution.conf
				 bin/
				   some_dlls.dll
				 any_folder_in_root/

The META-INF directory and all the sca-contribution.* files are required by the runtime. The default directory containing binaries is /bin folder in the contribution root directory. It is searched by default for binaries. To provide an alternative binary directory, developer should import the directory into the contribution using import.cpp tag in sca-contribution.xml. For more details see SCA specification section 7.1 (Executable files)

Note: In the upcomming releases, developer will be able to provide a contribution in ZIP format during installation.

Version and dependencies management

User Stories covered

  1. The administrator wants to label a contribution with a version, so that he explicitely knows which version of a contribution is running on a Runtime. The administrator can therefore query for a contribution version using info command. The administrator can also up/downgrade a contributíon from one version to another one.
  2. The user wants to import and use services or artifacts from a third party contribution X. Since X migth be updated in the future by the administrator, the user wants to make sure that the application stays consistent event after changes on X. For this purpose the user request that X should have a version number, that is used to identify to correct X to be used.

Not covered User Stories

  1. Multiple version of an application running on the same runtime. This is not covered, since a component name should be unique in the Trentino domain.
  2. Dependenciey check is not done by the runtime but only during validation and deployment by trengen. The runtime will only issue a warning if an application is updated while other applications depends on it. The user is then responsible updating dependent application accordingly.

Specifying version

For Trentino the version of a contribution is provided in the version attribute of the contribution. If no version is provided. The default value 0.0.0 is assumed. The version uses OSGI format : major.minor.micro.qualifier , where the qualifier part is optional.

Example contribution namespace with version

<contribution xmlns:dividerNS="http://divider" version="1.0.0">
...
</contribution>

Declaring and using dependencies

A contribution can use resources provided by another contributions. A resource is exported by a contribution using export.cpp tag. Then the exported resource is imported in another contribution using the import.cpp tag.

Example exporting a subdirectory of the "logging" contribution version 1.0.0 

<contribution xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912" xmlns:logging="LoggingServiceNamespace" version="1.0.0">
   <deployable composite="logging:LoggingServiceComposite"/>
   <export.cpp name="logging:metadata" path="services" />
   <export.cpp name="logging:bin" path="bin" />
</contribution>

Example importing a subdirectory of the logging contribution version 1.0.0 into calculator contribution version 2.0.0 

<contribution xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912" xmlns:sample="BasicCalculatorNamespace" version="2.0.0">
   <deployable composite="sample:BasicCalculatorComposite"/>
   <import.cpp name="loggingmetadata" location="logging:metadata" version="1.0.0" />
</contribution>

Example using the imported logging service 

           <componentType xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912">
      <service name="Calculator" >
      <interface.cpp class="Trentino::Example::BasicCalculator::Calculator" header="services/TrentinoExampleBasicCalculatorCalculator.h"/>
    </service>
	<reference name="LoggingService" multiplicity="1..1" autowire="false" target="LoggingServiceImpl/LoggingService">
		<interface.cpp class="Trentino::Example::Logging::LoggingService" header="loggingmetadata:TrentinoExampleLoggingLoggingService.h"/>
	</reference>
</componentType>
Validation of a contribution that depends on other ones

Since contribution calculator depends on the logging contribution, we needs to find dependencies during the validation process. For that purpose the user should provide the list of external contributions to Trengen.

Validation of Basiccalculator
            
            Trengen -cont BasicCalculator -ec LoggingService

The -ec options of Trengen specifies a comma separated list of paths to the contributions on which BasicCalculator depends

Error cases

If during installation of contribution calculator, resource with name logging:metadata with version 1.0.0 is not available in the runtime, then the deployement of the calculator will fails.

Updating a contribution

The administrator wants to upgrade a contribution from one version to another. The update command from the console should update a contribution to a new version. The format of the command is a follow: update "path_to_new_version" "contributionname"

  1. If the new and the old version are the same, Trentino return and error message. "No changes necessary: New version and old version are identical: "version number". Use refresh instead"
  2. If the update is sucessfull. Trentino output an informative message with the new and the old version.
  3. If an error occured during update, Trentino will try to reload the old version of the application and will output an error message saying that it is making a rollback to the old version
  4. If the rollback was not successfull, then an error message is shown saying that the rollback is not successful and that admin should rollback manually
  5. If a dependency is missing during update, then an error message is printed.
Removing a contribution from which other contributions depend

If The administrator remove a contribution from which other contributions depends. A warning stating that the contribution is used by other contributions is shown. The list of contributions using exported resources is shown in the output.

Internally, absolute paths to resources from removed contributions still exists and are stored in the contributions that uses the dependencies. Therefore dependent contributions will still continue working normally as far as no resource is deleted from the file system.

Providing dependencies to an executable file

In this section, we describe how to specify where the runtime can find all the executables, from which an executable is dependent. Dependencies can be specify globally for all executables, or locally by executable. Local specification of dependencies overwrite global specification

Specifying global dependencies at contribution level

Deployer can specify a folder that contains all the executables, from which an executable is dependent. 

<contribution xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200912" xmlns:ss="MyNamespace">
   <deployable composite="ss:MyComposite"/>
   <import.cpp name="dll-directory" location="../bin" />
</contribution>

The tag import.cpp MUST have the name dll-directory . The required location can be relative to the contribution root folder or absolute. We recommend using a relative value since it is more portable

Changing dll-directory at install time

In extreme case, the dll-directory might be different from device to device. The deployer still have the possibility to set the dll-directory without having to rebuild the contribution. In the META-INF directory, open the file sca-contribution.conf and add the following line at the end of the file: 

dir=<absolute/or relative/ path to the/ dll directory >

The runtime will not load your contribution if the given directory does not exists.