Difference between revisions of "Software Archive Specification"

From Gcube Wiki
Jump to: navigation, search
(→‎Dependencies Section)
Line 9: Line 9:
 
For each Service Profile a corresponding 'Software Archive' should be delivered.
 
For each Service Profile a corresponding 'Software Archive' should be delivered.
  
−
==Structure==
+
==Software Archive Structure==
 
A Software Archive is a single TAR GZ file, which contains all the files declared on the Service Profile and has the following structure:
 
A Software Archive is a single TAR GZ file, which contains all the files declared on the Service Profile and has the following structure:
 
<pre>
 
<pre>
Line 50: Line 50:
  
  
−
===Using ETICS to automatically create Software Archives===
+
===Using ETICS===
  
 
Create a new component in ETICS for each service profile you already defined in order to create the related Service Archive as artefact. Let see now how you should do this in ETICS.
 
Create a new component in ETICS for each service profile you already defined in order to create the related Service Archive as artefact. Let see now how you should do this in ETICS.

Revision as of 18:10, 5 June 2008

Short background

A 'Service' in gCube is a software system that delivers functionalities and it is composed by a set of related 'Packages'.

In the gCube context, a 'Package' is a 'piece of software' that can be deployed in a GHN. Packages are single tarballs, compliant with the Package Model, that contain the files to be installed, along with rules describing software/packages dependencies, deployment instructions, etc.

Each service is described by a 'Profile' document, named 'Service Profile'.

For each Service Profile a corresponding 'Software Archive' should be delivered.

Software Archive Structure

A Software Archive is a single TAR GZ file, which contains all the files declared on the Service Profile and has the following structure: 

/-profile.xml
|
/-<PackageName>
    |
    |-<LibraryFile/GARArchive>
    |-<additional files>

/-<PackageName>
    |
    |-<LibraryFile/GARArchive>
    |-<additional files>

/-<PackageName>
    |
    |-<LibraryFile/GARArchive>
    |-<additional files>

/.....

where:

  • at the root level, the archive contains the Service Profile of the service itself. All the file names included in the archive have to be reported with a relative path starting from their <PackageName> folder (not included) *as defined on the Service Profile*.
  • for every Package declared inside the Service Profile, the archive contains a directory (called with the same name of the PackageName field of the profile) including the corresponding jar/gar file:
    • for a WSRF service the name reported into the GARArchive field;
    • for a library/stubs the name reported into the LibraryFile field.

and any other additional file declared in the service profile (e.g. installation or reboot scripts)

Creating Software Archives

Manually

An easy way to create a Service Archive is to do it manually.

  1. Create a folder structure as described in previous section according to the corresponding Service Profile.
  2. Create a TAR GZ file of the created folder structure.


Using ETICS

Create a new component in ETICS for each service profile you already defined in order to create the related Service Archive as artefact. Let see now how you should do this in ETICS.

  1. name the component as <ServiceName>-servicearchive
  2. declare a dynamic dependency against each ETICS component that produces a package to be included in the Service Archive. In this way, the packages forming the whole service are available and they are built immediately before they are packaged. Link this configuration with the corresponding parent configuration.
  3. use the CVS Commands to download additional files related to the whole service, but not included in the packages (like the Service Profile)
  4. use the Build Commands available in ETICS in the following way:
INIT:
The init command has to be used to create the ${prefix} directory and all the <PackageName> subdirs

INSTALL:
The install command has to be used to move the GAR/JAR files and other additional files from their
 ${moduleDir}directory to the appropriate <PackageName> directory previously created.

PACKAGING:
Leave this command blank. At the end of the build process the default ETICS package command will create a
tar.gz (the ServiceArchive!) of the ${prefix} folder

To better understand the final result of the process above, you can have a look to the *-servicearchive components already created in ETICS.

Example

The following Profile describes a service and its stubs as two packages 

<?xml version="1.0" encoding="UTF-8"?>
<Resource xsi:noNamespaceSchemaLocation="service.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <ID></ID>
  <Type>Service</Type>
  <Profile>
    <Description>Description</Description>
    <Class>Class</Class>
    <Name>Name</Name>
    <Version>1.0</Version>
    <Configuration>
      <Static>
        <Configs>
          <Config>
            <File>aux.txt</File>
            <Description>aux</Description>
            <Label>aux</Label>
          </Config>
          <Config>
            <File>aux2.txt</File>
            <Description>aux2</Description>
            <Label>aux2</Label>
          </Config>
        </Configs>
      </Static>
      <Dynamic/>
    </Configuration>
    <Dependencies>
      <Dependency>
        <Class>DepClass</Class>
        <Name>DepName</Name>
        <Version>1.0</Version>
      </Dependency>
    </Dependencies>
    <Packages>
      <Main>
        <Description>Main Package Description</Description>
        <Name>MainPackage</Name>
        <Version>1.1</Version>
        <MultiVersion value="true"/>
        <Mandatory level="GHN"/>
        <Shareable level="VO"/>
        <InstallScripts>
          <File>maininstall.sh</File>
        </InstallScripts>
        <UninstallScripts>
          <File>mainuninstall.sh</File>
        </UninstallScripts>
        <RebootScripts>
          <File>mainreboot.sh</File>
        </RebootScripts>
        <Dependencies>
          <Dependency>
            <Service>
              <Class>MainDepClass</Class>
              <Name>MainDepName</Name>
              <Version>1.0</Version>						
            </Service>
            <Package>DepPackage</Package>
            <Version>1.0</Version>
            <Scope level="GHN"/>
            <Optional>true</Optional>
          </Dependency>
        </Dependencies>
        <SpecificData>text</SpecificData>
        <GARArchive>main.gar</GARArchive>
        <ServiceEquivalenceFunctions>...</ServiceEquivalenceFunctions>
        <PortType>...</PortType>
      </Main>
      <Software>
        <Description>Software Description</Description>
        <Name>SoftwareName</Name>
        <Version>1.0</Version>
        <MultiVersion value="true"/>
        <Mandatory level="GHN"/>
        <Shareable level="VO"/>
        <GHNRequirements>....</GHNRequirements>
        <InstallScripts>
          <File>softwareinstall.sh</File>
        </InstallScripts>
        <UninstallScripts>
          <File>softwareuninstall.sh</File>
        </UninstallScripts>
        <RebootScripts>
          <File>softwarereboot.sh</File>
        </RebootScripts>
        <Dependencies>
          <Dependency>
            <Service>
              <Class>SoftwareClass</Class>
              <Name>SoftwareName</Name>
              <Version>1.0</Version>
            </Service>
            <Package>SoftwarePackage</Package>
            <Version>1.0</Version>
            <Scope level="VO"/>
            <Optional>false</Optional>
          </Dependency>
        </Dependencies>
        <SpecificData>text</SpecificData>
        <Type>library</Type>
        <Files>
          <File>softwarefile.txt</File>
        </Files>
      </Software>
    </Packages>
    <SpecificData>text</SpecificData>
  </Profile>
</Resource>

This service has to produce as ServiceArchive a tar.gz file with the following structure: 

.
|-- MainPackage
|   |-- aux.txt
|   |-- aux2.txt
|   |-- main.gar
|   |-- maininstall.sh
|   |-- mainreboot.sh
|   `-- mainuninstall.sh
|-- SoftwareName
|   |-- softwarefile.txt
|   |-- softwareinstall.sh
|   |-- softwarereboot.sh
|   `-- softwareuninstall.sh
`-- profile.xml

Detailed Section Analysis

Description Tag

The description supplied in the store(StoreMessage) method ha priority on the one supplied with the profile. If no description is supplied with the method invocation the one filled in the profile will be used. If on one of this choice are used to supply the description the validation fails.

Class & Name Tag

During validation the Class and Name must be the same to the one passed as argument to store(StoreMessage) API.

Version Tag

This tag is always replaced with the version supplied with the store(StoreMessage) method. This choice have been thought to simplify the life of the developer to avoid to change everytime profile.

Configuration Section

<Configuration>
  <Static>
   <Configs>
    <Config>
     <File>aux.txt</File>
     <Description>aux</Description>
     <Label>aux</Label>
    </Config>
    <Config>
     <File>aux2.txt</File>
     <Description>aux2</Description>
     <Label>aux2</Label>
    </Config>
   </Configs>
  </Static>
 <Dynamic/>
</Configuration>



.
|-- MainPackage
|   |-- aux.txt
|   |-- aux2.txt
|   |-- main.gar
|   |-- maininstall.sh
|   |-- mainreboot.sh
|   `-- mainuninstall.sh
|-- SoftwareName
|   |-- softwarefile.txt
|   |-- softwareinstall.sh
|   |-- softwarereboot.sh
|   `-- softwareuninstall.sh
`-- profile.xml


This section will be moved soon on Main section. For the moment you have just to remind that the files declared on this section must go inside the directory with the name of the Main Package on Software Archive.

InstallScripts/UninstallScripts/RebootScripts Tag

<Main>
...
<InstallScripts>
 <File>maininstall.sh</File>
</InstallScripts>
<UninstallScripts>
 <File>mainuninstall.sh</File>
</UninstallScripts>
<RebootScripts>
 <File>mainreboot3.sh</File>
</RebootScripts>
...
</Main>



<Software>
...
<InstallScripts>
 <File>softwareinstall.sh</File>
</InstallScripts>
<UninstallScripts>
 <File>softwareuninstall.sh</File>
</UninstallScripts>
<RebootScripts>
 <File>softwarereboot3.sh</File>
</RebootScripts>
...
</Software>



.
|-- MainPackage
|   |-- aux.txt
|   |-- aux2.txt
|   |-- main.gar
|   |-- maininstall.sh
|   |-- mainreboot.sh
|   `-- mainuninstall.sh
|-- SoftwareName
|   |-- softwarefile.txt
|   |-- softwareinstall.sh
|   |-- softwarereboot.sh
|   `-- softwareuninstall.sh
`-- profile.xml


Just remind the general rule for this section: The files must be go inside the directory with the name of the Package on Software Archive.

Dependencies Section

<Main>
...
<Dependencies>
 <Dependency>
  <Service>
   <Class>MainDepClass</Class>
   <Name>MainDepName</Name>
   <Version>1.0</Version>						
  </Service>
  <Package>DepPackage</Package>
  <Version>1.0</Version>
  <Scope level="GHN"/>
  <Optional>true</Optional>
 </Dependency>
</Dependencies>
...
</Main>



<Software>
...
<Dependencies>
 <Dependency>
  <Service>
   <Class>SoftwareClass</Class>
   <Name>SoftwareName</Name>
   <Version>1.0</Version>
  </Service>
  <Package>SoftwarePackage</Package>
  <Version>1.0</Version>
  <Scope level="VO"/>
  <Optional>false</Optional>
 </Dependency>
</Dependencies>
...
</Software>


Each Dependency is in term of package. Each package is identified by the Service informations and PackageName and PackageVersion. Instead of specifying the Package Version you can specify a range of version. The syntax for this can be find at [1] (please do not consider <qualifier> that is used internally transparently for the user).


Please consider this mapping between ETICS versioning [2] and MAVEN versioning:


ETICS version:

[major-number].[minor-number].[patch-number]-[age]

MAVEN version:

<major>.<minor>.<revision>-<build>



The Scope tag is used to specify the Scope Level for dependency deployng. Allowed value are GHN,VRE,VO. This informations are used by the deployer.



The Optional tag is not mandatory and if not present is like you specify false. This allow the developer to specify if a dependency can be potentially optional during the deployment phase. As example you can think to a service A developed to use a service B to exploit it. If the service A can also work without service B (if it doesn't find any running instance of B) for example because it use an internal functionality you can specify the dependency as Optional.

Specific Main Package Section

GARArchive Tag

<Main>
...
<GARArchive>main.gar</GARArchive>
...
<Main>



.
|-- MainPackage
|   |-- aux.txt
|   |-- aux2.txt
|   |-- main.gar
|   |-- maininstall.sh
|   |-- mainreboot.sh
|   `-- mainuninstall.sh
|-- SoftwareName
|   |-- softwarefile.txt
|   |-- softwareinstall.sh
|   |-- softwarereboot.sh
|   `-- softwareuninstall.sh
`-- profile.xml


The gar archive must go under the Main Package folder on Software Archive

Specific Software Package Section

Files Section

<Software>
...
<Files>
 <File>softwarefile.txt</File>
</Files>
...
</Software>



.
|-- MainPackage
|   |-- aux.txt
|   |-- aux2.txt
|   |-- main.gar
|   |-- maininstall.sh
|   |-- mainreboot.sh
|   `-- mainuninstall.sh
|-- SoftwareName
|   |-- softwarefile.txt
|   |-- softwareinstall.sh
|   |-- softwarereboot.sh
|   `-- softwareuninstall.sh
`-- profile.xml


The files must go under the folder with the name of the Software Package on Software Archive


URI Tag

Not showed in the example instead of files section you can have an URI tag 

<URI>http://dlib25.isti.cnr.it/maven/Service3.tar.gz<URI>

During validation phase the Software Repository try to download the file. If the file is not downloadable the validation fails. If you specify this tag you have to be sure this file will be available for a long period in the future. If you are not sure of it is better to include it directly on Software Archive

Retrieved from "https://gcube.wiki.gcube-system.org/index.php?title=Software_Archive_Specification&oldid=3582"