View source for Profile Specification

= Preliminary definitions =

== gCube resources and profiles ==

A ''gCube Resource'' is anything whose related information can be gathered, stored, monitored, and disseminated in order to provide the valuable amount of knowledge needed during the creation and management of a VRE as well as to operate an entire gCube infrastructure. In order to be appropriately managed and discovered, a gCube resource has to be described by creating a ''profile document'' compliant with its XML schema.
The following resources have been identified:

* [[Profile_Specification#The_gHN_resource|gHN]] ([[node-schema|XSD]])
* [[Profile_Specification#The_Service_resource|Service]] ([[service-schema|XSD]])
* Running Instance ([[runninginstance-schema|XSD]])
* External Running Instance ([[externalrunninginstance-schema|XSD]])
* VRE ([[vre-schema|XSD]])
* Collection ([[collection-schema|XSD]])
* Metadata Collection ([[metadatacollection-schema|XSD]])
* Transformation Program ([[transformationprogram-schema|XSD]])
* CS ([[cs-schema|XSD]])
* CSInstance ([[csinstance-schema|XSD]])
* gLite resource ([[glite-schema|XSD]])

Such resources can be combined or created at VRE creation time in order to set up a new Virtual Research Environment.

= The gHN resource =
A Grid Hosting Node (shortly, a gHN) is the resource modelling a node of an infrastructure able to host gCube Running Instances. 

[TBC]

= The Service resource =

Usually, a ''Service'' is defined as a software system that delivers functionalities. In gCube, a Service is a not-empty set of related [[Profile_Specification#PackagesList_section| Packages]] (connected through dependencies) forming an unique logical entity. A Package is the smallest installable unit of software that can be deployed on a [[Profile_Specification#The_gHN_resource|gHN]] (e.g. a JAR o a GAR archive). Packages are the way in which the software needed to set up a VRE has to prepared in order to be used and stored in the system. 
Once the service components have been developed, they must be described by compiling the service profile.

===== Package types =====


Concretely, a Package is a “piece of software” that can be deployed on a [[Profile_Specification#The_gHN_resource|gHN]]. A Package can be:
* a ''[[Profile_Specification#MainPackage|MainPackage]]'', representing a package that once deployed produces a WSRF Service (a service able to manage stateful resources following the WS-Resource patterns);
* a ''[[Profile_Specification#Software|Software]]'', a software library (typically composed by one or more JAR archives) offering functionality for interacting with Service or a thirdy party software distributed with the service that can be dynamically deployed;

About how to define a package, see the [[Profile_Specification#Packages_section| Packages section]].

===== Composition =====
The set of Packages forming a Service is composed by:
# one and only one [[Profile_Specification#MainPackage|MainPackage]] representing the gCore compliant Web-Service
# an arbitrary number of other Packages of different types logically related (even if not used) to the [[Profile_Specification#MainPackage|MainPackage]]


The "main" part of a Service is, of course, the [[Profile_Specification#MainPackage|MainPackage]] from which the related Running Instance resource is generated. The other packages can be:
* helper modules developed and used by the [[Profile_Specification#MainPackage|MainPackage]] i.e stubs
* helper modules developed and distributed with the [[Profile_Specification#MainPackage|MainPackage]] in order to be used by other Services to interact with a Running Instance of the Service. e.g. test-suite


We enforce the use of this convection:

Main Package Name: '''''ServiceName''-service'''

Stubs: '''''ServiceName''-stubs'''

Test suite: '''''ServiceName''-test-suite'''




Example if the ''ServiceName'' is '''''Deployer''''', we will use:

Main Package Name: '''Deployer-service'''

Stubs: '''Deployer-stubs'''

Test suite: '''Deployer-test-suite'''

===== How to behave with library =====

{| align=center border=1
| ||'''Package in a Separated Software Archive''' || '''Appear as package in Service Profile'''
|- 
| Stubs library || NO (Packaged with Service) || YES
|-
| Service specific library || NO (Packaged with Service) || YES
|-
| D4Science library not service specific || YES (''D4Science Service Class'') || YES
|-
| Service Indipendent (Deployable) || YES (''ExternalSoftware'' Class) || YES
|-
| Service Indipendent (NOT Deployable) || NO (Contained in GAR archive) || NO
|}


====== Example of profile for D4Science library not service specific ======

 <Resource>
 	<ID></ID>
 	<Type>Service</Type>
 	<Profile>
 		<Description>....</Description> 
 		<Class>''D4Science Service Class''</Class>
 		<Name>''LibraryName''</Name>
 		<Version>xx.xx.xx</Version>
 		…
 		<Packages>
 			<Software>
 				<Description></Description>
 				<Name>''LibraryName''</Name>
 				<Version>xx.xx.xx</Version>
 				…
 			</Software>
 		</Packages>
 	</Profile>
 </Resource>



'''''D4Science Service Class''''' have to be replaced with the name of Service Class the library belong to.
It doesn't mean to use "D4Science Service Class" o "D4Science Class" as string.


'''Example:'''



 <Resource>
 	<ID></ID>
 	<Type>Service</Type>
 	<Profile>
 		<Description>....</Description>
 		<Class>Search</Class>
 		<Name>ResultSetLibrary</Name>
 		<Version>1.0.0</Version>
 		<Packages>
 			<Software>
 				<Description>RS Library</Description>
 				<Name>ResultSetLibrary</Name>
 				<Version>1.0.0</Version>
 				...
 			</Software>
 		</Packages>
 	</Profile>
 </Resource>

====== Example of profile for Service Indipendent (Deployable) library ======


 <Resource>
 	<ID></ID>
 	<Type>Service</Type>
 	<Profile>
 		<Description></Description> 
 		<Class>'''ExternalSoftware'''</Class>
 		<Name>''LibraryName''</Name>
 		<Version>''LibraryVersion''</Version>
 		…
 	<Packages>
 		<Software>
 			<Description></Description>
 			<Name>''LibraryName''</Name>
 			<Version>''LibraryVersion''</Version>
 			…
 		</Software>
 	</Packages>
 </Resource>


'''Example:'''

 <Resource>
         <ID></ID>
         <Type>Service</Type>
         <Profile>
                 <Description>Commons HTTP Client library</Description>
                 <Class>ExternalSoftware</Class>
                 <Name>commons-httpclient</Name>
                 <Version>3.0.1</Version>
                 <Packages>
                         <Software deployable="true">
                                 <Description>Commons HTTP Client library</Description>
                                 <Name>commons-httpclient</Name>
                                 <Version>3.0.1</Version>
                                 <MultiVersion value="true"/>
                                 <Mandatory level="VO"/>
                                 <Shareable level="VO"/>
                                 <Type>library</Type>
                                 <Files>
                                         <File>commons-httpclient-3.0.1.jar</File>
                                 </Files>
                         </Software>
                 </Packages>
                 <SpecificData></SpecificData>
         </Profile>
 </Resource>

===== How to specify dependencies =====
A package, once deployed, can rely on other software to perform its activities. Let's see how to specify these dependencies by distinguishing among:
* software developed within this service (this is the case of a stub library, for instance)
*:&rarr; the software has to be declared as [[Profile_Specification#Software|Software]] and the dependency is specified as [[Profile_Specification#Dependencies_2|package Dependency]]
* software developed and distributed within other gCube services
*:&rarr; the dependency is specified as [[Profile_Specification#Dependencies_2|package Dependency]] against a package defined in another Service profile
* thirdy party deployable software used only by this service
*:&rarr; the software has to be declared as [[Profile_Specification#Software|Software]] and the dependency is specified as [[Profile_Specification#Dependencies_2|package Dependency]]
* thirdy party deployable software used by other services
*:&rarr; the software has to be uploaded in the ETICS repository, the package has to be declared as  [[Profile_Specification#Software|Software]] and the dependency is specified as [[Profile_Specification#Dependencies_2|package Dependency]]
* thirdy party software that is not dynamically deployable
*:&rarr; the software has to be manually installed, the label has to be manually declared in the gHN profile (by the gHN owner) and the dependency is specified as [[Profile_Specification#GHNRequirements|gHN Requirement]]

== How to compile a Service profile ==

The following example shows the common elements that compose the Service profile. The Package-specific sections are explained apart later.
<pre>
<Resource xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<UniqueID/>
	<Type>Service</ResourceType>
	<Scopes>
	</Scopes>
	<Profile>
		<Description> ...a description...</Description>
		<Class> ... a class name... </Class>
		<Name>...a service name...</Name>
		<Version>\d{1,2}+.\d{1,2}+.\d{1,2}</Version>		
		<Dependencies>
			<Dependency>
				<Class>...</Class>
				<Name>...</Name>
				<Version>\d{1,2}+.\d{1,2}+.\d{1,2}</Version>
			</Dependency>
			<Dependency>
				<Class>...</Class>
				<Name>...</Name>
				<Version>\d{1,2}+.\d{1,2}+.\d{1,2}</Version>
			</Dependency>
			<Dependency>
				<Class>...</Class>
				<Name>...</Name>
				<Version>\d{1,2}+.\d{1,2}+.\d{1,2}</Version>
			</Dependency>
		</Dependencies>
		<SpecificData/>
		<Packages>
			[...]
		</Packages>
	</Profile>
</Resource>
</pre>

=== Common elements ===

==== Class ====
The class of a service is its functional area. It's a free text field that should group packages belonging the same logical functionalities.

==== Name ====
The Name is an arbitrary string that uniquely identifies the service within a service class.

==== Version ====
The service version must be in the format: \d{1,2}+.\d{1,2}+.\d{1,2}

For the moment this version number have to be fixed to '''1.0.0'''

==== Dependencies  ====
A gCube service is part of a complex system and it makes use of other services. At VRE definition time, firstly, it is compiled the list of services that satisfy the VRE definition criteria and, then, such a list is completed with the other services that allow the first ones to work properly. Therefore it is needed that a service declares which other services it will need to be available in order to do its work once it is deployed.

==== Packages section ====
This element groups an unbounded sequence of Package-derived elements. Each element describes a package that comes with the service. The structure of a Package element includes an initial common part and a package-specific part rooted by an element named as the service type ([[Profile_Specification#MainPackage|MainPackage]] and [[Profile_Specification#Software|Software]]).
The only constraint is that one and only one [[Profile_Specification#MainPackage|MainPackage]] element is accepted in the list.
 
===== Common elements =====

====== Example ======
The following example shows the elements of a Package definition common to both types of Package.
 <Packages>
 	<Main deployable="true">
 		<Name>Deployer-service</Name>
 		<Version>1.0.0</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.0</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.4</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>
 </Packages>

====== PackageName ======
An arbritrary string that uniquely identifies the package within this service.

====== Version ======
The version of the package. It has to be in the format: \d{1,2}+.\d{1,2}+.\d{1,2} (e.g. 1.0.1 or 1.11.0)

====== Mandatory ======
If the ''Mandatory'' element is declared, it states when the package has to be deployed by default. The value of the attribute ''level'' defines at which level the package is mandatory. Accepted values are: ''GHN'', ''VO'' and ''VRE''. For instance, stating that a package is mandatory at VO level means that each time a new VO is created the package MUST be deployed.

If the element is not declared, the package is assumed to be not mandatory at any level by default.

====== Shareable ======
If the ''Shareable'' element is declared, it states if the package can be shared across multiple Scopes. The value of the attribute ''level'' defines at which level the package is shareable. Accepted values are: ''VO'' and ''VRE''.

If the element is not declared, the package is assumed to be shareable at any scope level by default.

====== InstallScripts ====== 
This set of scripts are executed before the deployment of the package. They can be used to prepare the environment for the package execution (create a file system structure, install third parties software). The current folder where they are executed is the one where it is places. So, one can navigate the package tree with relative paths starting from the install script folder.

====== UninstallScripts ====== 
This set of scripts are executed after the undeployment of the package. They can be used to clean up the environment. The current folder where they are executed is the one where the package is downloaded and uncompressed.

====== RebootScripts ====== 
This set of scripts are executed before each container startup.

====== Dependencies ======
The dependencies of the package are a list of other packages that allow the package to properly work. These packages *must* defined somewhere in the same profile (and in this case they have the same ServiceClass and ServiceName of the package) or in other profiles.
It is important to point out that also the dependencies against the packages declared in the current profile has to be specified (like the one against its own stubs library). 

A dependency is a declaration of the following elements:
* Service
* PackageName
* Version
Need to be able to declare minimum, maximum allowed versions of a dependency (both min and max may be optional), and allow "holes" for known incompatible versions.


{| align=center border=1
|'''Range'''||'''Meaning''' 
|- 
| (,1.0.0] || x &lt;= 1.0.0
|-
| 1.0.0 || "Soft" requirement on 1.0.0 (just a recommendation - helps select the correct version if it matches all ranges)
|- 
| [1.0.0] || Hard requirement on 1.0.0
|- 
|[1.2.0,1.3.0] || 1.2.0 &lt;= x &lt;= 1.3.0 
|- 
|[1.0.0,2.0.0) || 1.0.0 &lt;= x &lt; 2.0.0 
|- 
|[1.5.0,) || x &gt;= 1.5.0
|- 
|(,1.0.0],[1.2.0,) || x &lt;= 1.0.0 or x &gt;= 1.2.0 Multiple sets are comma-separated
|- 
|(,1.1.0),(1.1.0,) || This excludes 1.1.0 if it is known not to work in combination with this library 
|}


Mathematical syntax chosen to avoid the use of ''-'' as it would conflict with what is used in many version number, and because &lt; and &gt;= doesn't look nice in XML. (,1.0.0] is used because infinity is not really helpful here.

Default strategy: Of the overlapping ranges, the highest soft requirement is the version to be used. If there are no soft requirements inside the prescribed ranges, the most recent version is used. If that does not fit the described ranges, then the most recent version number in the prescribed ranges is used. If the ranges exclude all versions, an error occurs.

Addition of ranges leads to additional necessary specifications on the dependency element

* Scope level
: ..equals to "GHN" means that the package must be co-deployed on the same GHN
: ..equals to "VRE" means that the package must be deployed on a GHN and visible in the same VRE (typically used for dependencies against MainPackages)
: ..equals to "VO" means that the package must be deployed on a GHN and visible in the same VO (typically used for dependencies against MainPackages)
* Optional
: a false value means that the fulfilment of dependency is mandatory for a successful deployment of the package that declares the dependency

The [[Profile_Specification#Example|example]] above defines three dependencies that requires that the stub classes of the Deployer service and the stub classes of the SoftwareRepository service, have to be co-deployed with the Deployer-service package.

====== GHNRequirements ======
A GHNRequirement is a requirement against the node where the package is going to be deployed. These requirements are matched with the gHN profiles in order to find a suitable node that can host the package.
A gHN requirement is composed by:
* ''category'': a name of child element of the Profile/GHNDescription element in the gHN profile
* ''operator'': one of the following values:
:* eq (equal)
:* ne (not equal)
:* lt (less than)
:* le (less or equal than)
:* gt (greater than)
:* ge (greater or equal than)
* ''requirement'': one of the attribute and/or child elements defined for the selected category in the gHN profile
* ''value'': the value of  the selected attribute defined for the category in the GHN profile

Therefore, a gHN requirement is an expression evaluated in this form:
''<category/requirement operator value>''

Example:
<pre>
<GHNRequirements>
	<Req category="RunTimeEnv" operator="eq" requirement="Variable" value="java1.5"/>
	<Req category="OperatingSystem" operator="eq" requirement="Name" value="Linux"/>
</GHNRequirements>
</pre>

The example above means: "This package can be deployed on a gHN where a RunTimeEnv/Variable element text is equal to java1.5 and an OperatingSystem[@Name] attribute is equal to Linux"

GHNRequiremnts can be also used when a package depends on a software that cannot be dynamically deployed. In this case, such a software has to be 
* manually installed, 
* declared in the gHN profile as a conventional RunTimeEnv/Variable value and, 
* reported  as GHNRequirement in the package definition. 

The list of labels is open and new labels can be defined at any time. So far, the list includes:
* ''java1.5'' - a JVM v1.5 is available
* ''gLiteSEAccess'' - the node is configured to access to a Storage Element on a gLite infrastructure
* ''MySQLdb'' - a MySQL database is available
* ''Oracle10g'' - an Oracle10g database is available

=== Package-specific sections ===

==== MainPackage ====
----
For convention the main package name have to be in the form:
'''''ServiceName''-service'''

Example:

 <Packages>
 	<Main deployable="true">
 		<Name>Deployer-service</Name>
 		<Version>1.0.0</Version>
 		<Mandatory level="GHN"/>
 		<Shareable level="VO"/>
 		<GHNRequirements>
 			<Requirement category="Site"  requirement="string" value="java1.5" operator="ge"/>
 		</GHNRequirements>
 		<Dependencies>
 			[...]
 		</Dependencies>
 		<GARArchive>org.gcube.common.vremanagement.deployer.gar</GARArchive>
 		<PortType>
 			<Name>gcube/common/vremanagement/Deployer</Name>
 			<Security/>			
 			<WSDL>
 			</WSDL>
 		</PortType>					
 	</Main>
 </Packages>

===== GARArchive =====
The full path of the GAR file. The path must start from the package folder.

Example:
If the structure of the directory is like this

 |--Deployer-service
    \--archive
       \--org.gcube.common.vremanagement.deployer.gar


The declaration in the profile must be:

 <GARArchive>archive/org.gcube.searchservice.resultsetservice.gar</GARArchive>

===== PortType =====
A PortType is a WSDL interface generated by the deployment of the MainPackage's GAR. Each of them is declared in the Deployment Descriptor file (WSDD) with a <service> element.

===== Name =====
The value of the name attribute in the <service> element in the service's WSDD file.

==== Software ====

A Software package is a deployable library or a thirdy party package uploaded with the service. 

Example:

 <Packages>
 	<Software>
 		<Name>Deployer-stubs</Name>
 		<Version>1.0.0</Version>
 		[...]			
 		<Files>
 			<File>org.gcube.common.vremanagement.deployer.stubs.jar</File>
 		</Files>
 	</Software>
 </Packages>

===== Files =====
The relative path (starting from software archive root directory) and the name of the library's files in the software archive.