Difference between revisions of "Profile Specification"

Revision as of 19:40, 14 February 2007

How to write the profile specification for this component depending on its type.

Preliminary definitions

DILIGENT Resources and profiles

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:

• VDL
• 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. 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 CNR's SVN Repository In the following, we will focus about how to compile service profile

The Service resource

Usually, a Service is defined as a software system that delivers functionalities. In DILIGENT, 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 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. 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 DHN. A Package can be:

• a WSRFService, representing a package that once deployed produces a WSRF Service (a service able to manage stateful resources following the WS-Resource patterns);
• a 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 GridJob, representing a package containing the code and the related information needed to run a certain job on the grid infrastructure;
• a Library, representing a software library (typically a JAR) that can be hosted on a DHN. There are three types of library:
  • 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.
• Software, a thirdy party software distributed with the service that can be dynamically deployed;
• ExternalSoftware, a thirdy party software available on the ETICS repository that can be dynamically deployed.

Composition

The set of Packages forming a Service is composed by:

1. one and only one Package of WSRFService or Portlet type (the main package or the entry point)
2. an arbitrary number of other Packages of different type logically related (even if not used) by it.

The "main" part of a Service is, of course, the WSRFService package from which the related Running Instance resource is generated. The other packages are used by it or distributed with it in order to be used by other Services that need to interact with a Running Instance of the Service.

How to specify dependencies

The WSRFService 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)

  → specified as package Dependency (see Dependencies in a Package element)

• software developed and distributed within other DILIGENT services

  → specified as package Dependency (see Dependencies in a Package element)

• thirdy party deployable software used only by this service

  → specified as package Dependency against a Software or a Library package (see Dependencies in a Package element)

• thirdy party deployable software used by other services

  → specified as package Dependency against an ExternalSoftware package (see Dependencies in a Package element and ExternalSoftware definition)

• thirdy party software that is not dynamically deployable

  → specified as DHNRequirement (DHN Requirement in a Package element)

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.

<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>

Common elements

Class

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

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

DescriptiveParameters

QoS

DeploymentInfo

DLDependencies: DL Logical Dependencies

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)

PackageList section

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 (WSRFService, Library, Portlet, GridJob, Software, ExternalSoftware). The only constraint is that one and only one WSRFService element is accepted.

Common elements

Example

The following example shows the elements of a Package definition common to all types of Package.

<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]

	<OtherFiles/>
	<OtherProperties/>    
</Package>

PackageName

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

PackageType

It identifies the type of the package. Allowed values are:

• WSRFService
• Library
• GridJob
• Portlet

Version

The version of the package. It has to be in the form of X.Y.

DLMandatory

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.

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

It states if the package can be shared across multiple DLs (true) or if it is DL-Specific (false).

DisposeInterfaceSupport

Not used

MultiVersionSupport

Not used

VOSharingSupport

It states if the package can be shared across multiple VOs (true) or if it is VO-Specific (false).

ManifestFile

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 the package is downloaded and uncompressed.

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

DHNRequirements

ConfigurationFiles

OtherFiles

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

This is a free section where you can insert anything that cannot be included in the other elements of the profile. For 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.

Package-specific sections

WSRFService

Example:

<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>

GARArchive

BuildFile

DeploymentOptions

ArchitecturalPattern

This element declares the architectural pattern adopted by the WSRF service.

ServiceEquivalenceFunctions element: Fix the service equivalence

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. So far, the following fuction are used in the infrastructure:

• match, used by the Active Planner service to discriminate among two Running Instances of the same service

WSRFEntry

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.

EntryName

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

Security

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

<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>

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

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:

1. shared library
2. stub library
3. external library

Shared Library

Example

<Library>
	<Type>shared</Type>
	<Parameters/>
	<LibraryFile>ip/org_diligentproject_informationservice_disip.jar</LibraryFile>
</Library>

• Type

Fixed: "shared"

• Parameters

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.

• LibraryFile

The path and the name of the library's file in the service archive.

Stub Library

Example:

<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>

• Type

Fixed: "stub"

• IsStubOf

This element declares of which WSRFService package the library is stub of.

• Parameters

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.

• LibraryFile

The path and the name of the library's file in the service archive.

External Library

Example:

<Library>
	<Type>external</Type>
	<Paramenters/>
	<ExternalLibraryFile>
		<ETICS-ID>24545-7fjm-265765</ETICS-ID>
		<Description>Apache Common IO</Description>
	</ExternalLibraryFile>					
</Library>

• Type

Fixed: "external"

• Parameters

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

It includes the ID on the ETICS Repository and a human readable description.

Portlet

Example:

<Portlet>
	<WARArchive>String</WARArchive>
	<BuildFile>String</BuildFile>
	<DeploymentOptions/>
	<Parameters>
		<Param>
			<Name>String</Name>
			<AllowedValues>
				<Value>*</Value>
			</AllowedValues>
		</Param>	
	</Parameters>
	<Service>
		<wsdl:definitions targetNamespace="http://diligentproject.org/..." name="...">
		</wsdl:definitions>
	</Service>
</Portlet>

Software

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

Example:

<Software>
	<FileList>
		<File>setup.exe</File>
		<File>data.cab</File>
	</FileList>
	<Description>my software</Description>
</Software>

• FileList

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

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:

• 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.

These software must be uploaded in the ETICS Repository and referred here.

Example:

<ExternalSoftware>
	<ETICS-ID>5eed2db4-10cb-48ac-bc34-c0de2e09a4f9</ETICS-ID>
	<Description>Lucene</Description>
</ExternalSoftware>

• ETICS-ID

A valid ID of an external software uploaded on the ETICS Repository

• Descritpion

A human readable description of the software referred by the ID (can be left empty).

-- Manuele Simi