Difference between revisions of "Software Archive Specification"

From Gcube Wiki
Jump to: navigation, search
(→‎Report Generation)
m
 
(105 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
<!-- CATEGORIES -->
 +
[[Category:Developer's Guide]]
 +
<!-- END CATEGORIES -->
 
==Short background==
 
==Short background==
  
−
A 'Service' in gCube is a software system that delivers functionalities and it is composed by a set of related 'Packages'.
+
A 'Service' in gCube is a software system which delivers functionality. 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.
+
In the gCube context, a 'Package' is a 'piece of software' that can be deployed into a gHN. Packages are single tarballs, compliant with the Package Model, that contains the files to be installed, along with rules describing software/packages dependencies, deployment instructions and so on.
  
−
Each service is described by a 'Profile' document, named 'Service Profile'.  
+
Each service is described by a 'Profile' document, named ''Service Profile''.  
  
−
For each Service Profile a corresponding 'Software Archive' should be delivered.
+
For each ''Service Profile'' a corresponding 'Software Archive' should be delivered.
  
 
==Software Archive 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>
 
−
/-profile.xml
 
−
|
 
−
/-<PackageName>
 
−
    |
 
−
    |-<LibraryFile/GARArchive>
 
−
    |-<additional files>
 
  
−
/-<PackageName>
+
.
−
    |
+
|--<PackageName>(Main)
−
     |-<LibraryFile/GARArchive>
+
| |--<GARArchive>
−
     |-<additional files>
+
|  |--svnpath.txt
 +
|  |--<additional files>
 +
|  |--doc
 +
|     \--api
 +
|       |- index.html
 +
|        \- others javadoc files
 +
|
 +
|
 +
|--<PackageName>
 +
|  |--<LibraryFile>
 +
|  |--svnpath.txt
 +
|  |--<additional files>
 +
|  \--doc
 +
|     \--api
 +
|       |-- index.html
 +
|        \-- others javadoc files
 +
|
 +
|....
 +
|
 +
|
 +
|--<PackageName>
 +
|  |--<LibraryFile>
 +
|  |--svnpath.txt
 +
|  |--<additional files>
 +
|  \--doc
 +
|    \--api
 +
|        |-- index.html
 +
|        \-- others javadoc files
 +
|
 +
|-- README
 +
|-- MANTAINERS
 +
|-- CHANGELOG
 +
|-- INSTALL
 +
|-- LICENSE
 +
|
 +
\-profile.xml
  
−
/-<PackageName>
 
−
    |
 
−
    |-<LibraryFile/GARArchive>
 
−
    |-<additional files>
 
−
 
−
/.....
 
−
</pre>
 
 
where:
 
where:
  
Line 38: Line 62:
 
** for a library/stubs the name reported into the LibraryFile 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)
 
and any other additional file declared in the service profile (e.g. installation or reboot scripts)
 +
 +
In Main packages the 'doc/api' folder with javadoc is mandatory, optional for the others packages.
 +
 +
The 'svnpath.txt' file is mandatory for each packages and contains the link to the source code or to the library download location in cases of external library not open source.
  
 
==Creating Software Archives==
 
==Creating Software Archives==
Line 63: Line 91:
  
 
INSTALL:
 
INSTALL:
−
The install command has to be used to move the GAR/JAR files and other additional files from their
+
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.
−
${moduleDir}directory to the appropriate <PackageName> directory previously created.
+
Copy the javadoc to the appropriate <PackageName> directory.
 +
Furthermore echo command with vcsroot link have to be redirected to a file 'svnpath.txt' in the appropriate <PackageName> directory.
  
 
PACKAGING:
 
PACKAGING:
Line 76: Line 105:
  
 
To better understand the example below check the [[ Profile_Specification | Service Profile]] specification.
 
To better understand the example below check the [[ Profile_Specification | Service Profile]] specification.
 +
 +
=== Service Profile Example===
  
 
The following Profile describes a service and its stubs as two packages
 
The following Profile describes a service and its stubs as two packages
  
−
<pre>
+
<source lang=xml>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<Resource xsi:noNamespaceSchemaLocation="service.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 
<Resource xsi:noNamespaceSchemaLocation="service.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
−
  <ID></ID>
+
<ID></ID>
−
  <Type>Service</Type>
+
<Type>Service</Type>
−
  <Profile>
+
<Profile>
−
    <Description>Description</Description>
+
<Description>Description</Description>
−
    <Class>Class</Class>
+
<Class>Class</Class>
−
    <Name>Name</Name>
+
<Name>Name</Name>
−
    <Version>1.0</Version>
+
<Version>1.0.0</Version>
−
    <Configuration>
+
<Configuration>
−
      <Static>
+
<Static>
−
        <Configs>
+
<Configs>
−
          <Config>
+
<Config>
−
            <File>aux.txt</File>
+
<File>aux.txt</File>
−
            <Description>aux</Description>
+
<Description>aux</Description>
−
            <Label>aux</Label>
+
<Label>aux</Label>
−
          </Config>
+
</Config>
−
          <Config>
+
<Config>
−
            <File>aux2.txt</File>
+
<File>aux2.txt</File>
−
            <Description>aux2</Description>
+
<Description>aux2</Description>
−
            <Label>aux2</Label>
+
<Label>aux2</Label>
−
          </Config>
+
</Config>
−
        </Configs>
+
</Configs>
−
      </Static>
+
</Static>
−
      <Dynamic/>
+
<Dynamic/>
−
    </Configuration>
+
</Configuration>
−
    <Dependencies>
+
<Dependencies>
−
      <Dependency>
+
<Dependency>
−
        <Class>DepClass</Class>
+
<Class>DepClass</Class>
−
        <Name>DepName</Name>
+
<Name>DepName</Name>
−
        <Version>1.0</Version>
+
<Version>1.0.0</Version>
−
      </Dependency>
+
</Dependency>
−
    </Dependencies>
+
</Dependencies>
−
    <Packages>
+
<Packages>
−
      <Main>
+
<Main>
−
        <Description>Main Package Description</Description>
+
<Description>Main Package Description</Description>
−
        <Name>MainPackage</Name>
+
<Name>Name-service</Name>
−
        <Version>1.1</Version>
+
<Version>1.1.0</Version>
−
        <MultiVersion value="true"/>
+
<MultiVersion value="true"/>
−
        <Mandatory level="GHN"/>
+
<Mandatory level="GHN"/>
−
        <Shareable level="VO"/>
+
<Shareable level="VO"/>
−
        <InstallScripts>
+
<InstallScripts>
−
          <File>maininstall.sh</File>
+
<File>maininstall.sh</File>
−
        </InstallScripts>
+
</InstallScripts>
−
        <UninstallScripts>
+
<UninstallScripts>
−
          <File>mainuninstall.sh</File>
+
<File>mainuninstall.sh</File>
−
        </UninstallScripts>
+
</UninstallScripts>
−
        <RebootScripts>
+
<RebootScripts>
−
          <File>mainreboot.sh</File>
+
<File>mainreboot.sh</File>
−
        </RebootScripts>
+
</RebootScripts>
−
        <Dependencies>
+
<Dependencies>
−
          <Dependency>
+
<Dependency>
−
            <Service>
+
<Service>
−
              <Class>MainDepClass</Class>
+
<Class>MainDepClass</Class>
−
              <Name>MainDepName</Name>
+
<Name>MainDepName</Name>
−
              <Version>1.0</Version>
+
<Version>1.0.0</Version>
−
            </Service>
+
</Service>
−
            <Package>DepPackage</Package>
+
<Package>DepPackage</Package>
−
            <Version>1.0</Version>
+
<Version>1.0.0</Version>
−
            <Scope level="GHN"/>
+
<Scope level="GHN"/>
−
            <Optional>true</Optional>
+
<Optional>true</Optional>
−
          </Dependency>
+
</Dependency>
−
        </Dependencies>
+
</Dependencies>
−
        <SpecificData>text</SpecificData>
+
<SpecificData>text</SpecificData>
−
        <GARArchive>main.gar</GARArchive>
+
<GARArchive>main.gar</GARArchive>
−
        <ServiceEquivalenceFunctions>...</ServiceEquivalenceFunctions>
+
<ServiceEquivalenceFunctions>...</ServiceEquivalenceFunctions>
−
        <PortType>...</PortType>
+
<PortType>...</PortType>
−
      </Main>
+
</Main>
−
      <Software>
+
<Software>
−
        <Description>Software Description</Description>
+
<Description>Software Description</Description>
−
        <Name>SoftwareName</Name>
+
<Name>Name-stubs</Name>
−
        <Version>1.0</Version>
+
<Version>1.0.0</Version>
−
        <MultiVersion value="true"/>
+
<MultiVersion value="true"/>
−
        <Mandatory level="GHN"/>
+
<Mandatory level="GHN"/>
−
        <Shareable level="VO"/>
+
<Shareable level="VO"/>
−
        <GHNRequirements>....</GHNRequirements>
+
<GHNRequirements>....</GHNRequirements>
−
        <InstallScripts>
+
<InstallScripts>
−
          <File>softwareinstall.sh</File>
+
<File>softwareinstall.sh</File>
−
        </InstallScripts>
+
</InstallScripts>
−
        <UninstallScripts>
+
<UninstallScripts>
−
          <File>softwareuninstall.sh</File>
+
<File>softwareuninstall.sh</File>
−
        </UninstallScripts>
+
</UninstallScripts>
−
        <RebootScripts>
+
<RebootScripts>
−
          <File>softwarereboot.sh</File>
+
<File>softwarereboot.sh</File>
−
        </RebootScripts>
+
</RebootScripts>
−
        <Dependencies>
+
<Dependencies>
−
          <Dependency>
+
<Dependency>
−
            <Service>
+
<Service>
−
              <Class>SoftwareClass</Class>
+
<Class>SoftwareClass</Class>
−
              <Name>SoftwareName</Name>
+
<Name>SoftwareName</Name>
−
              <Version>1.0</Version>
+
<Version>1.0.0</Version>
−
            </Service>
+
</Service>
−
            <Package>SoftwarePackage</Package>
+
<Package>SoftwarePackage</Package>
−
            <Version>1.0</Version>
+
<Version>1.0.0</Version>
−
            <Scope level="VO"/>
+
<Scope level="VO"/>
−
            <Optional>false</Optional>
+
<Optional>false</Optional>
−
          </Dependency>
+
</Dependency>
−
        </Dependencies>
+
</Dependencies>
−
        <SpecificData>text</SpecificData>
+
<SpecificData>text</SpecificData>
−
        <Type>library</Type>
+
<Type>library</Type>
−
        <Files>
+
<Files>
−
          <File>softwarefile.txt</File>
+
<File>stubs.jar</File>
−
        </Files>
+
</Files>
−
      </Software>
+
</Software>
−
    </Packages>
+
<Software>
−
    <SpecificData>text</SpecificData>
+
<Description>Test Suite</Description>
−
  </Profile>
+
<Name>Name-test-suite</Name>
 +
<Version>1.0.0</Version>
 +
[...]
 +
<Type>library</Type>
 +
<Files>
 +
<File>testsuite.jar</File>
 +
</Files>
 +
</Software>
 +
</Packages>
 +
<SpecificData>text</SpecificData>
 +
</Profile>
 
</Resource>
 
</Resource>
−
</pre>
+
</source>
 +
 
  
 
This service has to produce as ServiceArchive a tar.gz file with the following structure:
 
This service has to produce as ServiceArchive a tar.gz file with the following structure:
  
−
<pre>
+
.
−
.
+
|-- Name-service
−
|-- MainPackage
+
|  |-- aux.txt
−
|  |-- aux.txt
+
|  |-- aux2.txt
−
|  |-- aux2.txt
+
|  |-- main.gar
−
|  |-- main.gar
+
|  |-- maininstall.sh
−
|  |-- maininstall.sh
+
|  |-- mainreboot.sh
−
|  |-- mainreboot.sh
+
|  |-- mainuninstall.sh
−
|  `-- mainuninstall.sh
+
|  |-- svnpath.txt
−
|-- SoftwareName
+
|  |--doc
−
|  |-- softwarefile.txt
+
|    \--api
−
|  |-- softwareinstall.sh
+
|        |--index.html
−
|  |-- softwarereboot.sh
+
|        \--others javadoc files
−
|  `-- softwareuninstall.sh
+
|
−
`-- profile.xml
+
|-- Name-stubs
−
</pre>
+
|  |-- stubs.jar
 +
|  |-- softwareinstall.sh
 +
|  |-- softwarereboot.sh
 +
|  |-- softwareuninstall.sh
 +
|  \-- svnpath.txt
 +
|
 +
|-- Name-test-suite
 +
|  |-- testsuite.jar
 +
|  \-- svnpath.txt
 +
|
 +
\-- profile.xml
  
 
==Software Archive Validation Process==
 
==Software Archive Validation Process==
Line 225: Line 277:
  
 
===Configuration Section===
 
===Configuration Section===
−
 
+
<source lang=xml>
 
  <Configuration>
 
  <Configuration>
−
  <Static>
+
<Static>
−
  <Configs>
+
<Configs>
−
    <Config>
+
<Config>
−
    <File>'''aux.txt'''</File>
+
<File>'''aux.txt'''</File>
−
    <Description>aux</Description>
+
<Description>aux</Description>
−
    <Label>aux</Label>
+
<Label>aux</Label>
−
    </Config>
+
</Config>
−
    <Config>
+
<Config>
−
    <File>'''aux2.txt'''</File>
+
<File>'''aux2.txt'''</File>
−
    <Description>aux2</Description>
+
<Description>aux2</Description>
−
    <Label>aux2</Label>
+
<Label>aux2</Label>
−
    </Config>
+
</Config>
−
  </Configs>
+
</Configs>
−
  </Static>
+
</Static>
−
  <Dynamic/>
+
<Dynamic/>
 
  </Configuration>
 
  </Configuration>
−
 
+
</source>
−
 
+
−
 
+
 
  .
 
  .
−
  |-- '''MainPackage'''
+
  |-- Name-service
 
  |  |-- '''aux.txt'''
 
  |  |-- '''aux.txt'''
 
  |  |-- '''aux2.txt'''
 
  |  |-- '''aux2.txt'''
Line 253: Line 303:
 
  |  |-- maininstall.sh
 
  |  |-- maininstall.sh
 
  |  |-- mainreboot.sh
 
  |  |-- mainreboot.sh
−
  |  `-- mainuninstall.sh
+
  |  |-- mainuninstall.sh
−
  |-- SoftwareName
+
  |  |-- svnpath.txt
−
  |  |-- softwarefile.txt
+
  |  |--doc
 +
|    \--api
 +
|        |--index.html
 +
|        \--others javadoc files
 +
|
 +
|-- Name-stubs
 +
|  |-- stubs.jar
 
  |  |-- softwareinstall.sh
 
  |  |-- softwareinstall.sh
 
  |  |-- softwarereboot.sh
 
  |  |-- softwarereboot.sh
−
  |  `-- softwareuninstall.sh
+
  |  |-- softwareuninstall.sh
−
  `-- profile.xml
+
  |  \-- svnpath.txt
 +
|
 +
|-- Name-test-suite
 +
|  |-- testsuite.jar
 +
|  \-- svnpath.txt
 +
|
 +
\-- profile.xml
  
  
Line 267: Line 329:
  
 
===InstallScripts/UninstallScripts/RebootScripts Tag===
 
===InstallScripts/UninstallScripts/RebootScripts Tag===
−
 
+
<source lang=xml>
 
  <Main>
 
  <Main>
 
   ...
 
   ...
−
   <Name>'''MainPackage'''</Name>
+
   <Name>'''Name-service'''</Name>
−
  ...
+
[...]
−
  <InstallScripts>
+
<InstallScripts>
−
  <File>'''maininstall.sh'''</File>
+
<File>'''maininstall.sh'''</File>
−
  </InstallScripts>
+
</InstallScripts>
−
  <UninstallScripts>
+
<UninstallScripts>
−
  <File>'''mainuninstall.sh'''</File>
+
<File>'''mainuninstall.sh'''</File>
−
  </UninstallScripts>
+
</UninstallScripts>
−
  <RebootScripts>
+
<RebootScripts>
−
  <File>'''mainreboot.sh'''</File>
+
<File>'''mainreboot.sh'''</File>
−
  </RebootScripts>
+
</RebootScripts>
−
  ...
+
[...]
 
  </Main>
 
  </Main>
 +
</source>
  
−
 
+
<source lang=xml>
−
 
+
 
  <Software>
 
  <Software>
−
  ...
+
[...]
−
  <Name>'''SoftwareName'''</Name>
+
<Name>'''Name-stubs'''</Name>
−
  ...
+
[...]
−
  <InstallScripts>
+
<InstallScripts>
−
  <File>'''softwareinstall.sh'''</File>
+
<File>'''softwareinstall.sh'''</File>
−
  </InstallScripts>
+
</InstallScripts>
−
  <UninstallScripts>
+
<UninstallScripts>
−
  <File>'''softwareuninstall.sh'''</File>
+
<File>'''softwareuninstall.sh'''</File>
−
  </UninstallScripts>
+
</UninstallScripts>
−
  <RebootScripts>
+
<RebootScripts>
−
  <File>'''softwarereboot.sh'''</File>
+
<File>'''softwarereboot.sh'''</File>
−
  </RebootScripts>
+
</RebootScripts>
−
  ...
+
[...]
 
  </Software>
 
  </Software>
−
 
+
</source>
−
 
+
−
 
+
  
 
  .
 
  .
−
  |-- '''MainPackage'''
+
  |-- Name-service
 
  |  |-- aux.txt
 
  |  |-- aux.txt
 
  |  |-- aux2.txt
 
  |  |-- aux2.txt
Line 312: Line 372:
 
  |  |-- '''maininstall.sh'''
 
  |  |-- '''maininstall.sh'''
 
  |  |-- '''mainreboot.sh'''
 
  |  |-- '''mainreboot.sh'''
−
  |  `-- '''mainuninstall.sh'''
+
  |  |-- '''mainuninstall.sh'''
−
  |-- '''SoftwareName'''
+
  |  |-- svnpath.txt
−
  |  |-- softwarefile.txt
+
  |  |--doc
 +
|    \--api
 +
|        |--index.html
 +
|        \--others javadoc files
 +
|
 +
|-- Name-stubs
 +
|  |-- stubs.jar
 
  |  |-- '''softwareinstall.sh'''
 
  |  |-- '''softwareinstall.sh'''
 
  |  |-- '''softwarereboot.sh'''
 
  |  |-- '''softwarereboot.sh'''
−
  |  `-- '''softwareuninstall.sh'''
+
  |  |-- '''softwareuninstall.sh'''
−
  `-- profile.xml
+
  |  \-- svnpath.txt
 +
|
 +
|-- Name-test-suite
 +
|  |-- testsuite.jar
 +
|  \-- svnpath.txt
 +
|
 +
\-- profile.xml
  
  
  
 
Just remind the general rule for this section:
 
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.
+
'''The files must be go inside the directory with the name of the Package on Software Archive.'''
−
 
+
−
===Dependencies Section===
+
  
 +
===Specific Main Package Sections===
 +
====GARArchive Tag====
 +
<source lang=xml>
 
  <Main>
 
  <Main>
−
...
+
[...]
−
<Name>MainPackage</Name>
+
<Name>'''Name-service'''</Name>
−
...
+
[...]
−
<Dependencies>
+
<GARArchive>'''main.gar'''</GARArchive>
−
  <Dependency>
+
[...]
−
    <Service>
+
  <Main>
−
    <Class>MainDepClass</Class>
+
</source>
−
    <Name>MainDepName</Name>
+
−
    <Version>1.0</Version>
+
−
    </Service>
+
−
    <Package>DepPackage</Package>
+
−
    ''<Version>1.0</Version>''
+
−
    ''<Scope level="GHN"/>''
+
−
    ''<Optional>true</Optional>''
+
−
  </Dependency>
+
−
  </Dependencies>
+
−
  ...
+
−
  </Main>
+
  
 +
.
 +
|-- '''Name-service'''
 +
|  |-- aux.txt
 +
|  |-- aux2.txt
 +
|  |-- '''main.gar'''
 +
|  |-- maininstall.sh
 +
|  |-- mainreboot.sh
 +
|  |-- mainuninstall.sh
 +
|  |-- svnpath.txt
 +
|  |--doc
 +
|    \--api
 +
|        |--index.html
 +
|        \--others javadoc files
 +
|
 +
|-- Name-stubs
 +
|  |-- stubs.jar
 +
|  |-- softwareinstall.sh
 +
|  |-- softwarereboot.sh
 +
|  |-- softwareuninstall.sh
 +
|  \-- svnpath.txt
 +
|
 +
|-- Name-test-suite
 +
|  |-- testsuite.jar
 +
|  \-- svnpath.txt
 +
|
 +
\-- profile.xml
  
 +
The gar archive must go under the Main Package folder (i.e. ''Name-service'') on Software Archive
  
 +
===Specific Software Package Sections===
 +
 +
====Files Section====
 +
<source lang=xml>
 
  <Software>
 
  <Software>
−
  ...
+
[...]
−
  <Name>SoftwareName</Name>
+
<Name>'''Name-stubs'''</Name>
−
  ...
+
[...]
−
  <Dependencies>
+
<Files>
−
  <Dependency>
+
<File>'''stubs.jar'''</File>
−
    <Service>
+
</Files>
−
    <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>
 
  </Software>
−
 
+
</source>
−
Each Dependency is in term of package. Each package is identified by the Service information 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 [http://docs.codehaus.org/display/MAVEN/Dependency+Mediation+and+Conflict+Resolution] (please do not consider <qualifier> that is for internal use only).
+
−
 
+
−
Please consider this mapping between ETICS versioning [https://integration.wiki.d4science.research-infrastructures.eu/integration/index.php/Conventions#Version_numbers] 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 deploying. Allowed value are GHN,VRE,VO.
+
−
This information is used by the deployer.
+
−
 
+
−
 
+
−
The '''Optional''' tag is not mandatory and its absence corresponds to false value.
+
−
This allow the developer to specify if a dependency can be potentially optional during the deployment phase.
+
−
For instance, consider a service ''A'' designed to use service ''B'' when it is present or do by itself if service ''B'' is absent. In this case you can specify ''B'' as an Optional dependency.
+
−
 
+
−
===Specific Main Package Sections===
+
−
====GARArchive Tag====
+
−
<Main>
+
−
  ...
+
−
  <Name>'''MainPackage'''</Name>
+
−
  ...
+
−
  <GARArchive>'''main.gar'''</GARArchive>
+
−
  ...
+
−
<Main>
+
−
 
+
  
 
  .
 
  .
−
  |-- '''MainPackage'''
+
  |-- Name-service
 
  |  |-- aux.txt
 
  |  |-- aux.txt
 
  |  |-- aux2.txt
 
  |  |-- aux2.txt
−
  |  |-- '''main.gar'''
+
  |  |-- main.gar
 
  |  |-- maininstall.sh
 
  |  |-- maininstall.sh
 
  |  |-- mainreboot.sh
 
  |  |-- mainreboot.sh
−
  |  `-- mainuninstall.sh
+
  |  |-- mainuninstall.sh
−
  |-- SoftwareName
+
  |  |-- svnpath.txt
−
  |  |-- softwarefile.txt
+
  |  |--doc
 +
|    \--api
 +
|        |--index.html
 +
|        \--others javadoc files
 +
|
 +
|-- '''Name-stubs'''
 +
|  |-- '''stubs.jar'''
 
  |  |-- softwareinstall.sh
 
  |  |-- softwareinstall.sh
 
  |  |-- softwarereboot.sh
 
  |  |-- softwarereboot.sh
−
  |  `-- softwareuninstall.sh
+
  |  |-- softwareuninstall.sh
−
  `-- profile.xml
+
  |  \-- svnpath.txt
 +
|
 +
|-- Name-test-suite
 +
|  |-- testsuite.jar
 +
|  \-- svnpath.txt
 +
|
 +
\-- profile.xml
  
  
 +
'''The files must go under the folder with the name of the Software Package (i.e. Name-stubs) on Software Archive
 +
'''
  
−
The gar archive must go under the Main Package folder on Software Archive
+
====URI Tag====
  
−
===Specific Software Package Sections===
+
URI tag can be used instead of a Files tag whenever the actual content is stored remotely. This case is not showed in the example above.
−
====Files Section====
+
 
 +
<source lang=xml>
 +
<URI>http://dlib25.isti.cnr.it/maven/Service3.tar.gz<URI>
 +
</source>
 +
During the validation phase Software Repository tries to download the file. If it is not downloadable the validation fails.
 +
If you specify this tag you have to make sure this file will be available for a long period in the future. If not it would be better to include it directly on the Software Archive
 +
 
 +
==Test Suite==
 +
 
 +
Test suite is a mandatory piece of code used to test the Service at deployment time.
 +
Test suite have to be declared as a package in the Service Profile.
 +
This task should be accomplished adding a Package to the profile declaration. The name of this package should be ''<ServiceName>''-test-suite
 +
 
 +
<source lang=xml>
 
  <Software>
 
  <Software>
−
  ...
+
[...]
−
  <Name>'''SoftwareName'''</Name>
+
<Name>'''Name-test-suite'''</Name>
−
  ...
+
[...]
−
  <Files>
+
<Files>
−
  <File>'''softwarefile.txt'''</File>
+
<File>'''testsuite.jar'''</File>
−
  </Files>
+
</Files>
−
  ...
+
[...]
 
  </Software>
 
  </Software>
 +
</source>
  
 +
This service has to produce as ServiceArchive a tar.gz file with the following structure:
  
 
  .
 
  .
−
  |-- MainPackage
+
  |-- Name-service
 
  |  |-- aux.txt
 
  |  |-- aux.txt
 
  |  |-- aux2.txt
 
  |  |-- aux2.txt
Line 441: Line 521:
 
  |  |-- maininstall.sh
 
  |  |-- maininstall.sh
 
  |  |-- mainreboot.sh
 
  |  |-- mainreboot.sh
−
  |  `-- mainuninstall.sh
+
  |  |-- mainuninstall.sh
−
  |-- '''SoftwareName'''
+
  |  |-- svnpath.txt
−
  |  |-- '''softwarefile.txt'''
+
  |  |--doc
 +
|    \--api
 +
|        |--index.html
 +
|        \--others javadoc files
 +
|
 +
|-- Name-stubs
 +
|  |-- stubs.jar
 
  |  |-- softwareinstall.sh
 
  |  |-- softwareinstall.sh
 
  |  |-- softwarereboot.sh
 
  |  |-- softwarereboot.sh
−
  |  `-- softwareuninstall.sh
+
  |  |-- softwareuninstall.sh
−
  `-- profile.xml
+
  |  \-- svnpath.txt
 +
|
 +
|-- '''Name-test-suite'''
 +
|  |-- '''testsuite.jar'''
 +
|  \-- svnpath.txt
 +
|
 +
\-- profile.xml
  
 +
==Example==
  
 +
The following Profile describes a service and its stubs as two packages
  
−
The files must go under the folder with the name of the Software Package on Software Archive
+
<source lang=xml>
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<Resource xmlns:p1="http://schemas.xmlsoap.org/wsdl/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 +
<ID/>
 +
<Type>Service</Type>
 +
<Profile>
 +
<Description>Deployer: perform local deployment/undeployment of GCUBE packages</Description>
 +
<Class>VREManagement</Class>
 +
<Name>Deployer</Name>
 +
<Version>1.0.0</Version>
 +
<Dependencies>
 +
<Dependency>
 +
<Class>VREManagement</Class>
 +
<Name>SoftwareRepository</Name>
 +
<Version>1.0.0</Version>
 +
</Dependency>
 +
<Dependency>
 +
<Class>VREManagement</Class>
 +
<Name>VREManager</Name>
 +
<Version>1.0.0</Version>
 +
</Dependency>
 +
</Dependencies>
 +
<Packages>
 +
<Main deployable="false">
 +
<Name>Deployer-service</Name>
 +
<Version>1.0.2</Version>
 +
<Mandatory level="GHN"/>
 +
<Shareable level="VO"/>
 +
<GHNRequirements>
 +
<Requirement category="Site"  requirement="string" value="java1.5" operator="ge"/>
 +
</GHNRequirements>
 +
<Dependencies>
 +
<Dependency>
 +
<Service>
 +
<Class>VREManagement</Class>
 +
<Name>Deployer</Name>
 +
<Version>1.0.0</Version>
 +
</Service>
 +
<Package>Deployer-stubs</Package>
 +
<Version>1.0.2</Version>
 +
<Scope level="GHN"/>
 +
<Optional>false</Optional>
 +
</Dependency>
 +
<Dependency>
 +
<Service>
 +
<Class>VREManagement</Class>
 +
<Name>SoftwareRepository</Name>
 +
<Version>1.0.0</Version>
 +
</Service>
 +
<Package>SoftwareRepository-stubs</Package>
 +
<Version>[1.0.3,1.1.0)</Version>
 +
<Scope level="GHN"/>
 +
<Optional>false</Optional>
 +
</Dependency>
 +
</Dependencies>
 +
<GARArchive>org.gcube.common.vremanagement.deployer.gar</GARArchive>
 +
<PortType>
 +
<Name>gcube/common/vremanagement/Deployer</Name>
 +
<Security/>
 +
<WSDL>...</WSDL>
 +
</PortType>
 +
</Main>
 +
<Software>
 +
<Name>Deployer-stubs</Name>
 +
<Version>1.0.2</Version>
 +
<MultiVersion value="true"/>
 +
<Mandatory level="GHN"/>
 +
<Shareable level="VO"/>
 +
<GHNRequirements>
 +
<Requirement category="Site" operator="ge" requirement="string" value="java1.5"/>
 +
</GHNRequirements>
 +
<Type>library</Type>
 +
<Files>
 +
<File>org.gcube.common.vremanagement.deployer.stubs.jar</File>
 +
</Files>
 +
</Software>
 +
<Software>
 +
<Name>Deployer-test-suite</Name>
 +
<Version>1.0.1</Version>
 +
<MultiVersion value="true"/>
 +
<Shareable level="VO"/>
 +
<GHNRequirements>
 +
<Requirement category="Site" operator="ge" requirement="string" value="java1.5"/>
 +
</GHNRequirements>
 +
<Type>application</Type>
 +
<Files>
 +
<File>lib/org.gcube.common.vremanagement.deployer.testsuite.jar</File>
 +
</Files>
 +
</Software>
 +
</Packages>
 +
</Profile>
 +
</Resource>
 +
</source>
  
 +
This service has to produce a SoftwareArchive (a tar.gz) file with the following structure:
  
−
====URI Tag====
+
.
 +
|
 +
|--Deployer-service
 +
|  |--org.gcube.common.vremanagement.deployer.gar
 +
|  |--svnpath.txt
 +
|  \--doc
 +
|    \--api
 +
|        |--index.html
 +
|        \--others javadoc files
 +
|
 +
|--Deployer-stubs
 +
|  |--org.gcube.common.vremanagement.deployer.stubs.jar
 +
|  \--svnpath.txt
 +
|
 +
|--Deployer-test-suite
 +
|  \--org.gcube.common.vremanagement.deployer.testsuite.jar
 +
|
 +
\--profile.xml
 +
 
 +
 
 +
 
 +
The ETICS configuration (''org.gcube.vre-management.deployer-'''servicearchive''''') is:
  
−
URI tag can be used instead of a Files tag whenever the actual content is stored remotely. This case is not showed in the example above.
 
  
 
<pre>
 
<pre>
−
<URI>http://dlib25.isti.cnr.it/maven/Service3.tar.gz<URI>
+
 
 +
INIT:  
 +
mkdir -p ${prefix};
 +
mkdir -p ${prefix}/Deployer-service;
 +
mkdir -p ${prefix}/Deployer-stubs;
 +
mkdir -p ${prefix}/Deployer-test-suite;
 +
 
 +
 
 +
INSTALL:
 +
cp ${org.gcube.vre-management.deployer.moduleDir}/etc/profile.xml ${prefix};
 +
 
 +
cp ${org.gcube.vre-management.deployer.moduleDir}/lib/*.gar ${prefix}/Deployer-service;
 +
cp -r ${org.gcube.vre-management.deployer.moduleDir}/doc ${prefix}/Deployer-service;
 +
echo ${org.gcube.vre-management.deployer.vcsroot}/${org.gcube.vre-management.deployer.tag} > ${prefix}/Deployer-service/svnpath.txt;
 +
 
 +
cp ${org.gcube.vre-management.deployer-stubs.moduleDir}/lib/org.gcube.common.vremanagement.deployer.stubs.jar ${prefix}/Deployer-stubs;
 +
echo ${org.gcube.vre-management.deployer-stubs.vcsroot}/${org.gcube.vre-management.deployer-stubs.tag} > ${prefix}/Deployer-stubs/svnpath.txt;
 +
 
 +
cp ${org.gcube.vre-management.deployer-test-suite.moduleDir}/lib/org.gcube.common.vremanagement.deployer.testsuite.jar ${prefix}/Deployer-test-suite;
 +
echo ${org.gcube.vre-management.deployer-test-suite.vcsroot}/${org.gcube.vre-management.deployer-test-suite.tag} > ${prefix}/Deployer-test-suite/svnpath.txt;
 
</pre>
 
</pre>
  
−
During the validation phase Software Repository tries to download the file. If it is not downloadable the validation fails.
 
−
If you specify this tag you have to make sure this file will be available for a long period in the future. If not it would be better to include it directly on the Software Archive
 
  
−
== Report Generation ==
+
The ''servicearchive'' configuration is related to the ''service'' configuration that should be as following:
  
−
During validation phase a report is produced.
+
<pre>
−
The report is produced in XML format and through  an XSLT transformation is made available in an human oriented view.
+
INIT:  
−
The report include information about:
+
mkdir -p ${prefix}
−
* '''URL''' where the Software Repository download the Software Archive to store
+
 
−
* '''StartTime''' and '''EndTime''' of the validation process
+
COMPILE:
−
* '''ServiceClass''' value is the validation is successful or a message about the error
+
ant -Detics.build=true garService
−
* '''ServiceName''' value is the validation is successful or a message about the error
+
 
−
* '''Version''' value used for this Service or an error message if the version is not supplied
+
DOC:
−
* '''ServiceID''' unique ID assigned to the Service
+
ant -Detics.build=true doc
−
* '''Description''' the description filled in the profile (provided with the API, provided with the profile) or an error message if no description is supplied
+
 
−
* '''Operation''' information about the operation done with this Service: UPDATE of already stored version, NEW store
+
INSTALL:
−
* '''Scope''' the Context scope where the service will be publish or an error information
+
cp -R ${moduleDir}/lib/*.gar ${prefix}; cp -R ${moduleDir}/doc ${prefix}
−
* '''Files''' information regarding the file declared in the Service Profile, if they are found in the right location or an error indicating missing file in the directory with the name of the package it belongs
+
</pre>

Latest revision as of 18:14, 11 July 2013

Short background

A 'Service' in gCube is a software system which delivers functionality. It is composed by a set of related 'Packages'.

In the gCube context, a 'Package' is a 'piece of software' that can be deployed into a gHN. Packages are single tarballs, compliant with the Package Model, that contains the files to be installed, along with rules describing software/packages dependencies, deployment instructions and so on.

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: 

.
|--<PackageName>(Main)
|  |--<GARArchive>
|  |--svnpath.txt
|  |--<additional files>
|  |--doc
|     \--api
|        |- index.html
|        \- others javadoc files
|
|
|--<PackageName>
|  |--<LibraryFile>
|  |--svnpath.txt
|  |--<additional files>
|  \--doc
|     \--api
|        |-- index.html
|        \-- others javadoc files
|
|....
|
|
|--<PackageName>
|  |--<LibraryFile>
|  |--svnpath.txt
|  |--<additional files>
|  \--doc
|     \--api
|        |-- index.html
|        \-- others javadoc files
|
|-- README
|-- MANTAINERS
|-- CHANGELOG
|-- INSTALL
|-- LICENSE
|
\-profile.xml

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)

In Main packages the 'doc/api' folder with javadoc is mandatory, optional for the others packages.

The 'svnpath.txt' file is mandatory for each packages and contains the link to the source code or to the library download location in cases of external library not open source.

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.
Copy the javadoc to the appropriate <PackageName> directory.
Furthermore echo command with vcsroot link have to be redirected to a file 'svnpath.txt' in the appropriate <PackageName> directory.

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

To better understand the example below check the Service Profile specification.

Service Profile 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.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.0</Version>
	 		</Dependency>
		</Dependencies>
		<Packages>
			<Main>
				<Description>Main Package Description</Description>
	 			<Name>Name-service</Name>
	 			<Version>1.1.0</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.0</Version>						
	 					</Service>
	 					<Package>DepPackage</Package>
	 					<Version>1.0.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>Name-stubs</Name>
				<Version>1.0.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.0</Version>
						</Service>
						<Package>SoftwarePackage</Package>
						<Version>1.0.0</Version>
						<Scope level="VO"/>
						<Optional>false</Optional>
					</Dependency>
				</Dependencies>
				<SpecificData>text</SpecificData>
				<Type>library</Type>
				<Files>
					<File>stubs.jar</File>
				</Files>
			</Software>
			<Software>
				<Description>Test Suite</Description>
				<Name>Name-test-suite</Name>
				<Version>1.0.0</Version>
				[...]
				<Type>library</Type>
				<Files>
					<File>testsuite.jar</File>
				</Files>
			</Software>
		</Packages>
		<SpecificData>text</SpecificData>
	</Profile>
</Resource>


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

.
|-- Name-service
|   |-- aux.txt
|   |-- aux2.txt
|   |-- main.gar
|   |-- maininstall.sh
|   |-- mainreboot.sh
|   |-- mainuninstall.sh
|   |-- svnpath.txt
|   |--doc
|     \--api
|        |--index.html
|        \--others javadoc files
|
|-- Name-stubs
|   |-- stubs.jar
|   |-- softwareinstall.sh
|   |-- softwarereboot.sh
|   |-- softwareuninstall.sh
|   \-- svnpath.txt
|
|-- Name-test-suite
|   |-- testsuite.jar
|   \-- svnpath.txt
|
\-- profile.xml

Software Archive Validation Process

The Software Archive validation process relies on the information contained in the following sections of the Service Profile to validate the actual constituents of the Software Archive.

Description Tag

The description supplied in the store(StoreMessage) method has priority with respect to 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 no 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>
.
|-- Name-service
|   |-- aux.txt
|   |-- aux2.txt
|   |-- main.gar
|   |-- maininstall.sh
|   |-- mainreboot.sh
|   |-- mainuninstall.sh
|   |-- svnpath.txt
|   |--doc
|     \--api
|        |--index.html
|        \--others javadoc files
|
|-- Name-stubs
|   |-- stubs.jar
|   |-- softwareinstall.sh
|   |-- softwarereboot.sh
|   |-- softwareuninstall.sh
|   \-- svnpath.txt
|
|-- Name-test-suite
|   |-- testsuite.jar
|   \-- svnpath.txt
|
\-- profile.xml


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

InstallScripts/UninstallScripts/RebootScripts Tag

 <Main>
  ...
  <Name>'''Name-service'''</Name>
 	[...]
 	<InstallScripts>
 		<File>'''maininstall.sh'''</File>
 	</InstallScripts>
 	<UninstallScripts>
 		<File>'''mainuninstall.sh'''</File>
 	</UninstallScripts>
 	<RebootScripts>
 		<File>'''mainreboot.sh'''</File>
 	</RebootScripts>
 	[...]
 </Main>
 <Software>
 	[...]
 	<Name>'''Name-stubs'''</Name>
 	[...]
 	<InstallScripts>
 		<File>'''softwareinstall.sh'''</File>
 	</InstallScripts>
 	<UninstallScripts>
 		<File>'''softwareuninstall.sh'''</File>
 	</UninstallScripts>
 	<RebootScripts>
 		<File>'''softwarereboot.sh'''</File>
 	</RebootScripts>
 	[...]
 </Software>
.
|-- Name-service
|   |-- aux.txt
|   |-- aux2.txt
|   |-- main.gar
|   |-- maininstall.sh
|   |-- mainreboot.sh
|   |-- mainuninstall.sh
|   |-- svnpath.txt
|   |--doc
|     \--api
|        |--index.html
|        \--others javadoc files
|
|-- Name-stubs
|   |-- stubs.jar
|   |-- softwareinstall.sh
|   |-- softwarereboot.sh
|   |-- softwareuninstall.sh
|   \-- svnpath.txt
|
|-- Name-test-suite
|   |-- testsuite.jar
|   \-- svnpath.txt
|
\-- 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.

Specific Main Package Sections

GARArchive Tag

 <Main>
 	[...]
 	<Name>'''Name-service'''</Name>
 	[...]
 	<GARArchive>'''main.gar'''</GARArchive>
 	[...]
 <Main>
.
|-- Name-service
|   |-- aux.txt
|   |-- aux2.txt
|   |-- main.gar
|   |-- maininstall.sh
|   |-- mainreboot.sh
|   |-- mainuninstall.sh
|   |-- svnpath.txt
|   |--doc
|     \--api
|        |--index.html
|        \--others javadoc files
|
|-- Name-stubs
|   |-- stubs.jar
|   |-- softwareinstall.sh
|   |-- softwarereboot.sh
|   |-- softwareuninstall.sh
|   \-- svnpath.txt
|
|-- Name-test-suite
|   |-- testsuite.jar
|   \-- svnpath.txt
|
\-- profile.xml

The gar archive must go under the Main Package folder (i.e. Name-service) on Software Archive

Specific Software Package Sections

Files Section

 <Software>
 	[...]
 	<Name>'''Name-stubs'''</Name>
 	[...]
 	<Files>
 		<File>'''stubs.jar'''</File>
 	</Files>
 	[...]
 </Software>
.
|-- Name-service
|   |-- aux.txt
|   |-- aux2.txt
|   |-- main.gar
|   |-- maininstall.sh
|   |-- mainreboot.sh
|   |-- mainuninstall.sh
|   |-- svnpath.txt
|   |--doc
|     \--api
|        |--index.html
|        \--others javadoc files
|
|-- Name-stubs
|   |-- stubs.jar
|   |-- softwareinstall.sh
|   |-- softwarereboot.sh
|   |-- softwareuninstall.sh
|   \-- svnpath.txt
|
|-- Name-test-suite
|   |-- testsuite.jar
|   \-- svnpath.txt
|
\-- profile.xml


The files must go under the folder with the name of the Software Package (i.e. Name-stubs) on Software Archive

URI Tag

URI tag can be used instead of a Files tag whenever the actual content is stored remotely. This case is not showed in the example above. 

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

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

Test Suite

Test suite is a mandatory piece of code used to test the Service at deployment time. Test suite have to be declared as a package in the Service Profile. This task should be accomplished adding a Package to the profile declaration. The name of this package should be <ServiceName>-test-suite 

 <Software>
 	[...]
 	<Name>'''Name-test-suite'''</Name>
 	[...]
 	<Files>
 		<File>'''testsuite.jar'''</File>
 	</Files>
 	[...]
 </Software>

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

.
|-- Name-service
|   |-- aux.txt
|   |-- aux2.txt
|   |-- main.gar
|   |-- maininstall.sh
|   |-- mainreboot.sh
|   |-- mainuninstall.sh
|   |-- svnpath.txt
|   |--doc
|     \--api
|        |--index.html
|        \--others javadoc files
|
|-- Name-stubs
|   |-- stubs.jar
|   |-- softwareinstall.sh
|   |-- softwarereboot.sh
|   |-- softwareuninstall.sh
|   \-- svnpath.txt
|
|-- Name-test-suite
|   |-- testsuite.jar
|   \-- svnpath.txt
|
\-- profile.xml

Example

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

<?xml version="1.0" encoding="UTF-8"?>
<Resource xmlns:p1="http://schemas.xmlsoap.org/wsdl/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<ID/>
	<Type>Service</Type>
	<Profile>
		<Description>Deployer: perform local deployment/undeployment of GCUBE packages</Description>
		<Class>VREManagement</Class>
		<Name>Deployer</Name>
		<Version>1.0.0</Version>
		<Dependencies>
			<Dependency>			
					<Class>VREManagement</Class>
					<Name>SoftwareRepository</Name>
					<Version>1.0.0</Version>
			</Dependency>											
			<Dependency>			
					<Class>VREManagement</Class>
					<Name>VREManager</Name>
					<Version>1.0.0</Version>
			</Dependency>
		</Dependencies>
		<Packages>
			<Main deployable="false">
				<Name>Deployer-service</Name>
				<Version>1.0.2</Version>
				<Mandatory level="GHN"/>
				<Shareable level="VO"/>
				<GHNRequirements>
					<Requirement category="Site"  requirement="string" value="java1.5" operator="ge"/>
				</GHNRequirements>
				<Dependencies>
					<Dependency>
						<Service>
							<Class>VREManagement</Class>
							<Name>Deployer</Name>
							<Version>1.0.0</Version>
						</Service>
						<Package>Deployer-stubs</Package>
						<Version>1.0.2</Version>
						<Scope level="GHN"/>
						<Optional>false</Optional>
					</Dependency>
					<Dependency>
						<Service>
							<Class>VREManagement</Class>
							<Name>SoftwareRepository</Name>
							<Version>1.0.0</Version>						
						</Service>
						<Package>SoftwareRepository-stubs</Package>
						<Version>[1.0.3,1.1.0)</Version>
						<Scope level="GHN"/>
						<Optional>false</Optional>
					</Dependency>
				</Dependencies>
				<GARArchive>org.gcube.common.vremanagement.deployer.gar</GARArchive>
				<PortType>
						<Name>gcube/common/vremanagement/Deployer</Name>
						<Security/>			
						<WSDL>...</WSDL>
				</PortType>					
			</Main>
			<Software>
				<Name>Deployer-stubs</Name>
				<Version>1.0.2</Version>
				<MultiVersion value="true"/>
				<Mandatory level="GHN"/>
				<Shareable level="VO"/>
				<GHNRequirements>
					<Requirement category="Site" operator="ge" requirement="string" value="java1.5"/>
				</GHNRequirements>
				<Type>library</Type>
				<Files>
					<File>org.gcube.common.vremanagement.deployer.stubs.jar</File>
				</Files>
			</Software>
			<Software>
				<Name>Deployer-test-suite</Name>
				<Version>1.0.1</Version>
				<MultiVersion value="true"/>				
				<Shareable level="VO"/>
				<GHNRequirements>
					<Requirement category="Site" operator="ge" requirement="string" value="java1.5"/>
				</GHNRequirements>
				<Type>application</Type>
				<Files>
					<File>lib/org.gcube.common.vremanagement.deployer.testsuite.jar</File>
				</Files>
			</Software>
		</Packages>
	</Profile>
</Resource>

This service has to produce a SoftwareArchive (a tar.gz) file with the following structure: 

.
|
|--Deployer-service
|  |--org.gcube.common.vremanagement.deployer.gar
|  |--svnpath.txt
|  \--doc
|     \--api
|        |--index.html
|        \--others javadoc files
|
|--Deployer-stubs
|  |--org.gcube.common.vremanagement.deployer.stubs.jar
|  \--svnpath.txt
|
|--Deployer-test-suite
|  \--org.gcube.common.vremanagement.deployer.testsuite.jar
|
\--profile.xml


The ETICS configuration (org.gcube.vre-management.deployer-servicearchive) is: 



INIT: 
mkdir -p ${prefix};
mkdir -p ${prefix}/Deployer-service;
mkdir -p ${prefix}/Deployer-stubs;
mkdir -p ${prefix}/Deployer-test-suite;


INSTALL:
cp ${org.gcube.vre-management.deployer.moduleDir}/etc/profile.xml ${prefix};

cp ${org.gcube.vre-management.deployer.moduleDir}/lib/*.gar ${prefix}/Deployer-service;
cp -r ${org.gcube.vre-management.deployer.moduleDir}/doc ${prefix}/Deployer-service;
echo ${org.gcube.vre-management.deployer.vcsroot}/${org.gcube.vre-management.deployer.tag} > ${prefix}/Deployer-service/svnpath.txt;

cp ${org.gcube.vre-management.deployer-stubs.moduleDir}/lib/org.gcube.common.vremanagement.deployer.stubs.jar ${prefix}/Deployer-stubs;
echo ${org.gcube.vre-management.deployer-stubs.vcsroot}/${org.gcube.vre-management.deployer-stubs.tag} > ${prefix}/Deployer-stubs/svnpath.txt;

cp ${org.gcube.vre-management.deployer-test-suite.moduleDir}/lib/org.gcube.common.vremanagement.deployer.testsuite.jar ${prefix}/Deployer-test-suite;
echo ${org.gcube.vre-management.deployer-test-suite.vcsroot}/${org.gcube.vre-management.deployer-test-suite.tag} > ${prefix}/Deployer-test-suite/svnpath.txt;


The servicearchive configuration is related to the service configuration that should be as following: 

INIT:    
mkdir -p ${prefix}

COMPILE:
ant -Detics.build=true garService

DOC:
ant -Detics.build=true doc

INSTALL:
cp -R ${moduleDir}/lib/*.gar ${prefix}; cp -R ${moduleDir}/doc ${prefix}
Retrieved from "https://wiki.gcube-system.org/index.php?title=Software_Archive_Specification&oldid=19183"