Difference between revisions of "Service Archive Specification"

Latest revision as of 12:34, 29 August 2008

Short background

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

In the D4Science 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 'Service Archive' should be delivered.

Structure

A Service 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>(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



/.....

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 svn source code.

Creating Service 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 to automatically create Service Archives

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

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

<?xml version="1.0" encoding="UTF-8"?>
<Resource>
    <ID>gfgdf80-131b-11db-90fgf98-dgfgfgf66ed3f</ID>
    <Type>Service</Type>
    <Profile>
        <Class>InformationSystem</Class>
        <Name>IS-Registry</Name>
        <Version>1.0.0</Version>
        <Packages>
            <Main>
		<Name>IS-Registry-service</Name>
		<Version>1.0</Version>
		<Mandatory level="VO"/>
		<Shareable level="VO"/>
		<GHNRequirements>
			<Requirement category="Site" requirement="string" value="java1.5" operator="ge"/>
		</GHNRequirements>
		<Dependencies>
			<Dependency>
				<Service>
				   <Class>InformationSystem</Class>
		 		   <Name>IS-Registry</Name>
		 		   <Version>1.0.0</Version>
				</Service>
				<Package>IS-Registry-stubs</Package>
				<Version>1.0.0</Version>
				<Scope level="GHN"/>
				<Optional>false</Optional>
			</Dependency>
		</Dependencies>
		<GARArchive>org.gcube.informationsystem.registry.gar</GARArchive>
            	<PortType>
                	<Name>gcube/informationsystem/registry/registryFactory</Name>
                    	<Security/>			
			<WSDL/>
            	</PortType>
            	<PortType>
                	<Name>gcube/informationsystem/registry/registry</Name>
                    	<Security/>			
			<WSDL/>
            	</PortType>
            </Main>
            <Software>
            	<Name>IS-Registry-stubs</Name>
		<Version>1.0</Version>
		<MultiVersion value="true"/>
		<Mandatory level="GHN"/>
		<Shareable level="VO"/>
		<GHNRequirements>
			<Requirement category="Site" operator="ge" requirement="string" value="java1.5"/>
		</GHNRequirements>
		<SpecificData/>
		<Type>library</Type>
		<Files>
			<File>org.gcube.informationsystem.registry.stubs.jar</File>
		</Files>
	   </Software>           
        </Packages>
    </Profile>
</Resource>

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

|--profile.xml
|
|
|--IS-Registry-service
|  |--org.gcube.informationsystem.registry.gar
|  |--svnpath.txt
|  \--doc
|     \--api
|        |--index.html
|        \--others javadoc files
|
|
\--IS-Registry-stubs
   |--org.gcube.informationsystem.registry.stubs.jar
   \--svnpath.txt

For this service archive the ETICS configuration is

INIT: 
mkdir -p ${prefix};
mkdir -p ${prefix}/IS-Registry-service;
mkdir -p ${prefix}/IS-Registry-stubs;


INSTALL:
cp ${org.gcube.information-system.registry.moduleDir}/etc/profile.xml ${prefix};
cp ${org.gcube.information-system.registry-stubs.moduleDir}/lib/org.gcube.informationsystem.registry.stubs.jar ${prefix}/IS-Registry-stubs;
cp ${org.gcube.information-system.registry.moduleDir}/lib/*.gar ${prefix}/IS-Registry-service;
cp -r ${org.gcube.information-system.registry.moduleDir}/doc ${prefix}/IS-Registry-service;
echo ${org.gcube.information-system.registry.vcsroot}/${org.gcube.information-system.registry.tag} > ${prefix}/IS-Registry-service/svnpath.txt;
echo ${org.gcube.information-system.registry-stubs.vcsroot}/${org.gcube.information-system.registry-stubs.tag} > ${prefix}/IS-Registry-stubs/svnpath.txt;