Difference between revisions of "Profile Specification"

From Gcube Wiki
Jump to: navigation, search
(PackageList section)
m
 
(283 intermediate revisions by 7 users not shown)
Line 1: Line 1:
How to write the profile specification for this component depending on its type.
+
<!-- CATEGORIES -->
 +
[[Category:Developer's Guide]]
 +
<!-- END CATEGORIES -->
 +
= Preliminary definitions =
  
== Preliminary definitions ==
+
== gCube resources and profiles ==
  
=== DILIGENT 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:
  
A ''DILIGENT 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 VDL as well as to operate the entire DILIGENT infrastructure. In the project, 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 ([[Generic-Resource-schema|XSD]])
 +
* Collection ([[collection-schema|XSD]])
 +
* Metadata Collection ([[metadatacollection-schema|XSD]])
 +
* gLite resource ([[Generic-Resource-schema|XSD]])
  
* VDL
+
Such resources can be combined or created at VRE creation time in order to set up a new Virtual Research Environment.
* Collection
+
* Metadata Collection
+
* Transformation Rule
+
* Service
+
* Running Instance
+
* External Running Instance
+
* DHN
+
* CS
+
* CSInstance
+
* gLite resource
+
  
Such resources can be combined or created at VDL creation time in order to set up a new Virtual Digital Library.
+
= The gHN resource =
In order to be appropriately managed and discovered, a DILIGENT Resource has to be described by creating a ''profile document'' compliant with its XML schema. A Schema per each resource type has been defined and all of them are available in the 
+
A gCube Hosting Node (shortly, a gHN) is the resource modelling a node of an infrastructure able to host gCube Running Instances.  
[https://elibrary.isti.cnr.it/svn_public/diligent_GAR/DILIGENTCommon/DILResourceSchemas/ CNR's SVN Repository]
+
In the following, we will focus about how to compile service profile
+
  
==== The Service resource ====
+
The gHN resource is built by collecting and grouping both the configuration and runtime information on the node. The profile of the gHN is composed by two classes of information:
  
Usually, a ''Service'' is defined as a software system that delivers functionalities. In DILIGENT, a Service is a not-empty set of related [[Profile_Specification#PackageList_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 DHN (e.g. a JAR o a GAR archive). Packages are the way in which the software needed to set up a DL has to prepared in order to be used and stored in the system.  
+
* static information, i.e. information that does not change once the gHN is started
 +
 
 +
* dynamic information, i.e. information that changes during the gHN lifetime
 +
 
 +
At the top level, there are four main sections in the gHN profile:
 +
 
 +
* ''Infrastructure'', reporting the name of the infrastructure to which the gHN is joined to
 +
 
 +
* ''GHNDescription'', a GLUE compliant section describing the hardware characteristics of the node
 +
 
 +
* ''Site'', reporting information about the site to which the gHN belongs to
 +
 
 +
* ''DeployedPackages'', reporting the list of gCube software packages actually deployed on the gHN
 +
 
 +
[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.
 
Once the service components have been developed, they must be described by compiling the service profile.
  
Line 32: Line 49:
  
  
Concretely, a Package is a “piece of software” that can be deployed on a DHN. A Package can be:
+
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#WSRFService|WSRFService]]'', 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#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#Portlet|Portlet]]'', representing a package that once deployed produces a portlet (Web components, managed by a portlet container, that process requests and generate dynamic GUI content) that can be hosted in a DILIGENT Portal;
+
* a ''[[Profile_Specification#Software|Software]]'', a software library (typically composed by one or more JAR archives) offering functionality for interacting with Service or a third party software distributed with the service that can be dynamically deployed;
* a ''[[Profile_Specification#GridJob|GridJob]]'', representing a package containing the code and the related information needed to run a certain job on the grid infrastructure;
+
 
* a ''[[Profile_Specification#Library|Library]]'', representing a software library (typically a JAR) that can be hosted on a DHN. There are three types of library:
+
About how to define a package, see the [[Profile_Specification#Packages_section| Packages section]].
** ''Shared'' Library, software library offering functionality of common utility, e.g. an XML parser library or a mathematical support library;
+
** ''Stub'' Library, software library offering functionality for interacting with WSRF Services.
+
** ''External'' Library, a thirdy party library available on the ETICS Repository that can be dynamically deployed.
+
* ''[[Profile_Specification#Software|Software]]'', a thirdy party software distributed with the service that can be dynamically deployed;
+
* ''[[Profile_Specification#ExternalSoftware|ExternalSoftware]]'', a thirdy party software available on the ETICS repository that can be dynamically deployed.
+
  
About how to define a package of any type above, see the [[Profile_Specification#PackageList_section| PackageList section]].
 
 
===== Composition =====
 
===== Composition =====
 
The set of Packages forming a Service is composed by:
 
The set of Packages forming a Service is composed by:
# one and only one Package of [[Profile_Specification#WSRFService|WSRFService]] or [[Profile_Specification#Portlet|Portlet]] type (the main package)
+
# one and only one [[Profile_Specification#MainPackage|MainPackage]] representing the gCore compliant Web-Service
# an arbitrary number of other Packages of different type logically related (even if not used) to it.
+
# 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 WSRFService package from which the related Running Instance resource is generated. The other packages can be
 
* helper modules developed and used by the WSRFService
 
* thirdy parties software used by the WSRFService
 
* helper modules developed and distributed with the WSRFService in order to be used by other Services to interact with a Running Instance of the Service.
 
  
===== How to specify dependencies =====
+
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:
A WSRFService package, once deployed, can rely on other software to perform its activities. Let's see how to specify these dependencies by distinguishing among:
+
* helper modules developed and used by the [[Profile_Specification#MainPackage|MainPackage]] i.e stubs
* software developed within this service (this is the case of a stub library, for instance)
+
* 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
*:&rarr; the software has to be declared as [[Profile_Specification#Library|Library]] and the dependency is specified as [[Profile_Specification#Dependencies|package Dependency]]
+
* software developed and distributed within other DILIGENT services
+
*:&rarr; the dependency is specified as [[Profile_Specification#Dependencies|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]] or [[Profile_Specification#Library|Library]] (it depends on the nature of the software) and the dependency is specified as [[Profile_Specification#Dependencies|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#ExternalSoftware|ExternalSoftware]] and the dependency is specified as [[Profile_Specification#Dependencies|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 DHN profile (by the DHN owner) and the dependency is specified as [[Profile_Specification#DHNRequirements|DHN Requirement]]
+
  
== How to compile the profile ==
 
  
The following example shows the common elements that compose the Service profile. The Package-specific sections are explained apart later.
+
We enforce the use of this convention:
<pre>
+
<DILIGENTResource xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+
<UniqueID/>
+
<ResourceType>Service</ResourceType>
+
<AuthorizationPolicies>
+
[...]
+
</AuthorizationPolicies>
+
<Profile>
+
<Class>MetadataManagement</Class>
+
<Name>MetadataCatalog</Name>
+
<DescriptiveParameters>
+
<DescParameter/>
+
</DescriptiveParameters>
+
<QoS/>
+
<DeploymentInfo>
+
<Deployable value="true"/>
+
</DeploymentInfo>
+
<DLDependencies>
+
<DLComponent>
+
<Class>MetadataManagement</Class>
+
<Name>XMLIndexer</Name>
+
<DescriptiveParametersValue/>
+
</DLComponent>
+
<DLComponent>
+
<Class>ContentManagement</Class>
+
<Name>StorageManagementService</Name>
+
<DescriptiveParametersValue/>
+
</DLComponent>
+
<DLComponent>
+
<Class>ContentManagement</Class>
+
<Name>CollectionManagementService</Name>
+
<DescriptiveParametersValue/>
+
</DLComponent>
+
</DLDependencies>
+
<SpecificData/>
+
<PackagesList>
+
                [...]
+
</PackagesList>
+
</Profile>
+
</DILIGENTResource>
+
</pre>
+
  
=== Common elements ===
+
Main Package Name='''''ServiceName''-service'''
  
==== Class ====
+
Stubs='''''ServiceName''-stubs'''
The class of a service is it's functional area. The following values are accepted as service classes:
+
* InformationSystem
+
* Keeper
+
* VDLGenerator
+
* BMM
+
* DVOS
+
* Search
+
* Index
+
* DataFusion
+
* CSD
+
* CSS
+
* ProcessManagement
+
* Annotation
+
* FeatureExtraction
+
* Personalisation
+
* ContentSecurity
+
* ContentManagement
+
* MetadataManagement
+
* Portal
+
  
==== Name ====
+
Test suite='''''ServiceName''-test-suite'''
The Name is an arbitrary string that uniquely identifies the service within a service class.
+
  
==== DescriptiveParameters ====
 
  
==== QoS ====
+
'''Example''':
  
==== DeploymentInfo ====
+
if the ''ServiceName'' is '''''Deployer''''', we will use:
  
==== DLDependencies  ====
+
Main Package Name='''Deployer-service'''
A DILIGENT service is part of a complex system and it makes use of other services. At VDL definition time, firstly, it is compiled the list of services that satisfy the VDL 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.
+
Specify a DL dependency here means that if this service is deployed in a DL, also the service identified by the Service Class and Name has to be deployed in the DL. (The DescriptiveParametersValue sintax still needs to be defined)
+
  
==== PackagesList section ====
+
Stubs='''Deployer-stubs'''
This element groups an unbounded sequence of Package elements. Each element describes a package that belongs 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#WSRFService|WSRFService]], [[Profile_Specification#Library|Library]], [[Profile_Specification#Portlet|Portlet]], [[Profile_Specification#GridJob|GridJob]], [[Profile_Specification#Software|Software]], [[Profile_Specification#ExternalSoftware|ExternalSoftware]]).
+
The only constraint is that one and only one WSRFService element is accepted in the list.
+
+
===== Common elements =====
+
  
====== Example ======
+
Test suite='''Deployer-test-suite'''
The following example shows the elements of a Package definition common to all types of Package.
+
<pre>
+
<Package>
+
<PackageName>MetadataCatalogService</PackageName>
+
<PackageType>WSRFService</PackageType>
+
<Version>1.0</Version>
+
<DLMandatory value="true"/>
+
<DHNMandatory value="false"/>
+
<VOMandatory value="false"/>
+
<DLSharable value="true"/>
+
<DisposeInterfaceSupport value="false"/>
+
<MultiVersionSupport value="false"/>
+
<VOSharingSupport value="false"/>
+
<ManifestFile/>
+
<InstallScripts>
+
<File>...</File>
+
</InstallScripts>
+
<UninstallScripts>
+
<File>...</File>
+
</UninstallScripts>
+
<RebootScripts>
+
<File>...</File>
+
</RebootScripts>
+
<Dependencies>
+
<Dependency>
+
<Service>
+
<Class>ContentManagement</Class>
+
<Name>ContentManagementService</Name>
+
</Service>
+
<PackageName>ContentManagementLayer_lib</PackageName>
+
<Version>0.1</Version>
+
<SameDHN value="true"/>
+
<Priority>3</Priority>
+
</Dependency>
+
<Dependency>
+
<Service>
+
<Class>MetadataManagement</Class>
+
<Name>XMLIndexer</Name>
+
</Service>
+
<PackageName>XMLIndexerService_stubs</PackageName>
+
<Version>1.0</Version>
+
<SameDHN value="true"/>
+
<Priority>3</Priority>
+
</Dependency>
+
</Dependencies>
+
<DHNRequirements>
+
<Req category="RunTimeEnv" operator="eq" requirement="Variable" value="java1.5"/>
+
<Req category="OperatingSystem" operator="eq" requirement="Name" value="Linux"/>
+
</DHNRequirements>
+
<ConfigurationFiles>
+
<File>....</File>
+
</ConfigurationFiles>
+
  
[package specific tag]
+
===== How to behave with library =====
 +
A library can be profiled in several ways, mainly depending of its source. The following table depicts them:
  
<OtherFiles/>
+
{| align=center border=1
<OtherProperties/>   
+
| ||'''Package in a Separated Software Archive''' || '''Appear as package in Service Profile'''
</Package>
+
|-
</pre>
+
| Stubs library || NO (Packaged with Service) || YES
 +
|-
 +
| Service specific library || NO (Packaged with Service) || YES
 +
|-
 +
| Library not service specific || YES (''Any Service Class'') || YES
 +
|-
 +
| Service Indipendent (Deployable) || YES (''ExternalSoftware'' Class) || YES
 +
|-
 +
| Service Indipendent (NOT Deployable) || NO (Contained in GAR archive) || NO
 +
|}
  
====== PackageName ======
 
An arbritrary string that uniquely identifies the package within this service.
 
  
====== PackageType ======
+
====== Example of profile for library not service specific ======
It identifies the type of the package. Allowed values are:
+
* WSRFService
+
* Library
+
* GridJob
+
* Portlet
+
* Software
+
* ExternalSoftware
+
  
====== Version ======
+
This is a basic template for a library profile:
The version of the package. It has to be in the form of X.Y.
+
  
====== DLMandatory ======
+
<source lang="xml">
If true, it states that at least one instance of this package must be deployed on a DL. This means that each time a new DL is created, this package is automatically added to the list of packages to be deployed.
+
<Resource>
 +
<ID></ID>
 +
<Type>Service</Type>
 +
<Profile>
 +
<Description>....</Description>
 +
<Class>... a class name...</Class>
 +
<Name>... a library name...</Name>
 +
<Version>\d{1,2}+.\d{1,2}+.\d{1,2}</Version>
 +
 +
<Packages>
 +
<Software>
 +
<Description></Description>
 +
<Name>... a library name...</Name>
 +
<Version>\d{1,2}+.\d{1,2}+.\d{1,2}</Version>
 +
                                <MavenCoordinates>
 +
                                                <GroupId></GroupId>
 +
                                                <ArtifactId></ArtifactId>
 +
                                                <Version></Version>
 +
                                </MavenCoordinates>
 +
 +
</Software>
 +
</Packages>
 +
</Profile>
 +
</Resource>
 +
</source>
  
====== DHNMandatory ======
 
If true, it states that one instance of this package must be deployed on each node of the infrastructure.
 
  
====== VOMandatory ======
 
If true, it states that at least one instance of this package must be deployed on a VO. This means that each time a new VO is created, this package is automatically added to the list of packages to be deployed in that VO. It is typically used to discriminate those packages that are needed for the management of a VO (mostly Collective Layer packages).
 
  
====== DLSharable ======
+
where:
It states if the package can be shared across multiple DLs (true) or if it is DL-Specific (false).
+
  
====== DisposeInterfaceSupport ======
+
''... a class name...'' has to be replaced with the name of Service Class the library belong to
Not used
+
  
====== MultiVersionSupport ======
+
''... a library name...'' has to be replaced with the name of Library name
Not used
+
  
====== VOSharingSupport ======
+
''\d{1,2}+.\d{1,2}+.\d{1,2}'' has to be replaced with the actual version of the Library
It states if the package can be shared across multiple VOs (true) or if it is VO-Specific (false).
+
  
====== ManifestFile ======
+
The following is an instance example of the template:
  
====== InstallScripts ======
+
<source lang="xml">
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 the package is downloaded and uncompressed.
+
<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>
 +
                                <MavenCoordinates>
 +
                                                <GroupId>org.gcube.search</GroupId>
 +
                                                <ArtifactId>resultsetlibrary</ArtifactId>
 +
                                                <Version>1.0.0</Version>
 +
                                </MavenCoordinates>
  
====== 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.
+
</Software>
 +
</Packages>
 +
</Profile>
 +
</Resource>
 +
</source>
  
====== RebootScripts ======  
+
====== Example of profile for Service Independent (Deployable) library ======
This set of scripts are executed before each container startup.
+
  
====== Dependencies ======
+
This is a basic template for a Service Independent (Deployable) library profile:
The dependencies of the package are a list of other packages (defined somewhere in the current or in other profiles) that allow the package to properly work. It is importat to point out that also the depenedencies against the packages declared in the current profile has to be specified (like the one agains its stub library).
+
From the Collective Layer perspective, a dependency is taken into consideration at package deployment time and it is a way to force the deployment of other packages (where it depends of the type of dependency) when the current package is deployed.
+
  
A dependency is a declaration of the following element:
+
<source lang=xml>
* Service
+
<Resource>
* PackageName
+
<ID></ID>
* Version (optional)
+
<Type>Service</Type>
* SameDHN
+
<Profile>
: A true value here means that the package must be co-deployed on the same DHN
+
<Description></Description>
* SameDL
+
<Class>ExternalSoftware</Class>
: A true value here means that the package must be deployed on a DHN and visible in the same DL (typically used for dependencies against WSRFService packages)
+
<Name>... a library name...</Name>
* SameVO
+
<Version>\d{1,2}+.\d{1,2}+.\d{1,2}</Version>
: A true value here means that the package must be deployed on a DHN and visible in the same VO (typically used for dependencies against WSRFService packages)
+
* Priority
+
<Packages>
: The priority is a number that defines the level of the dependency:
+
<Software>
: 1 -> wish
+
<Description></Description>
: 2 -> important
+
<Name>... a library name...</Name>
: 3 -> mandatory
+
<Version>\d{1,2}+.\d{1,2}+.\d{1,2}</Version>
: 4 -> security reasons
+
                        <MavenCoordinates>
 +
                                        <GroupId>.. groupID ..</GroupId>
 +
                                        <ArtifactId>.. artifactID ..</ArtifactId>
 +
                                        <Version>.. version ..</Version>
 +
                        </MavenCoordinates>
 +
 +
</Software>
 +
</Packages>
 +
</Resource>
 +
</source>
  
The following example defines a dependency that requires that the stub classes of the XMLIndexer service are co-deployed with the package that includes the dependency declaration:
+
where 
<pre>
+
<Dependency>
+
<Service>
+
<Class>MetadataManagement</Class>
+
<Name>XMLIndexer</Name>
+
</Service>
+
<PackageName>XMLIndexerService_stubs</PackageName>
+
<Version>1.0</Version>
+
<SameDHN value="true"/>
+
<Priority>3</Priority>
+
</Dependency>
+
</pre>
+
  
Finally, if the depenency is against a software stored in the ETICS repository, an [[Profile_Specification#ExternalSoftware|ExternalSoftware]] package has to be defined in the current profile and the dependency has to be defined as any other one.
+
''... a library name...'' has to be replaced with the name of Library name
  
====== DHNRequirements ======
+
''\d{1,2}+.\d{1,2}+.\d{1,2}'' has to be replaced with the actual version of the Library
A DHNRequirement is a requirement against the node where the package is deployed. These requirements are matched with the DHN profiles in order to find a suitable node that can host the package.
+
A DHN requirement is composed by:
+
* category
+
: It is a name of an element in the DHN profile
+
* operator
+
: it is 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
+
: It is one of the attributes/child elements defined for the selected category in the DHN profile
+
* value
+
: it is the value of  the selected attribute defined for the category in the DHN profile
+
  
At the end of the story, a requirement is an expression evaluated in this form:
 
''<category/requirement operator value>''
 
  
Example:
+
The following is an instance example of the template:
<pre>
+
<DHNRequirements>
+
<Req category="RunTimeEnv" operator="eq" requirement="Variable" value="java1.5"/>
+
<Req category="OperatingSystem" operator="eq" requirement="Name" value="Linux"/>
+
</DHNRequirements>
+
</pre>
+
  
The example above means: "I can be deployed on a DHN where there is a RunTimeEnv/Variable element equals to java 1.5 and an OperatingSystem[@Name] element equals to Linux"
+
<source lang=xml>
 +
<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>
 +
                                <MavenCoordinates>
 +
                                              <GroupId>org.gcube.externals</GroupId>
 +
                                              <ArtifactId>commons-httpclient</ArtifactId>
 +
                                              <Version>3.0.1</Version>
 +
                                </MavenCoordinates>
 +
                                ...
 +
                        </Software>
 +
                </Packages>
 +
                <SpecificData></SpecificData>
 +
        </Profile>
 +
</Resource>
 +
</source>
  
A typical usage of DHNRequiremnts is when a package depends on a software that cannot be dynamically deployed. In this case, the software has to be manually installed and declared in the DHN profile as RunTimeEnv/Variable and then it has to be reported  as DHN requirement in the package definition. A list of conventional labels that identify the software (and more in general, the DHN capabilities) has to be fixed:
+
===== How to specify dependencies =====
* 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
+
  
Of course, the list above can be enriched at any time.
+
The dependencies are specified in the pom of the project, in the profile is only specified the set of maven coordinates.
 +
The artifact can be found on an internal maven repository (Nexus) or on another trusted maven Repository
  
====== ConfigurationFiles ======
+
== How to compile a Service profile ==
  
====== OtherFiles ======
+
The following example shows the common elements that compose the Service profile. The Package-specific sections are explained apart later.
List here the files that are in the service archive belonging the package and that are not already included in other elements (like installscripts, GARArchive, etc.)
+
  
====== OtherProperties ======
+
<source lang=xml>
This is a free section where you can insert anything that cannot be included in the other elements of the profile. For
+
<Resource xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
instance, you can insert here any information you suppose helps to discriminate the service among others. Let's suppose you have two different Search services, S1 and S2, implementing two different kinds of search. Ok, you specify a different name, but you can also add here information that helps to differentiate S1 from S2.
+
<ID></ID>
 +
<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>
 +
<SpecificData/>
 +
<Packages>
 +
[...]
 +
</Packages>
 +
</Profile>
 +
</Resource>
 +
</source>
  
=== Package-specific sections ===
+
=== Common elements ===
  
==== WSRFService ====
+
==== 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.
  
Example:
+
==== Name ====
<pre>
+
The Name is an arbitrary string that uniquely identifies the service within a service class.
<WSRFService>
+
<GARArchive>org_diligentproject_X.gar</GARArchive>
+
<BuildFile/>
+
<DeploymentOptions/>
+
<ArchitecturalPattern>Factory</ArchitecturalPattern>
+
<ServiceEquivalenceFunctions/>
+
<WSRFEntry>
+
<EntryName>String</EntryName>
+
<Factory value="true"/>
+
<Parameters/>
+
<Security>
+
[...]
+
</Security>
+
<WSDL>
+
<wsdl:definitions targetNamespace="http://...." name="....">
+
[...]
+
</wsdl:definitions>
+
</WSDL>
+
</WSRFEntry>
+
</WSRFService>
+
</pre>
+
  
===== GARArchive =====
+
==== Version ====
 +
The service version must be in the format: \d{1,2}+.\d{1,2}+.\d{1,2}
  
===== BuildFile =====
+
This version marks a whole gCube distribution and, for the current distribution under development, the version number is fixed to '''1.00.00'''. Future and different distributions will eventually evolve with a different service version.
  
===== DeploymentOptions =====
+
==== 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.
  
===== ArchitecturalPattern =====
+
==== Packages section ====
This element declares the architectural pattern adopted by the WSRF service.
+
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.  
  
===== ServiceEquivalenceFunctions element: Fix the service equivalence =====
+
The following example shows the elements of a Package definition common to both types of Package.
This element allows to define functions to use at runtime to understand when two Running Instances of the service are equivalents from a specific function point of view. They can be considered are a sort of criteria to find service's replicas. Each function defined here must have a corrispondent section in the Running Instance profile that gives the values to the formal parameter defined in the function.
+
<source lang=xml>
So far, the following fuction are used in the infrastructure:
+
<Packages>
* '''match''', used by the Active Planner service to discriminate among two Running Instances of the same service
+
<Main deployable="true">
 +
<Name>Deployer-service</Name>
 +
<Version>1.0.0</Version>
 +
                <MavenCoordinates>
 +
                    <groupId>org.gcube.vremanagement</groupId>
 +
                    <artifactId>deployer-service</artifactId>
 +
                    <version>1.0.0</version>
 +
                </MavenCoordinates>
 +
<Mandatory level="GHN"/>
 +
<Shareable level="VO"/>
 +
<GHNRequirements>
 +
<Requirement category="Site"  requirement="string" value="java1.5" operator="ge"/>
 +
</GHNRequirements>
 +
<GARArchive>org.gcube.common.vremanagement.deployer.gar</GARArchive>
 +
<PortType>
 +
<Name>gcube/common/vremanagement/Deployer</Name>
 +
<Security/>
 +
</PortType>
 +
</Main>
 +
</Packages>
 +
</source>
 +
====== Name ======
 +
An arbritrary string that uniquely identifies the package within this service.
  
===== WSRFEntry =====
+
====== Version ======
A WSRFEntry is a WSDL interface generated by the deployment of the WSRFService's GAR. Each of them is declared in the Deployment Descriptor file (WSDD) with a <service> element.
+
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)
  
===== EntryName =====
+
====== Mandatory ======
The value of the name attribute in the <service> element in the service's WSDD file.
+
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: ''NONE'', ''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.
  
===== Security =====
+
If the element is not declared, the package is assumed to be not mandatory at any level by default.
This section includes information for a correct management of the service's security at Collective Layer level. If the service is not configured for security it can be omitted.
+
====== Example ======
+
<pre>
+
<Security>
+
<SecurityDescriptor>
+
<securityConfig xmlns="http://www.globus.org">
+
<authz value="VOAuthorizationPDP:org.diligentproject.dvos.authorization.handler.VOAuthorizationPDP"/>
+
<method name="addCredentialsRenewalOperation">
+
<auth-method>
+
<GSISecureConversation>
+
  <protection-level>
+
        <privacy/>
+
      </protection-level>
+
</GSISecureConversation>
+
</auth-method>
+
<run-as>
+
<service-identity/>
+
</run-as>
+
</method>
+
<auth-method>
+
<GSISecureConversation/>
+
</auth-method>
+
<run-as>
+
<service-identity/>
+
</run-as>
+
</securityConfig>
+
</SecurityDescriptor>
+
<LogicalOperations>
+
<Operation id="{http://www.diligentproject.org/namespaces/dvos/credentialRenewal}manageCredentialsTask"
+
name="manageCredentialsTask" 
+
description="This operation allows to set credentials renewal task on the credentials renewal service">
+
<Role name="CredentialsTaskManager"/>
+
</Operation>
+
</LogicalOperations>
+
<ServiceRoles>
+
<Role name="CredentialsManager"/>
+
</ServiceRoles>
+
</Security>
+
</pre>
+
====== SecurityDescriptor ======
+
The content of the security descriptor file for the WSRF entry.,
+
====== LogicalOperations ======
+
This section defines logical operations required to access Running Instances of this service. Those used in the configuration file of the authorization handler for the service. For each operation also the list of roles to which the operation should be permitted in the VO must be given. This allows the DLManagement, after the deployment of a new Running Instance., to correclty set auhtorizations to access the RI just created.
+
====== ServiceRoles ======
+
The set of roles Running Instances of this service have to hold in order to succesfully act in the VO. As identities used by the Running Instance have to be selected before the deployment, the DLManagement is in charge to assign these roles to the identity selected for the new Running Instance.
+
  
==== Library ====
+
====== 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: ''NONE'', ''VO'' and ''VRE''.
The Library packages are usually JAR archives. The Collective Layer copies such libraries in the $GLOBUS_LOCATION/lib folder. There are 3 types of Library:
+
# shared library
+
# stub library
+
# external library
+
  
==== Shared Library ====
+
If the value is ''NONE'', the package cannot be shared across any scope, i.e. there must be one and only one deployed instance of that package in a scope.
----
+
Example
+
<pre>
+
<Library>
+
<Type>shared</Type>
+
<Parameters/>
+
<LibraryFile>ip/org_diligentproject_informationservice_disip.jar</LibraryFile>
+
</Library>
+
</pre>
+
  
* Type
+
If the element is not declared, the package is assumed to be shareable at any scope level by default.
: Fixed: "shared"
+
  
* Parameters
+
====== InstallScripts ======
: The parameters grouped in this section allow to statically configure the library. The section can be leave empty if there is no need to configure the package in this way.
+
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.
  
* LibraryFile
+
====== UninstallScripts ======
: The path and the name of the library's file in the service archive.
+
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.
  
==== Stub Library ====
+
====== RebootScripts ======  
----
+
This set of scripts are executed before each container startup.
Example:
+
<pre>
+
<Library>
+
<Type>stub</Type>
+
<IsStubOf>
+
<PackageName>DIS-IC_Service</PackageName>
+
<Version>1.0</Version>
+
<Service>
+
<Class>InformationSystem</Class>
+
<Name>DIS-IC</Name>
+
</Service>
+
</IsStubOf>
+
<Parameters/>
+
<LibraryFile>bin/org_diligentproject_informationservice_disic_stubs.jar</LibraryFile>
+
</Library>
+
</pre>
+
  
* Type
+
====== MavenCoordinates ======
: Fixed: "stub"
+
The MavenCoordinates is a set of maven coordinates that defines the artifact realted to the package.
 +
The dependencies of the project may be specified in the pom according to maven specifications
  
* IsStubOf
+
A set of coordinates is a declaration of the following elements:
: This element declares of which WSRFService package the library is stub of.
+
* GroupID
 +
* ArtifactID
 +
* Version
  
* Parameters
+
====== GHNRequirements ======
: The parameters grouped in this section allow to statically configure the library. The section can be leave empty if there is no need to configure the package in this way.
+
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 expressed by:
 +
* ''category'': it identifies the element/attribute of the Profile/GHNDescription section of the gHN profile against which the requirement is expressed.  
 +
It can assume one of the following values:
  
* LibraryFile
+
<div style="border: 1px dashed #2F6FAB; background-color: #F9F9F9; color: black; padding:0.5em; margin-top:5px; margin-bottom:5px; font-family: monospace; font-style: normal; font-size-adjust: none;">
: The path and the name of the library's file in the service archive.
+
:* MEM_RAM_AVAILABLE
 +
:* MEM_RAM_SIZE
 +
:* MEM_VIRTUAL_AVAILABLE
 +
:* MEM_VIRTUAL_SIZE
 +
:* HOST
 +
:* OS
 +
:* DISK_SPACE
 +
:* LOAD1MIN
 +
:* LOAD5MIN
 +
:* LOAD15MIN
 +
:* PLATFORM
 +
:* PROCESSOR_NUM
 +
:* PROCESSOR_BOGOMIPS
 +
:* SITE_LOCATION
 +
:* SITE_COUNTRY
 +
:* SITE_DOMAIN
 +
:* CUSTOM_REQUIREMENT
 +
:* RUNTIME_ENV_STRING
 +
:* RUNTIME_ENV_NUMBER
 +
</div>
  
==== External Library ====
+
* ''operator'': declares the relation between the actual value of the looked up attribute ''category'' and the ''value'' expressed in the Requirement.
----
+
It can assume one of the following values:
Example:
+
<div style="border: 1px dashed #2F6FAB; background-color: #F9F9F9; color: black; padding:0.5em; margin-top:5px; margin-bottom:5px; font-family: monospace; font-style: normal; font-size-adjust: none;">
<pre>
+
:* eq (Equal)
<Library>
+
:* le (Less or Equal)
<Type>external</Type>
+
:* ge (Greater or Equal)
<Paramenters/>
+
:* gt (Greater than)
<ExternalLibraryFile>
+
:* lt (Less than)
<ETICS-ID>24545-7fjm-265765</ETICS-ID>
+
:* exist (can be also used in terms of "contains")
<Description>Apache Common IO</Description>
+
:* ne (Not Equal)
</ExternalLibraryFile>
+
</div>
</Library>
+
</pre>
+
  
* Type
+
* ''requirement'': one of the attribute and/or child elements defined for the selected category in the gHN profile
: Fixed: "external"
+
  
* Parameters
+
* ''value'': the value of  the selected attribute defined for the category in the GHN profile
: The parameters grouped in this section allow to statically configure the library. The section can be leave empty if there is no need to configure the package in this way.
+
  
* ExternalLibraryFile
+
Therefore, a gHN requirement is an expression evaluated in this form:
: It includes the ID on the ETICS Repository and a human readable description.
+
''<category/requirement operator value>''
  
==== Portlet ====
+
* A simple '''example''':
----
+
<div style="border: 1px dashed #2F6FAB; background-color: #F9F9F9; color: black; padding:0.5em; margin-top:5px; margin-bottom:5px; font-family: monospace; font-style: normal; font-size-adjust: none;">
Example:
+
<source lang="xml" enclose="none" line title="PlanRequest.xml">
<pre>
+
<GHNRequirements>
<Portlet>
+
<Requirement category="OS" operator="exist" value="Linux" requirement=""/>
<WARArchive>String</WARArchive>
+
<Requirement category="PROCESSOR_NUM" operator="ge"  value="2" requirement=""/>
<BuildFile>String</BuildFile>
+
</GHNRequirements>
<DeploymentOptions/>
+
</source>
<Parameters>
+
</div>
<Param>
+
<Name>String</Name>
+
<AllowedValues>
+
<Value>*</Value>
+
</AllowedValues>
+
</Param>
+
</Parameters>
+
<Service>
+
<wsdl:definitions targetNamespace="http://diligentproject.org/..." name="...">
+
</wsdl:definitions>
+
</Service>
+
</Portlet>
+
</pre>
+
  
==== Software ====
+
The example above means: "This package can be deployed on a gHN running on a Linux Operating System (Line 2) (it requires that the value of OS in the GHN profile '''contains''' the string Linux) ''and'' having at least 2 processors (Line 3)". '''Note''': in both cases the requirement attribute is not relevant.
----
+
A Software package is a deployable thirdy party package uploaded with the service.  
+
  
Example:
+
* '''Example'''. Accessing the run time environment variables:
<pre>
+
<div style="border: 1px dashed #2F6FAB; background-color: #F9F9F9; color: black; padding:0.5em; margin-top:5px; margin-bottom:5px; font-family: monospace; font-style: normal; font-size-adjust: none;">
<Software>
+
<source lang="xml" enclose="none" line >
<FileList>
+
<GHNRequirements>
<File>setup.exe</File>
+
<Requirement category="RUNTIME_ENV_STRING" requirement="ANT_HOME" operator="eq" value="/usr/share/ant" />
<File>data.cab</File>
+
<Requirement category="RUNTIME_ENV_STRING" requirement="GLOBUS_OPTIONS" operator="exist"  value="" />
</FileList>
+
</GHNRequirements>
<Description>my software</Description>
+
</source>
</Software>
+
</div>
</pre>
+
  
* FileList
+
The former block (Line 2) checks that the environment contains the key ''ANT_HOME'' and that its value is equal to ''/usr/share/ant'' while the latter (Line 3) simply checks that the environment contains the key  ''GLOBUS_OPTIONS'' regardless its value.
: The list of files that compose the software. It is validated at registration time and if one of the declared files is not included in the Service Archive, the registration fails.
+
* Descritpion
+
: A human description of the software (can be left empty).
+
  
==== ExternalSoftware ====
+
*  '''Putting them together a clarifying example''':
 +
<div style="border: 1px dashed #2F6FAB; background-color: #F9F9F9; color: black; padding:0.5em; margin-top:5px; margin-bottom:5px; font-family: monospace; font-style: normal; font-size-adjust: none;">
 +
<source lang="xml" enclose="none" line >
 +
<GHNRequirements>
 +
<Requirement category="RUNTIME_ENV_STRING" requirement="Java" operator="exist" value="1.5" />
 +
<Requirement category="RUNTIME_ENV_STRING" requirement="gCore-version" operator="eq"  value="1.0.1" />
 +
        <Requirement category="RUNTIME_ENV_STRING" requirement="CATALINA_HOME" operator="exist" value="" />
 +
        <Requirement category="SITE_DOMAIN" requirement="" operator="exist" value="research-infrastructures.eu" />
 +
        <Requirement category="OS" requirement="" operator="exist" value="Linux" />
 +
        <Requirement category="OS" requirement="" operator="eq" value="i386" />
 +
</GHNRequirements>
 +
</source>
 +
</div>
 +
Here a concrete example where the user statically claims that its service to run needs:
 +
* A jdk having version 1.5.* (note the exist operator)
 +
* An installed gCore having version 1.0.1
 +
* That apache tomcat is installed on the machine (it is enough to check the CATALINA_HOME environment variable is defined)
 +
* The ghn must run in the *.research-infrastructures.eu domain
 +
* The operating system must be Linux*
 +
* The platform must be i386
 +
 
 +
* '''Example'''. Custom queries:
 +
To give freedom to customize the access to specific paths in the resources a CUSTOM_REQUIREMENT category has been introduced. The example below is a sample:
 +
 +
<div style="border: 1px dashed #2F6FAB; background-color: #F9F9F9; color: black; padding:0.5em; margin-top:5px; margin-bottom:5px; font-family: monospace; font-style: normal; font-size-adjust: none;">
 +
<source lang="xml" enclose="none" >
 +
<Requirement category="CUSTOM_REQUIREMENT" operator="exist"  value="/GHNDescription/Architecture[@PlatformType = 'i386']" requirement="" />
 +
</source>
 +
</div>
 +
 
 +
The same result can be obtained by the query:
 +
<div style="border: 1px dashed #2F6FAB; background-color: #F9F9F9; color: black; padding:0.5em; margin-top:5px; margin-bottom:5px; font-family: monospace; font-style: normal; font-size-adjust: none;">
 +
<source lang="xml" enclose="none" >
 +
<Requirement category="PLATFORM" operator="eq"  value="i386" requirement=""/>
 +
</source>
 +
</div>
 +
 
 +
 
 +
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 ===
 +
Depending on the type of the package, there are some specific elements to report on the package profile.
 +
 
 +
==== MainPackage ====
 
----
 
----
An ExternalSoftware package is a deployable thirdy party package used by this service but not uploaded with the Service on the infrastructure.
+
 
One can decide to do not include a software as part of a Service because:
+
A MainPackage is a package than once deployed it generates an instance of a gCube Service.
* it is supposed that the software is of general interest and it can be used also by other Services
+
 
* the size of the software is quite huge (more than few Megabytes) and it is better to do not upload it in a service invocation.
+
For convention the main package name have to be in the form:
These software must be uploaded in the ETICS Repository and referred here.
+
'''''ServiceName''-service'''
  
 
Example:
 
Example:
<pre>
+
<source lang=xml>
<ExternalSoftware>
+
<Packages>
<ETICS-ID>5eed2db4-10cb-48ac-bc34-c0de2e09a4f9</ETICS-ID>
+
<Main deployable="true">
<Description>Lucene</Description>
+
<Name>Deployer-service</Name>
</ExternalSoftware>
+
<Version>1.0.0</Version>
</pre>
+
                <MavenCoordinates>
 +
[...]
 +
</MavenCoordinates>
 +
<Mandatory level="GHN"/>
 +
<Shareable level="VO"/>
 +
<GHNRequirements>
 +
<Requirement category="Site"  requirement="string" value="java1.5" operator="ge"/>
 +
</GHNRequirements>
 +
<GARArchive>org.gcube.common.vremanagement.deployer.gar</GARArchive>
 +
<PortType>
 +
<Name>gcube/common/vremanagement/Deployer</Name>
 +
<Security/>
 +
</PortType>
 +
</Main>
 +
</Packages>
 +
</source>
 +
===== GARArchive =====
 +
The full path of the GAR file. The path must start from the package folder.
  
* ETICS-ID
+
Example:
: A valid ID of an external software uploaded on the ETICS Repository
+
If the structure of the directory is like this
* Descritpion
+
: A human readable description of the software referred by the ID (can be left empty).
+
  
==== GridJob ====
+
|--Deployer-service
----
+
    \--archive
A GridJob package...
+
      \--org.gcube.common.vremanagement.deployer.gar
  
  
-- Manuele Simi
+
The declaration in the profile must be:
 +
 
 +
<source lang=xml>
 +
<GARArchive>archive/org.gcube.searchservice.resultsetservice.gar</GARArchive>
 +
</source>
 +
 
 +
===== 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 any third party package that can be dynamically deployed.
 +
 
 +
Here is an example of a software declared of type=library (meaning that its files are copied in the $GLOBUS_LOCATION folder) and using installation and reboot scripts:
 +
<source lang=xml>
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<Resource xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 +
<ID></ID>
 +
<Type>Service</Type>
 +
<Profile>
 +
<Description>eXistDB</Description>
 +
<Class>ExternalSoftware</Class>
 +
<Name>exist</Name>
 +
<Version>1.2.6</Version>
 +
<Packages>
 +
<Software>
 +
<Description>eXist XML Database</Description>
 +
<Name>exist</Name>
 +
<Version>1.2.6</Version>
 +
<MultiVersion value="true"/>
 +
<Mandatory level="VO"/>
 +
<Shareable level="VO"/>
 +
<InstallScripts>
 +
<File>install.sh</File>
 +
</InstallScripts>
 +
<RebootScripts>
 +
<File>reboot.sh</File>
 +
</RebootScripts>
 +
<Type>library</Type>
 +
<Files>
 +
<File>commons-collections-3.1.jar</File>
 +
<File>commons-pool-1.4.jar</File>
 +
<File>excalibur-cli-1.0.jar</File>
 +
<File>exist.jar</File>
 +
<File>exist-optional.jar</File>
 +
<File>javax.servlet-1.4.jar</File>
 +
<File>jEdit-syntax.jar</File>
 +
<File>jgroups-all.jar</File>
 +
<File>jline-0_9_5.jar</File>
 +
<File>jta.jar</File>
 +
<File>quartz-1.6.0.jar</File>
 +
<File>stax-api-1.0.1.jar</File>
 +
<File>sunxacml.jar</File>
 +
<File>xmldb.jar</File>
 +
<File>xmlrpc-client-3.1.1.jar</File>
 +
<File>xmlrpc-common-3.1.1.jar</File>
 +
<File>xmlrpc-server-3.1.1.jar</File>
 +
<!--File>xmlrpc-1.2-patched.jar</File-->
 +
<File>conf.xml</File>
 +
<File>catalog.xml</File>
 +
</Files>
 +
</Software>
 +
</Packages>
 +
</Profile>
 +
</Resource>
 +
</source>
 +
===== Files =====
 +
The relative path (starting from software archive root directory) and the name of the library's files shipped in the software archive.

Latest revision as of 17:12, 11 July 2013

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:

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 gCube Hosting Node (shortly, a gHN) is the resource modelling a node of an infrastructure able to host gCube Running Instances.

The gHN resource is built by collecting and grouping both the configuration and runtime information on the node. The profile of the gHN is composed by two classes of information:

  • static information, i.e. information that does not change once the gHN is started
  • dynamic information, i.e. information that changes during the gHN lifetime

At the top level, there are four main sections in the gHN profile:

  • Infrastructure, reporting the name of the infrastructure to which the gHN is joined to
  • GHNDescription, a GLUE compliant section describing the hardware characteristics of the node
  • Site, reporting information about the site to which the gHN belongs to
  • DeployedPackages, reporting the list of gCube software packages actually deployed on the gHN

[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 Packages (connected through dependencies) forming an unique logical entity. A Package is the smallest installable unit of software that can be deployed on a 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 gHN. A Package can be:

  • a MainPackage, representing a package that once deployed produces a WSRF Service (a service able to manage stateful resources following the WS-Resource patterns);
  • a Software, a software library (typically composed by one or more JAR archives) offering functionality for interacting with Service or a third party software distributed with the service that can be dynamically deployed;

About how to define a package, see the Packages section.

Composition

The set of Packages forming a Service is composed by:

  1. one and only one MainPackage representing the gCore compliant Web-Service
  2. an arbitrary number of other Packages of different types logically related (even if not used) to the MainPackage


The "main" part of a Service is, of course, the MainPackage from which the related Running Instance resource is generated. The other packages can be:

  • helper modules developed and used by the MainPackage i.e stubs
  • helper modules developed and distributed with the 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 convention:

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

A library can be profiled in several ways, mainly depending of its source. The following table depicts them:

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
Library not service specific YES (Any Service Class) YES
Service Indipendent (Deployable) YES (ExternalSoftware Class) YES
Service Indipendent (NOT Deployable) NO (Contained in GAR archive) NO


Example of profile for library not service specific

This is a basic template for a library profile:

 <Resource>
 	<ID></ID>
 	<Type>Service</Type>
 	<Profile>
 		<Description>....</Description> 
 		<Class>... a class name...</Class>
 		<Name>... a library name...</Name>
 		<Version>\d{1,2}+.\d{1,2}+.\d{1,2}</Version><Packages>
 			<Software>
 				<Description></Description>
 				<Name>... a library name...</Name>
 				<Version>\d{1,2}+.\d{1,2}+.\d{1,2}</Version>
                                <MavenCoordinates>
                                                <GroupId></GroupId>
                                                <ArtifactId></ArtifactId>
                                                <Version></Version>
                                </MavenCoordinates></Software>
 		</Packages>
 	</Profile>
 </Resource>


where:

... a class name... has to be replaced with the name of Service Class the library belong to

... a library name... has to be replaced with the name of Library name

\d{1,2}+.\d{1,2}+.\d{1,2} has to be replaced with the actual version of the Library

The following is an instance example of the template:

 <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>
                                <MavenCoordinates>
                                                <GroupId>org.gcube.search</GroupId>
                                                <ArtifactId>resultsetlibrary</ArtifactId>
                                                <Version>1.0.0</Version>
                                </MavenCoordinates>
 
 				...
 			</Software>
 		</Packages>
 	</Profile>
 </Resource>
Example of profile for Service Independent (Deployable) library

This is a basic template for a Service Independent (Deployable) library profile:

 <Resource>
 	<ID></ID>
 	<Type>Service</Type>
 	<Profile>
 		<Description></Description> 
 		<Class>ExternalSoftware</Class>
 		<Name>... a library name...</Name>
 		<Version>\d{1,2}+.\d{1,2}+.\d{1,2}</Version><Packages>
 		<Software>
 			<Description></Description>
 			<Name>... a library name...</Name>
 			<Version>\d{1,2}+.\d{1,2}+.\d{1,2}</Version>
                        <MavenCoordinates>
                                        <GroupId>.. groupID ..</GroupId>
                                        <ArtifactId>.. artifactID ..</ArtifactId>
                                        <Version>.. version ..</Version>
                        </MavenCoordinates></Software>
 	</Packages>
 </Resource>

where

... a library name... has to be replaced with the name of Library name

\d{1,2}+.\d{1,2}+.\d{1,2} has to be replaced with the actual version of the Library


The following is an instance example of the template:

 <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>
                                 <MavenCoordinates>
                                               <GroupId>org.gcube.externals</GroupId>
                                               <ArtifactId>commons-httpclient</ArtifactId>
                                               <Version>3.0.1</Version>
                                 </MavenCoordinates>
                                 ...
                         </Software>
                 </Packages>
                 <SpecificData></SpecificData>
         </Profile>
 </Resource>
How to specify dependencies

The dependencies are specified in the pom of the project, in the profile is only specified the set of maven coordinates. The artifact can be found on an internal maven repository (Nexus) or on another trusted maven Repository

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.

<Resource xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<ID></ID>
	<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>		
		<SpecificData/>
		<Packages>
			[...]
		</Packages>
	</Profile>
</Resource>

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}

This version marks a whole gCube distribution and, for the current distribution under development, the version number is fixed to 1.00.00. Future and different distributions will eventually evolve with a different service version.

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 (MainPackage and Software). The only constraint is that one and only one MainPackage element is accepted in the list.

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>
                <MavenCoordinates>
                    <groupId>org.gcube.vremanagement</groupId>
                    <artifactId>deployer-service</artifactId>
                    <version>1.0.0</version>
                </MavenCoordinates>
 		<Mandatory level="GHN"/>
 		<Shareable level="VO"/>
 		<GHNRequirements>
 			<Requirement category="Site"  requirement="string" value="java1.5" operator="ge"/>
 		</GHNRequirements>
 		<GARArchive>org.gcube.common.vremanagement.deployer.gar</GARArchive>
 		<PortType>
 			<Name>gcube/common/vremanagement/Deployer</Name>
 			<Security/>			
 		</PortType>					
 	</Main>
 </Packages>
Name

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: NONE, 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: NONE, VO and VRE.

If the value is NONE, the package cannot be shared across any scope, i.e. there must be one and only one deployed instance of that package in a scope.

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.

MavenCoordinates

The MavenCoordinates is a set of maven coordinates that defines the artifact realted to the package. The dependencies of the project may be specified in the pom according to maven specifications

A set of coordinates is a declaration of the following elements:

  • GroupID
  • ArtifactID
  • Version
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 expressed by:

  • category: it identifies the element/attribute of the Profile/GHNDescription section of the gHN profile against which the requirement is expressed.

It can assume one of the following values:

  • MEM_RAM_AVAILABLE
  • MEM_RAM_SIZE
  • MEM_VIRTUAL_AVAILABLE
  • MEM_VIRTUAL_SIZE
  • HOST
  • OS
  • DISK_SPACE
  • LOAD1MIN
  • LOAD5MIN
  • LOAD15MIN
  • PLATFORM
  • PROCESSOR_NUM
  • PROCESSOR_BOGOMIPS
  • SITE_LOCATION
  • SITE_COUNTRY
  • SITE_DOMAIN
  • CUSTOM_REQUIREMENT
  • RUNTIME_ENV_STRING
  • RUNTIME_ENV_NUMBER
  • operator: declares the relation between the actual value of the looked up attribute category and the value expressed in the Requirement.

It can assume one of the following values:

  • eq (Equal)
  • le (Less or Equal)
  • ge (Greater or Equal)
  • gt (Greater than)
  • lt (Less than)
  • exist (can be also used in terms of "contains")
  • ne (Not Equal)
  • 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>

  • A simple example:
  1. <GHNRequirements>
  2.         <Requirement category="OS" operator="exist" value="Linux" requirement=""/>
  3.         <Requirement category="PROCESSOR_NUM" operator="ge"  value="2" requirement=""/>
  4. </GHNRequirements>

The example above means: "This package can be deployed on a gHN running on a Linux Operating System (Line 2) (it requires that the value of OS in the GHN profile contains the string Linux) and having at least 2 processors (Line 3)". Note: in both cases the requirement attribute is not relevant.

  • Example. Accessing the run time environment variables:
  1. <GHNRequirements>
  2.         <Requirement category="RUNTIME_ENV_STRING" requirement="ANT_HOME" operator="eq" value="/usr/share/ant" />
  3.         <Requirement category="RUNTIME_ENV_STRING" requirement="GLOBUS_OPTIONS" operator="exist"  value="" />
  4. </GHNRequirements>

The former block (Line 2) checks that the environment contains the key ANT_HOME and that its value is equal to /usr/share/ant while the latter (Line 3) simply checks that the environment contains the key GLOBUS_OPTIONS regardless its value.

  • Putting them together a clarifying example:
  1. <GHNRequirements>
  2.         <Requirement category="RUNTIME_ENV_STRING" requirement="Java" operator="exist" value="1.5" />
  3.         <Requirement category="RUNTIME_ENV_STRING" requirement="gCore-version" operator="eq"  value="1.0.1" />
  4.         <Requirement category="RUNTIME_ENV_STRING" requirement="CATALINA_HOME" operator="exist" value="" />
  5.         <Requirement category="SITE_DOMAIN" requirement="" operator="exist" value="research-infrastructures.eu" />
  6.         <Requirement category="OS" requirement="" operator="exist" value="Linux" />
  7.         <Requirement category="OS" requirement="" operator="eq" value="i386" />
  8. </GHNRequirements>

Here a concrete example where the user statically claims that its service to run needs:

  • A jdk having version 1.5.* (note the exist operator)
  • An installed gCore having version 1.0.1
  • That apache tomcat is installed on the machine (it is enough to check the CATALINA_HOME environment variable is defined)
  • The ghn must run in the *.research-infrastructures.eu domain
  • The operating system must be Linux*
  • The platform must be i386
  • Example. Custom queries:

To give freedom to customize the access to specific paths in the resources a CUSTOM_REQUIREMENT category has been introduced. The example below is a sample:

<Requirement category="CUSTOM_REQUIREMENT" operator="exist"  value="/GHNDescription/Architecture[@PlatformType = 'i386']" requirement="" />

The same result can be obtained by the query:

<Requirement category="PLATFORM" operator="eq"  value="i386" requirement=""/>


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

Depending on the type of the package, there are some specific elements to report on the package profile.

MainPackage


A MainPackage is a package than once deployed it generates an instance of a gCube Service.

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>
                <MavenCoordinates>
 			[...]
 		</MavenCoordinates>
 		<Mandatory level="GHN"/>
 		<Shareable level="VO"/>
 		<GHNRequirements>
 			<Requirement category="Site"  requirement="string" value="java1.5" operator="ge"/>
 		</GHNRequirements>
 		<GARArchive>org.gcube.common.vremanagement.deployer.gar</GARArchive>
 		<PortType>
 			<Name>gcube/common/vremanagement/Deployer</Name>
 			<Security/>			
 		</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 any third party package that can be dynamically deployed.

Here is an example of a software declared of type=library (meaning that its files are copied in the $GLOBUS_LOCATION folder) and using installation and reboot scripts:

<?xml version="1.0" encoding="UTF-8"?>
<Resource xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<ID></ID>
	<Type>Service</Type>
	<Profile>
		<Description>eXistDB</Description>
		<Class>ExternalSoftware</Class>
		<Name>exist</Name>
		<Version>1.2.6</Version>
		<Packages>
			<Software>
				<Description>eXist XML Database</Description>
				<Name>exist</Name>
				<Version>1.2.6</Version>
				<MultiVersion value="true"/>
				<Mandatory level="VO"/>
				<Shareable level="VO"/>
				<InstallScripts>
	 				<File>install.sh</File>
	 			</InstallScripts>
				<RebootScripts>
					<File>reboot.sh</File>
				</RebootScripts>
	 			<Type>library</Type>
				<Files>
					<File>commons-collections-3.1.jar</File>
					<File>commons-pool-1.4.jar</File>
					<File>excalibur-cli-1.0.jar</File>
					<File>exist.jar</File>
					<File>exist-optional.jar</File>
					<File>javax.servlet-1.4.jar</File>
					<File>jEdit-syntax.jar</File>
					<File>jgroups-all.jar</File>
					<File>jline-0_9_5.jar</File>
					<File>jta.jar</File>
					<File>quartz-1.6.0.jar</File>
					<File>stax-api-1.0.1.jar</File>
					<File>sunxacml.jar</File>
					<File>xmldb.jar</File>
					<File>xmlrpc-client-3.1.1.jar</File>
					<File>xmlrpc-common-3.1.1.jar</File>
					<File>xmlrpc-server-3.1.1.jar</File>
					<!--File>xmlrpc-1.2-patched.jar</File-->
					<File>conf.xml</File>
					<File>catalog.xml</File>
				</Files>
			</Software>
		</Packages>
	</Profile>
</Resource>
Files

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