Solution Deployment Descriptor Specification 1.0

Committee Draft 4

8 April 2008

Specification URIs:

This Version:

http://docs.oasis-open.org/sdd/v1.0/cd04/sdd-spec-v1.0-cd04.html

http://docs.oasis-open.org/sdd/v1.0/cd04/sdd-spec-v1.0-cd04.doc

http://docs.oasis-open.org/sdd/v1.0/cd04/sdd-spec-v1.0-cd04.pdf

Previous Version:

http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01.html

http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01.doc

http://docs.oasis-open.org/sdd/v1.0/pr01/sdd-spec-v1.0-pr01.pdf

Latest Version:

http://docs.oasis-open.org/sdd/v1.0/sdd-spec-v1.0.html

http://docs.oasis-open.org/sdd/v1.0/sdd-spec-v1.0.doc

http://docs.oasis-open.org/sdd/v1.0/sdd-spec-v1.0.pdf

Technical Committee:

OASIS Solution Deployment Descriptor (SDD) TC

Chair(s):

Brent Miller, IBM Corporation

Editor(s):

Julia McCarthy, IBM Corporation

Robert Dickau, Macrovision Corporation

Merri Jensen, SAS Institute, Inc.

Related work:

None

Declared XML Namespace(s):

sdd-common=http://docs.oasis-open.org/sdd/ns/common

sdd-pd=http://docs.oasis-open.org/sdd/ns/packageDescriptor

sdd-dd=http://docs.oasis-open.org/sdd/ns/deploymentDescriptor

Abstract:

This specification defines schema for two XML document types: Package Descriptors and Deployment Descriptors. Package Descriptors define characteristics of a package used to deploy a solution. Deployment Descriptors define characteristics of the content of a solution package, including the requirements that are relevant for creation, configuration and maintenance of the solution content. The semantics of the descriptors are fully defined, allowing software implementations to precisely understand the intent of the descriptor authors and to use the information provided in the descriptors to support solution deployment.

Status:

This document was last revised or approved by the OASIS Solution Deployment Descriptor (SDD) Technical Committee on the above date. The level of approval is also listed above. Check the “Latest Version” or “Latest Approved Version” location noted above for possible later revisions of this document.

Technical Committee members should send comments on this specification to the Technical Committee’s email list. Others should send comments to the Technical Committee by using the “Send A Comment” button on the Technical Committee’s web page at http://www.oasis-open.org/committees/sdd/.

For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the Technical Committee web page (http://www.oasis-open.org/committees/sdd/ipr.php.

The non-normative errata page for this specification is located at http://www.oasis-open.org/committees/sdd/.

 

Notices

Copyright © OASIS® 2007, 2008. All Rights Reserved.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.

OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.

The name "OASIS", is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see http://www.oasis-open.org/who/trademark.php for above guidance.

 

Table of Contents

Notices. 3

Table of Contents. 4

1      Introduction. 9

1.1 Terminology. 9

1.2 Purpose. 9

1.3 Scope. 10

1.4 Audience. 10

1.5 How to Read this Document 10

1.6 Motivation. 10

1.7 Requirements. 11

1.8 XML Namespaces. 13

1.9 Notational Conventions. 13

1.10 General Document Conventions. 13

1.11 Diagram Conventions. 13

1.12 Normative References. 15

1.13 Non-Normative References. 15

2      Solution Deployment Descriptor Overview. 16

2.1 Package and Deployment Descriptors. 16

2.2 Topology. 16

2.3 Content and Artifacts. 16

2.4 Resulting and Changed Resources. 17

2.5 Base, Selectable and Localization Content Hierarchies. 17

2.6 Constraints. 18

2.7 Requirements. 18

2.8 Conditions. 18

2.9 Variables. 18

3      Package Descriptor 19

3.1 PackageDescriptor 19

3.1.1 PackageDescriptor Property Summary. 19

3.1.2 PackageDescriptor Property Usage Notes. 19

3.2 DescriptorInfoGroup. 20

3.2.1 DescriptorInfoGroup Property Usage Notes. 20

3.3 PackageIdentityType. 22

3.3.1 PackageIdentityType Property Summary. 22

3.3.2 PackageIdentityType Property Usage Notes. 22

3.4 IdentityType. 24

3.4.1 IdentityType Property Summary. 24

3.4.2 IdentityType Property Usage Notes. 25

3.5 MaintenanceInformationType. 26

3.5.1 MaintenanceInformationType Property Summary. 26

3.5.2 MaintenanceInformationType Property Usage Notes. 26

3.6 FixIdentityType. 27

3.6.1 FixIdentityType Property Summary. 27

3.6.2 FixIdentityType Property Usage Notes. 27

3.7 BuildInformationType. 27

3.7.1 BuildInformationType Property Summary. 28

3.7.2 BuildInformationType Property Usage Notes. 28

3.8 ManufacturerType. 28

3.8.1 ManufacturerType Property Summary. 28

3.8.2 ManufacturerType Property Usage Notes. 28

3.9 LocationType. 29

3.9.1 LocationType Property Summary. 29

3.9.2 LocationType Property Usage Notes. 29

3.10 VersionType. 29

3.11 ContentsType. 29

3.11.1 ContentsType Property Summary. 29

3.11.2 ContentsType Property Usage Notes. 30

3.12 ContentType. 30

3.12.1 ContentType Property Summary. 30

3.12.2 ContentType Property Usage Notes. 30

3.13 DigestInfoGroup. 31

3.13.1 DigestInfoGroup Property Usage Notes. 31

4      Deployment Descriptor 32

4.1 DeploymentDescriptor 32

4.1.1 DeploymentDescriptor Property Summary. 33

4.1.2 DeploymentDescriptor Property Usage Notes. 33

4.2 Topology. 34

4.2.1 TopologyType. 35

4.2.2 ResourceType. 36

4.2.3 PropertyType. 39

4.2.4 ResultingPropertyType. 39

4.3 Atomic Content Elements. 40

4.3.1 InstallableUnitType. 41

4.3.2 ConfigurationUnitType. 44

4.3.3 ArtifactType. 46

4.3.4 InstallationArtifactsType. 49

4.3.5 ConfigurationArtifactsType. 50

4.3.6 OperationListType. 50

4.3.7 OperationType. 50

4.3.8 ArgumentListType. 51

4.3.9 ArgumentType. 51

4.3.10 OutputVariableListType. 52

4.3.11 OutputVariableType. 53

4.3.12 AdditionalContentType. 53

4.3.13 SubstitutionType. 54

4.3.14 CompletionType. 55

4.4 Constraints. 56

4.4.1 CapacityConstraintType. 57

4.4.2 CapacityValueType. 58

4.4.3 ConsumptionConstraintType. 59

4.4.4 ConsumptionConstraintValueType. 60

4.4.5 PropertyConstraintType. 61

4.4.6 PropertyValueListType. 61

4.4.7 VersionConstraintType. 62

4.4.8 VersionConstraintValueType. 63

4.4.9 VersionValueType. 63

4.4.10 VersionRangeType. 64

4.4.11 MaxVersionType. 65

4.4.12 UniquenessConstraintType. 65

4.4.13 RelationshipConstraintType. 66

4.5 Conditions. 67

4.5.1 ConditionType. 67

4.5.2 AlternativeConditionalType. 69

4.5.3 ConditionalResourceConstraintType. 70

4.5.4 ConditionalPropertyConstraintType. 72

4.6 Variables. 73

4.6.1 VariableExpressionType. 73

4.6.2 BaseVariableType. 74

4.6.3 VariablesType. 75

4.6.4 ParametersType. 76

4.6.5 BaseParameterType. 77

4.6.6 IntegerParameterType. 78

4.6.7 BoundaryType. 79

4.6.8 StringParameterType. 80

4.6.9 StringCaseType. 81

4.6.10 BooleanParameterType. 81

4.6.11 URIParameterType. 81

4.6.12 ResourcePropertyType. 82

4.6.13 DerivedVariableType. 83

4.6.14 ConditionalDerivedVariableExpressionType. 83

4.7 Requirements. 84

4.7.1 RequirementsType. 84

4.7.2 RequirementType. 85

4.7.3 AlternativeRequirementType. 87

4.7.4 ResourceConstraintGroup. 88

4.7.5 RequirementResourceConstraintType. 90

4.7.6 InternalDependencyType. 91

4.7.7 DependencyType. 92

4.7.8 RequiredBaseType. 93

4.7.9 RequiredBaseConstraintType. 94

4.7.10 AlternativeRequiredBaseConstraintType. 96

4.8 Resulting and Changed Resources. 97

4.8.1 ResultingResourceType. 97

4.8.2 ResultingChangeType. 99

4.8.3 RelationshipType. 101

4.9 Composite Content Elements. 101

4.9.1 CompositeInstallableType. 103

4.9.2 CompositeUnitType. 106

4.10 Aggregation. 108

4.10.1 ReferencedPackageType. 112

4.10.2 ResourceMapType. 115

4.10.3 ResultingResourceMapType. 116

4.10.4 ResultingChangeMapType. 118

4.10.5 RequisitesType. 119

4.11 Base Content 120

4.11.1 BaseContentType. 120

4.12 Content Selectability. 121

4.12.1 SelectableContentType. 121

4.12.2 GroupsType. 122

4.12.3 GroupType. 123

4.12.4 FeaturesType. 124

4.12.5 FeatureType. 125

4.12.6 NestedFeatureType. 126

4.12.7 MultiplicityType. 129

4.12.8 FeatureReferenceType. 130

4.12.9 ContentElementReferenceType. 130

4.12.10 PackageFeatureReferenceType. 131

4.12.11 ConstrainedResourceType. 131

4.12.12 MultiplicityConstraintType. 132

4.12.13 RequiredContentSelectionType. 132

4.12.14 ContentSelectionFeatureType. 133

4.12.15 MultiSelectType. 134

4.13 Localization. 134

4.13.1 LocalizationContentType. 135

4.13.2 LocalizationUnitType. 136

4.13.3 CompositeLocalizationUnitType. 139

4.13.4 LanguageSelectionsType. 142

4.13.5 OptionalLanguagesType. 142

4.13.6 LanguagesType. 143

4.13.7 LanguageType. 143

4.13.8 LanguageSetType. 144

4.14 Display Information. 145

4.14.1 DescriptionGroup. 145

4.14.2 DisplayElementGroup. 145

4.14.3 DisplayTextType. 146

5      Conformance. 147

5.1 General Conformance Statements. 147

5.2 Conformance Levels. 147

5.2.1 CL Capabilities. 147

5.2.2 Conformance Level Differences. 148

5.3 Profiles. 150

5.3.1 Profile Creation. 150

5.3.2 Profile Publication. 150

5.3.3 Profile Applicability. 151

5.4 Compatibility Statements. 151

5.5 Conformance Clause. 151

5.5.1 Conformance for Users of This Specification. 151

5.5.2 Conformance for This Specification Itself 151

A.     Schema File List 153

B.     Acknowledgements. 154

 


1    Introduction

The Solution Deployment Descriptor (SDD) specification defines a standard, in the form of a schema for XML documents, called Solution Deployment Descriptors, or SDDs. SDDs define metadata that describes the packaging and deployment characteristics of resources that are relevant for their lifecycle management, including creation, configuration and maintenance.

A.1 Terminology

The following terms are used in this specification in a specialized sense that might differ from definitions elsewhere.

Artifact

Zero or more files and/or metadata used to perform a deployment lifecycle operation on a resource.

Deployment lifecycle

The stages marking maturation of a solution: develop, package, integrate, manufacture, install, configure, evaluate, deploy into production, upgrade and/or update, uninstall.

Host Resource

A resource that provides the execution environment for another resource.

Package

A set of artifacts used to perform deployment lifecycle operations on a group of related resources that make up a solution.

Resource

A particular element of a computing environment, such as a computer system, an operating system, a Web server, a software application, or a complex solution.

Solution

One or more interrelated resources on which deployment lifecycle operations can be performed.

Target Resource

A resource that processes artifacts to perform deployment lifecycle operations on another resource. The host resource often serves as the target resource.

Topology

The physical or logical layout of a solution’s resources.

Update (n.)

A package that replaces a limited set of the resources in a solution instance. An update does not require migration.

Upgrade (n.)

A package that replaces all, or a significant portion of, the resources used in a solution. An upgrade might or might not require migration.

1.1 Purpose

The purpose of this document is to provide the normative specification of the SDD, including concepts, structure, syntax, semantics and usage.

1.2 Scope

This document is the specification for the SDD. It consists of both normative and non-normative prose, diagrams, schema and examples. The document is intended to facilitate an understanding of the SDD concepts, structure, syntax, semantics and usage. This document is not intended to be a tutorial.

This document is the full SDD specification, but it also is augmented with other documents produced by the SDD TC, including the SDD XML Schema and Examples (see Appendix [A]), [SDDP], [SDDSP] and the set of SDD profiles (see section [5.3]), as well as documents produced by others (see section [5.3.1]).

1.3 Audience

This document is intended to assist those who require an understanding of the nature and details of the SDD. This includes architects, developers, solution integrators and service/support personnel who generate, consume, or otherwise use SDDs, as well as those who develop tooling and applications for constructing and deploying SDDs.

1.4 How to Read this Document

The various audiences of this specification might have different objectives and purposes when reading the document. You might wish to generally understand the SDD, or learn the details of the SDD to create or consume SDDs, or use the document as a reference.

§         If your purpose is to understand the major capabilities and characteristics of the SDD and how they fit together, start by reading the Introductions to the major sections: [3], [4] and [4.1]–[4.14].

§         If your purpose is to understand the major elements of the SDD and how they work together to accomplish the goals of this specification, read in addition to the above, the introductions to each of the type sections [3.1]–[3.13] and the type subsections within sections [4.2]–[4.14].

§         If your purpose is to understand the syntax of the SDD, look at the tables in each of the Property Summary sections.

§         If your purpose is to understand the semantics of the elements and attributes of the SDD, read the Property Usage Notes sections.

§         If your purpose is to understand only the package descriptor, subset the above suggestions to focus on the sub-sections within section [3].

§         If your purpose is to understand only the deployment descriptor, subset the above suggestions to focus on the sub-sections within section [4].

1.5 Motivation

The motivation for producing this specification is best expressed in this excerpt from the SDD Technical Committee’s charter:

Deployment and lifecycle management of a set of interrelated software, hereinafter referred to as a solution, is a predominantly manual operation because there is currently no standardized way to express installation packaging for a multi-platform environment. Each hosting platform or operating system has its own format for expressing packaging of a single installable unit but, even on these homogeneous platforms, there is no standardized way to combine packages into a single aggregated unit without significant re-creation of the dependency and installation instructions. The problem is compounded when the solution is to be deployed across multiple, heterogeneous, platforms. A standard for describing the packaging and mechanism to express dependencies and various lifecycle management operations within the package would alleviate these problems and subsequently enable automation of these highly manual and error-prone tasks.

The purpose of this Technical Committee is to define XML schema to describe the characteristics of an installable unit (IU) of software that are relevant for core aspects of its deployment, configuration and maintenance. This document will be referred to as the Solution Deployment Descriptor (SDD).

SDDs will benefit member companies and the industry in general by providing a consistent model and semantics to address the needs of all aspects of the IT industry dealing with software deployment, configuration and lifecycle management. The benefits of this work include:

·         ability to describe software solution packages for both single and multi-platform heterogeneous environments.

·         ability to describe software solution packages independent of the software installation technology or supplier.

·         ability to provide information necessary to permit full lifecycle maintenance of software solutions.

1.6 Requirements

A summary of requirements satisfied by this SDD specification follows. Detailed requirements that support approved use cases are available at the SDD TC Web page, http://www.oasis-open.org/committees/sdd.

Solution lifecycle management

The SDD must provide information to support the complete lifecycle of a software solution. Certain key requirements are applicable to all phases of deployment lifecycle operation: planning, installation, configuration, maintenance, upgrade, migration and uninstallation.

Solution requirements for environment to perform lifecycle management tasks

A deployment lifecycle operation on a target resource is often dependent on a certain set of conditions that must exist on the target. This set of pre-existing conditions is known as the environment. If successful deployment lifecycle operations are dependent on a certain set of pre-existing conditions (environment), then the SDD specification must support the ability to specify the required environment.

Projected changes to environment

The SDD specification must support the definition of environment changes that become effective once the lifecycle operation is complete.

Solution instance variability

The SDD specification must support the definition of the appropriate information for a runtime to vary the ways in which the solution can be deployed. This information is also needed to enable an integrator to control the variability according to the needs of their higher-level solution.

This variability includes the information to control (1) the subset of capability that can be deployed; (2) setting the initial configuration of the solution; and (3) varying the topology in which the solution can be deployed.

Solution composition

The SDD specification must support the ability for the author to compose solution packages from multiple components, products, or solutions.

Solution and packaging identity

The SDD specification must support the definition of identity information for the solution package, resources that make up the solution, and solution itself to support use cases including asset management, license management, support/update entitlement, component reuse during development, reports and queries from a package repository, identifying associated documentation, solution lifecycle management, traceability to build/development environment and problem management systems, correlation into the hosting environment, component reuse, and maintenance history. Also, the SDD specification must support the definition of the identity description information used by a runtime to assist a user in making correct decisions about solution installation. The SDD specification must support the definition of the information that uniquely identifies the SDD descriptor and the ability to identify the version of the SDD. The customer should be able to identify the solution packages with consistent names.

Physical packaging

Physical packaging information should be contained in a separate media descriptor. The deployment model for a solution should be decoupled from the details of physical packaging. The format and structure of the physical packaging is outside the scope of SDD v1.0.

Interoperability with existing software packaging technologies

The SDD specification must support the ability for the author to compose solutions from existing software packages that do not have an SDD. This means that the SDD should be able to describe existing software packages.

Conform to external standards

The SDD specification must provide for alternative descriptive text to be defined for any images, animations, or audio information contained in the descriptor.

Decision support

Requirements to perform lifecycle management operations within various target environments may not be satisfied in the target’s current state but might be able to be satisfied with additional operations. For example, successful deployment of a set of Java[1] components is dependent on the existence of a Java runtime environment that is not included with the solution. The SDD should have the ability to specify information that will assist lifecycle management tools in planning for, accessing and installing these external requirements.

Specification organization

The SDD specification must provide the semantic behavior expected by producers and consumers of SDDs. This information allows for the producers to ensure that the consumers of their SDDs will provide the support intended.

Solution metadata

The SDD metadata may not encompass all of the information about the solution in all contexts in which the solution can be deployed. Additional metadata that is outside of the scope of the SDD is available at the SDD TC Web page, http://www.oasis-open.org/committees/sdd.

Globalization

For all content in the SDD that would be displayed to a user, the specification must support the definition of strings for multiple locales; for example, this content must be localizable.

Align with other standards bodies

Satisfying all the requirements listed here calls for extensive standardization in specific areas. The requirements should thus be aligned with other appropriate standards bodies. The SDD reuses existing OASIS and other standards where appropriate and aligns with other standards bodies (for example, [OGF-ACS]) that are developing standards in the same domain as SDD.

1.7 XML Namespaces

The XML namespaces defined as part of this specification are:

§         sdd-pd: stands for the package descriptor portion of the SDD namespace.

§         sdd-dd: stands for the deployment descriptor portion of the SDD namespace.

§         sdd-common: stands for the common (shared) types, elements and groups of the SDD namespace.

For XML namespaces not defined as part of this specification, conventional XML namespace prefixes are used as follows, regardless of whether a namespace declaration is present in the example:

§         The prefix xsd: stands for the W3C XML Schema namespace [XSD].

§         The prefix ds: stands for the digital signature namespace [XMLDSIG-CORE].

1.8 Notational Conventions

Everything in the specification, including the Appendices, is considered normative except for the abstract, examples and any sections or other material marked as non-normative.

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY” and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].

These keywords are capitalized when used unambiguously to specify requirements or application features and behavior. When these words are not capitalized, they are meant in their natural-language sense.

1.9 General Document Conventions

In describing XML elements and attributes of the SDD schema, this document contains many cross-references. Such references appear as the referenced section number inside square brackets, for example, [4.5]. In electronic versions of this specification, the cross-references can act as links the target section.

The following property naming convention is used in the schema: Element and type names begin with an uppercase letter and attribute names begin with a lowercase letter.

Italics are used to identify element and attribute names, type names and enumerated values defined by an SDD type.

In describing the XML schema, each section typically contains the following subsections:

§         A diagram illustrating the element, group, or type that is specified in the section.

§         Property Summary: A table listing the schema elements and attributes, along with the data type, cardinality and description for each one.

When specified, extension points are listed in the tables with no name and a type of xsd:any for element extensions and xsd:anyAttribute for attribute extensions. Cardinality is also provided.

When a type is an extension of another type, the extended type is listed in the table with no name and prefixed with [extends]. The extended type’s properties can be referenced from the appropriate section listed in the description column.

When the schema specifies a default or fixed attribute value, that value is prefixed with two asterisks, as in **default value=“true”.

§         Property Usage Notes: A list of the elements and attributes, along with more detailed prose descriptions of the properties and how they fit into the schema as a whole.

§         Not all sections contain every one of the preceding subsections.

1.10 Diagram Conventions

Sections 3 and 4 of this specification contain diagrams that illustrate the structure of elements, data types and groups used throughout the SDD schema. Figure 1 is an example of this type of diagram.

Figure 1: Sample XML structure diagram.

Elements are represented by the element name inside a rectangle. A rectangle with a solid border denotes an element.

Where appropriate, the cardinality of an element is indicated by a rectangle with the cardinality listed underneath, using the form “min..max”. For example, “1..∞” indicates a minimum of one occurrence of the element and an unbounded upper limit:

 

References to global elements are denoted by a small arrow in the lower right corner of the element’s rectangle:

 

Attributes are denoted by a “@” symbol followed by the attribute name, inside a dashed rectangle.

 

Complex types are denoted by a rectangle with all the corners truncated and a white square followed by the element name:

 

Simple types are denoted by a rectangle with all the corners truncated and a white triangle followed by the element name:

 

Groups are denoted by a rectangle with three small squares followed by the group name: black squares and a solid rectangle indicate element groups and white squares with a dashed rectangle indicate attribute groups:

 

A plus sign on the right border of a component indicates hidden child elements or attributes. When hidden, the child elements are usually described in a separate section.

There are two connectors (or compositors) used in the SDD schema diagrams to combine elements:

§         A sequence of elements is indicated by the following symbol:

§         A choice among elements is indicated by the following symbol:

A large yellow box indicates a data type that is referenced.

Blue shading appearing in a figure has no significance; it simply indicates that a component was currently selected in the XML editor.

The XSD schema figures were created with <oXygen/>.

1.11 Normative References

[CL2_Schema]       Solution Deployment Descriptor Schema

                              See Appendix [A] for location.

[CONFORM]            OASIS, OASIS Conformance Requirements for Specifications 1.0, http://www.oasis-open.org/committees/download.php/305/conformance_requirements-v1.pdf.

[IANA-CHARSET]    Internet Assigned Numbers Authority, Character Sets, http://www.iana.org/assignments/character-sets, modified December 2006.

[IETF-UUID]            Internet Engineering Task Force Draft Specification, http://www.ietf.org/rfc/rfc4122.txt.

[ISO639.2]              Library of Congress, Codes for the Representation of Names of Languages, http://www.loc.gov/standards/iso639-2/englangn.html.

[ISO3166]               International Organization for Standardization, English Country Names and Code Elements, http://www.iso.ch/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html.

[RFC2119]               S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, http://www.ietf.org/rfc/rfc2119.txt, IETF RFC 2119, March 1997.

[RFC3066]               H. Alvestrand, ed. RFC 3066: Tags for the Identification of Languages 1995, http://www.ietf.org/rfc/rfc3066.txt.

[UNIT]                     Bureau International des Poids et Mesures, http://www.bipm.fr.

[XMLDSIG-CORE]   Bartel et al., XML-Signature Syntax and Processing, http://www.w3.org/TR/xmldsig-core/, W3C Recommendation, February 2002.

[XSD]                     W3C Schema Working Group, XML Schema, http://www.w3.org/TR/xmlschema-1/, W3C Recommendation, October 2004.

 

1.12 Non-Normative References

[CL1_Schema]       Solution Deployment Descriptor Conformance Level 1 Schema

                              See Appendix [A] for location.

[CIM]                      Distributed Management Task Force, Inc., Common Information Model (CIM) http://www.dmtf.org/standards/cim/.

[OGF-ACS]             Open Grid Forum, Application Contents Service WG (ACS-WG), http://www.ogf.org/gf/group_info/view.php?group=acs-wg.

[SDDP]                   Solution Deployment Descriptor Primer

http://docs.oasis-open.org/sdd/v1.0/sdd-primer-v1.0.doc

http://docs.oasis-open.org/sdd/v1.0/sdd-primer-v1.0.pdf

http://docs.oasis-open.org/sdd/v1.0/sdd-primer-v1.0.html

[SDDSP]                 Solution Deployment Descriptor Starter Profile

http://docs.oasis-open.org/sdd/v1.0/sdd-starter-profile-v1.0.doc

http://docs.oasis-open.org/sdd/v1.0/sdd-starter-profile-v1.0.pdf

http://docs.oasis-open.org/sdd/v1.0/sdd-starter-profile-v1.0.html

 

 

 

2    Solution Deployment Descriptor Overview

2.1 Package and Deployment Descriptors

The package descriptor defines package content which includes artifacts whose processing results in deployment of the software package. The deployment descriptor defines metadata associated with those artifacts. The SDD package descriptor defines the package identity, the package content and various other attributes of the package. Each SDD consists of exactly one deployment descriptor and one package descriptor. The deployment descriptor is where the topology, selectability, inputs, requirements and conditions of the deployment are described.

2.2 Topology

The SDD’s topology describes all the resources that may be required, created or modified when any of the deployment operations supported by the SDD are performed.

Primary identifying characteristics of the resources can be defined in topology. The topology includes identification of hosts–hosted by relationships between resources. It is usual that only a subset of the resources described in topology will play a role in any particular deployment. This is determined by the selection of content elements for the particular deployment. The resources that are required, created or modified by the content elements in scope for the deployment are the ones that will participate in the deployment and so will be associated with resources in the deployment environment.

At deployment time, definitions of the resources that participate in that particular deployment are associated with actual resource instances in the deployment environment. The mechanism for associating resource definitions with resource instances is not defined by the SDD.

The only resource definitions in the SDD are in topology. All other mention of resources in the SDD are references to the resource definitions in the topology.

2.3 Content and Artifacts

Metadata throughout the deployment descriptor is associated with package content in the definition of atomic content elements. The atomic content elements are InstallableUnit, ConfigurationUnit and LocalizationUnit. These are the only content elements that define Artifacts elements.

Artifact elements identify an artifact file or set of files defined in package content whose processing will perform all or a portion of the deployment for a particular deployment lifecycle operation. Artifact elements define the inputs and outputs, substitution values and types associated with the artifact files. The content element’s target resource, identified by targetResourceRef, processes the artifact files with the defined inputs to perform deployment operations. Examples of artifact types include zip files, rpm files and executable install files. Artifact types are not defined by this specification. The artifact types defined in the SDD need to be understood by software that processes the SDD. Profiles are used to communicate the artifact types that an implementation is capable of processing [5.3].

Composite content elements organize the content of an SDD but do not define artifacts used to deploy SDD content. There are three types of composite content elements: CompositeInstallable, CompositeUnit and CompositeLocalizationUnit.

CompositeInstallable is used any time that more than one content element is defined in support of one operation on the package; any time aggregation of SDDs is needed; or any time the package includes selectable content. CompositeInstallable is the root of a content hierarchy that supports a single deployment lifecycle operation. It can define a base content hierarchy, a localization content hierarchy and a selectable content hierarchy that includes selection criteria. One SDD can have more than one CompositeInstallable–each supporting a different operation.

CompositeUnit is used to organize content elements within the base or selectable content hierarchies. CompositeUnits can define InstallableUnits, ConfigurationUnits, ContainedPackages and other CompositeUnits. Requirements, conditions and variables that are common to all content elements defined by the CompositeUnit can be defined in the CompositeUnit to avoid repetition. Within the selectable content hierarchy, a CompositeUnit can provide an efficient means for selection of a set of related content elements by a feature.

CompositeLocalizationUnit serves the same purposes as CompositeUnit within the LocalizatonContent hierarchy.

SDD packages can aggregate other SDD packages. Metadata about the aggregation is defined in ContainedPackage, ContainedLocalizationPackage and Requisite elements. ContainedPackage elements are a content element that can be defined anywhere in the base and selectable content hierarchies. ContainedLocalizationPackages are content elements that can be defined in the localization content hierarchy. Requisites are packages that can be deployed, if necessary, to satisfy requirements in the aggregating SDD. They are not content of the SDD package. The type of all three of these elements is ReferencedPackageType. The term “referenced package” is used in this specification when referring to these elements as a group. The term “referenced SDD” is used when referring to any aggregated SDD.

Each referenced package element can further constrain the deployment of the referenced SDD by defining additional requirements; by mapping resources defined in the aggregating SDD to those defined in the referenced SDD; and by determining feature selections for deployment of the referenced SDD.

2.4 Resulting and Changed Resources

Deployment of an SDD package creates or modifies software resources. These resources are included in the topology definition and described in more detail in ResultingResource and ResultingChange elements.

The SDD author can choose to model resulting and modified resources at a very granular level, at a very coarse level; at any level in between, or not at all. An example of modeling resulting resources at a granular level would be modeling every file created by the deployment as a resulting resource. An example of modeling resulting resources at a very coarse level would be modeling the software product created by deployment as a single resulting resource. The choice depends on the needs of the solution deployment. If a resource is not modeled in the SDD, no requirements can be expressed on it, no conditions can be based on it and no variables can be set from values of its properties. It cannot play any of the roles described for resources in the ResourceType section of this document [4.2.2].

2.5 Base, Selectable and Localization Content Hierarchies

Each CompositeInstallable element can define three types of content hierarchies. Base content is the default content for the deployment lifecycle operation associated with the CompositeInstallable. This is content that will be deployed whenever the associated operation is performed on the SDD package. Base content may be conditioned on characteristics of the deployment environment but it is not selectable by the deployer.

The SDD author can define selectable subsets of optional content in the selectable content hierarchy. The selection criteria include features and groups of features that select content from the selectable content hierarchy. Selectability, as used in the SDD, is a characteristic of the deployment lifecycle operation and the package. For example, the decision to provide selectability for one operation in one package has no semantic relationship to the selectability provided in another package related to the same software. It also has no semantic relationship to the selectability provided for a different operation within the same package.

Localization content is the third type of content hierarchy. Localization refers to enabling a particular piece of software for support for one or more languages. Anything that needs to be deployed to provide support for a particular language in that software is considered localization content. Translated materials are a primary, but not the only, example of localization content.

Localization content is similar in many ways to other content, but there are important differences in how localization content is selected for deployment that lead to the need for a separate content hierarchy and separate types. There are two criteria for determining that localization content is in scope for a particular deployment.

§         The first criterion has to do with the language or languages supported by the localization content. At least one of the languages must be in scope for the content to be selected.

§         The second criterion has to do with the availability of the resources to be localized–the localization base. The localization base may be a resource deployed by base or selectable content, or it may be a resource previously deployed and found in the deployment environment.

2.6 Constraints

The SDD author needs to communicate constraints on resources for a variety of purposes.

·         Some constraints must be met for the requirements of a content element to be met.

·         Other constraints must be met for a resource to serve as the required base for an update.

·         Still others must be met to satisfy a condition that determines the applicability of a content element or completion action.

The Constraint types are:

2.7 Requirements

Requirements are defined by content elements. A requirement consists of resource constraints that the SDD author states MUST be met prior to successful deployment or use of the software described by the SDD package. Each requirement definition lists one or more deployment lifecycle operations to which the requirement applies. When the requirement is specified in an atomic content element, the operation associates the requirement with artifacts within the atomic content element

When a requirement can be satisfied in more than one way, alternatives can be defined within a requirement. A requirement is considered met when any one of the alternatives is satisfied.

2.8 Conditions

Conditions are expressed on characteristics of resources in the deployment environment. Conditions are used to indicate when particular elements of the SDD are applicable, or when they should be ignored. Conditions are not requirements. Failure to satisfy a condition does not indicate a failure; it simply means the conditioned element should be ignored. Conditions are used to:

§         determine if a content element is applicable

§         choose from among values for a variable

§         determine when a feature is applicable

§         determine when a particular result is applicable

§         determine if a particular completion action is necessary.

Because conditions are always based on the characteristics of resources, they are expressed using resource constraints.

2.9 Variables

Variables provide a way to associate user inputs, resource property values, fixed strings and values derived from these with input arguments for artifacts and with constraints on resources.

3    Package Descriptor

A package descriptor is an XML document that provides information about the identity and the contents of a software package. A software package is a bundle of one or several content elements that deploy or remove computer software; add features to existing software; or apply maintenance to existing software. Each package descriptor is associated with a deployment descriptor.

3.1 PackageDescriptor

Figure 2: PackageDescriptor structure.

The root element of a package descriptor XML document is PackageDescriptor. PackageDescriptor includes elements that describe the package identity and the contents that make up the package. The PackageDescriptor includes the associated deployment descriptor XML document by defining a Content element with a purpose attribute set to deploymentDescriptor.

3.1.1 PackageDescriptor Property Summary

Name

Data Type

*

Description

PackageIdentity

PackageIdentityType

1

Human-understandable identity information for the software package.

Contents

ContentsType

1

A list of package contents.

ds:Signature

ds:SignatureType

0..1

A signature for the package descriptor.

schemaVersion

xsd:string

1

The descriptor complies with this version of the Solution Deployment Descriptor Specification.

**fixed value=“1.0”

descriptorID

UUIDType

1

Identifier of a particular package’s descriptor.

lastModified

xsd:dateTime

1

The time the descriptor was last modified.

descriptorLanguageBundle

xsd:token

0..1

The root name of language bundle files containing translations for display text elements in the PackageDescriptor.

 

xsd:anyAttribute

0..*

 

3.1.2 PackageDescriptor Property Usage Notes

§         PackageIdentity: The PackageIdentity element provides identity information about the software package that can be used by the consumer of the package for deployment planning or aggregation of the package into a larger solution.

See the PackageIdentityType section for structure and additional usage details [3.3].

§         Contents: The Contents element defines a list of one or more Content elements describing all the files that are part of the package. All files in the package MUST be defined in Contents.

See the ContentsType section for structure and additional usage details [3.11].

§         ds:Signature: The package descriptor and each file in the package MAY be digitally signed. It is RECOMMENDED that they be digitally signed by using an XML-Signature [XMLDSIG-CORE].

The signature element is an enveloped signature over the SDD package. Note that each Content element included in the package is digitally signed indirectly via this digest. Files can also be individually signed in the Content element.

§         schemaVersion, descriptorID, lastModified, descriptorLanguageBundle: See the DescriptorInfoGroup section for structure and additional usage details [3.2].

3.2 DescriptorInfoGroup

Figure 3: DescriptorInfoGroup structure.

The attributes defined by DescriptorInfoGroup are included in both PackageDescriptor and DeploymentDescriptor.

3.2.1 DescriptorInfoGroup Property Usage Notes

§         schemaVersion: The schemaVersion attribute identifies the Solution Deployment Descriptor specification version to which the descriptor conforms. It MUST have a fixed value of “1.0”.

§         descriptorID: The descriptorID attribute, combined with the lastModified attribute value, provides a unique identifier for the descriptor. The descriptorID value MUST be unique within the scope of use of the deployment descriptor or package descriptor. The descriptorID attribute is an instance of UUIDType, which is based on xsd:hexBinary with length 16. This enables use of a 128-bit UUID [IETF-UUID]. The descriptorID value supports descriptor updates by allowing updated descriptors to be correctly associated with an earlier version of the same descriptor.

For example, if a descriptor contains errors, it may be replaced by an error-free version using the same descriptorID value but a different lastModified value.

§         lastModified: The lastModified value can be used to differentiate between different versions of the same descriptor, for example, the descriptor for one particular package. Comparison of lastModified values can be used to determine which descriptor is newer.

The lastModified attribute MUST be defined as a value that conforms to the xsd:dateTime type as defined in [XSD] and MUST match the following lexical representation: [-]CCYY-MM-DDThh:mm:ss[Z|(+|-)hh:mm].  This is a combination of a complete date and time of day, where the time zone can be specified as Z (UTC) or (+|-)hh:mm. 

For example, the following are valid values for the lastModified attribute:

§         2001-10-26T21:32:52

§         2001-10-26T21:32:52+02:00

§         2001-10-26T19:32:52Z

§         2001-10-26T19:32:52+00:00

§         -2001-10-26T21:32:52

§         2001-10-26T21:32:52.12679

However, the following values would be invalid:

§         2001-10-26

§         2001-10-26T21:32

§         01-10-26T21:32

§         2001-10-26T25:32:52+02:00

The first three invalid examples do not specify all the required parts, and the fourth includes an out of range hours part, “25”.

§         descriptorLanguageBundle: Language translations for elements of DisplayTextType in the descriptor MAY be included in the solution package. Note that these are not translations for the software deployed by the package, but rather translations only for the text in the descriptors themselves. The root name of the files containing these translations can be specified in the descriptorLanguageBundle attribute, which is an instance of xsd:token. Language bundles are associated with specific locales at run time using Java-style resource bundle resolution; that is, the bundle file names SHOULD take the form languageBundle_locale, where locale consists of optional language, location (country) and variant codes, separated by an underscore character. Language codes consist of two lowercase letters [ISO639.2] and location codes consist of two uppercase letters [ISO3166].

For example, “SampleStrings_en_US” refers to the United States English version of the SampleStrings bundle and “SampleStrings_ja” identifies the Japanese version of the same bundle.

See the DisplayTextType section for structure and additional usage details [4.14.3].

3.3 PackageIdentityType

Figure 4: PackageIdentityType structure.

The software package described by the SDD can be identified for humans and package management software using the properties in PackageIdentity. The PackageIdentity is not to be confused with the identity of the deployed software, which is described in the resulting resource elements of the deployment descriptor; see the ResultingResourceType section [4.8.1].

3.3.1 PackageIdentityType Property Summary

Name

Data Type

*

Description

 

[extends] IdentityType

 

See the IdentityType section for additional properties [3.4].

packageType

PackageTypeType

0..1

The type of the package, for example, “baseInstall” or “maintenance”.

**default value=“baseInstall”.

contentType

xsd:QName

0..1

The type of content provided by this package, for example, BIOS.

label

xsd:NCName

0..1

A programmatic label for this package.

 

xsd:anyAttribute

0..*

 

3.3.2 PackageIdentityType Property Usage Notes

See the IdentityType section for details of the inherited attributes and elements [3.4].

§         packageType: The package type is provided to aid consumer understanding of the type of content contained in the package. A package can contain more than one type of content. In this case, a single packageType value should be selected that represents the primary content type as determined by the SDD author. The SDD defines a set of enumeration values in PackageTypeType which are extendable by the SDD author.

The enumerated types defined by the SDD are as follows:

·         baseInstall: The value baseInstall indicates that the package provides a complete installation of the solution. This package type is associated with deployment descriptors that contain installable units with installation artifacts that install the primary solution resources.

When packageType is not specified, this is the default value.

·         baseUninstall: The value baseUninstall indicates that the package provides a complete uninstallation of the solution. This package type is associated with deployment descriptors that contain installable units with uninstall artifacts that remove the primary solution resources.

·         configuration: The value configuration indicates that the package configures the solution. This package type is associated with deployment descriptors that contain configuration units with configuration artifacts that configure the solution.

·         maintenance: The value maintenance indicates that the package fixes one or more problems in the solution. This package type is associated with deployment descriptors that contain installable units with update artifacts.

·         modification: The value modification indicates that the package modifies the function of the solution in some way such as by adding new function. This package type is associated with deployment descriptors that contain installable units with update artifacts.

·         replacement: The value replacement indicates that the package installs a solution that replaces a previous version of the solution. Replacement MAY be associated with migration of data into the new solution and/or with deletion of the replaced solution. When associated with migration of data, installation or configuration artifacts within the solution package would perform the migration. When associated with deletion of the replaced solution, uninstall artifacts within the solution package would perform the deletion. This package type is associated with deployment descriptors that contain installable units with installation artifacts that deploy a set of resources that replace the set of resources associated with a previous version of the solution.

·         localization: The value localization indicates that the package contains materials that localize deployed software for one or more languages.

§         contentType: The value of contentType is determined by the SDD manufacturer to communicate a characteristic of the package that MAY be used in the manufacturer’s package management system or other manufacturer-specific tools that use the SDD. The SDD author chooses the values; they are not defined in this specification.

§         label: The label MAY be used as an index in a package management system. The SDD author chooses the values; they are not defined in this specification.

3.4 IdentityType

Figure 5: IdentityType structure.

This complex type provides identity information for the package as a whole, as well as for content elements, which are portions of the package. Content elements are the InstallableUnit, LocalizationUnit, ConfigurationUnit, CompositeUnit and CompositeInstallable elements defined in the deployment descriptor.

3.4.1 IdentityType Property Summary

Name

Data Type

*

Description

Description

DisplayTextType

0..1

A verbose description of the package or content element.

ShortDescription

DisplayTextType

0..1

A limited description of the package or content element.

Name

DisplayTextType

0..1

A human-readable, translatable, name for the package or content element.

Version

VersionType

0..1

The package or content element version.

MaintenanceInformation

MaintenanceInformationType

0..1

Information about package or content element content used when the package contains maintenance.

BuildInformation

BuildInformationType

0..1

A manufacturer identifier for the build of this package or content element. This property can be extended with additional manufacturer-specific information about the build.

Manufacturer

ManufacturerType

0..1

Information about the manufacturer of the package or content element.

 

xsd:any

0..*

 

softwareID

xsd:string

0..1

A manufacturer’s identification number for the software created or updated by the package or content element.

 

xsd:anyAttribute

0..*

 

3.4.2 IdentityType Property Usage Notes

§         Description, ShortDescription: These elements MAY be used to provide human-understandable information. If used, they MUST provide a description of the package.

The Description element MUST be defined if the ShortDescription element is defined.

See the DisplayTextType section for structure and additional usage details [4.14.3].

§         Name: When the manufacturer of the SDD has a package management system, Name in PackageIdentity should correspond to the name of the package as known in the package management system. Name in a content element’s Identity should correspond to the name of the unit of packaging, if it is known in the package management system.

When the PackageIdentity element is defined, Name MUST be defined.

Software packages that create software often have the same name as the deployed software. Software packages that update software often have a name that reflects the fact that the package is a maintenance package, differentiating it from the base deployed software. The author of the software package that is described by PackageIdentity determines whether the Name is the same as or different from the Name of the deployed software.

See the DisplayTextType section for structure and additional usage details [4.14.3].

§         Version: This is a packaging version. In PackageIdentity, it is the version of the package as a whole. In content element identities, this is the version of the unit of packaging represented by the content element. In either case, the SDD author MAY choose to make this version correspond to the version of a resulting or changed resource, but it should not be confused with resource versions.

In the case of a base install, version MAY be the same as the top level resulting resource. In the case of a configuration package, version SHOULD NOT be the same as the top level resulting resource.

See the VersionType section for structure and additional usage details [3.10].

§         MaintenanceInformation: This is used when the package or content element describes the deployment of maintenance.

See the MaintenanceInformationType section for structure and additional usage details [3.5].

§         BuildInformation: In PackageIdentity, this describes the build of the package as a whole. In content element Identity, this describes the build of the artifact(s) and the content element describing the artifact.

See the BuildInformationType section for structure and additional usage details [3.7].

§         Manufacturer: See the ManufacturerType section for structure and additional usage details [3.8].

§         softwareID: The software identified by softwareID is the software whose deployment is described by the SDD. When the manufacturer maintains software identifiers within a sales and distribution system, the softwareID SHOULD correspond to an identifier for the software within that system. If a format for software identifiers is not pre-existing within the manufacturer’s systems, a UUID SHOULD be used for softwareID. When a UUID is used, it MUST be unique within the domain in which the described software is used.

3.5 MaintenanceInformationType

Figure 6: MaintenanceInformationType structure.

If the package provides maintenance for deployed software, MaintenanceInformation declares information about the fix or fixes provided. If the package content is a single fix, MaintenanceInformation describes the information about that one fix. If the content is a collection of fixesfor example, a fix packMaintenanceInformation describes each of the fixes provided by the fix pack.

3.5.1 MaintenanceInformationType Property Summary

Name

Data Type

*

Description

Severity

DisplayTextType

0..1

Severity of the maintenance content.

Category

DisplayTextType

0..*

Category of the maintenance content.

Supersedes

MaintenanceInformationType

0..*

A previously released fix that is superseded by application of this maintenance.

Fix

FixIdentityType

0..*

An included fix.

 

xsd:any

0..*

 

3.5.2 MaintenanceInformationType Property Usage Notes

§         Severity: This value SHOULD correspond to a severity value used within the SDD provider’s support system. It serves as a hint to the deployer about the urgency of applying the described maintenance.

See the DisplayTextType section for structure and additional usage details [4.14.3].

§         Category: These values SHOULD correspond to maintenance categories within the SDD provider’s support system.

See the DisplayTextType section for structure and additional usage details [4.14.3].

§         Supersedes: Superseded fixes are ones that fix a problem also fixed by the superseding maintenance package or content element and therefore need not be applied.

This element does not indicate whether or not the superseded fix needs to be removed. To indicate that the previous fix must be removed before the superseding maintenance can be applied successfully; the SDD author can create a requirement stating that the fix must not be present.

Superseded fixes MAY include all the information defined in MaintenanceInformationType. At a minimum, a superseded fix MUST include at least one Fix element with the name of the superseded fix defined.

§         Fix: Fix elements provide information about individual fixes provided by the maintenance content.

See the FixIdentityType section for structure and additional usage details [3.6].

3.6 FixIdentityType

Figure 7: FixIdentityType structure.

Elements of FixIdentityType describe fixes that will be applied when the package is deployed or the content element is applied.

3.6.1 FixIdentityType Property Summary

Name

Type

*

Description

Name

xsd:NMTOKEN

1

A name for the fix which is, at a minimum, unique within the scope of the resource fixed.

Description

DisplayTextType

1

A complete description of the fix.

ShortDescription

DisplayTextType

0..1

An abbreviated description of the fix.

Symptom

DisplayTextType

0..*

A symptom of the problem fixed.

 

xsd:any

0..*

 

3.6.2 FixIdentityType Property Usage Notes

§         Name: The Name element MUST provide a value that uniquely identifies a fix within a scope defined by the manufacturer. This is a name provided by the manufacturer that corresponds to the fix name as understood in the deployment environment.

§         Description, ShortDescription: These elements MAY be used to provide human-understandable information. If used, they MUST provide a description of the fix.

The Description element MUST be defined if the ShortDescription element is defined.

See the DisplayTextType section for structure and additional usage details [4.14.3].

§         Symptom: Symptom strings can be used to correlate a fix with one or more experienced problems.

See the DisplayTextType section for structure and additional usage details [4.14.3].

3.7 BuildInformationType

Figure 8: BuildInformationType structure.

BuildInformationType provides the type definition for the BuildInformation element in package and content element identity. BuildInformation provides information about the creation of the package and its parts.

3.7.1 BuildInformationType Property Summary

Name

Type

*

Description

buildID

xsd:token

1

Identifies the build of the package or package element.

 

xsd:anyAttribute

0..*

 

3.7.2 BuildInformationType Property Usage Notes

§         buildID: The buildID attribute is an identifier provided by the manufacturer and meaningful to developers that can be used to identify a build of the defining element. This information MUST correspond with information known in the manufacturer’s build environment. It is traditionally used during problem determination to allow maintainers of the software to determine the specifics of package creation. Inclusion of buildID in the SDD allows the end user to provide this information to package maintainers, enabling them to correlate the deployed software with a particular known build of the software.

3.8 ManufacturerType

Figure 9: ManufacturerType structure.

The SDD author can include information about the package manufacturer that includes name, location and contact information such as the address of the manufacturer’s Web site or telephone number.

3.8.1 ManufacturerType Property Summary

Name

Type

*

Description

Name

DisplayTextType

1

A translatable name for the manufacturer.

Location

LocationType

0..1

The address and country of the manufacturer.

ContactInformation

DisplayTextType

0..1

Contact information for the manufacturer.

 

xsd:any

0..*

 

3.8.2 ManufacturerType Property Usage Notes

§         Name: The value provided in the Name element MUST be an identifiable name of the manufacturer of the SDD.

See the DisplayTextType section for structure and additional usage details [4.14.3].

§         Location: See the LocationType section for structure and additional usage details [3.9].

§         ContactInformation: This element MAY provide additional contact information for the named manufacturer, such as a support Web site address or a technical support telephone number.

See the DisplayTextType section for structure and additional usage details [4.14.3].

3.9 LocationType

Figure 10: LocationType structure.

LocationType supports inclusion of the manufacturer’s address and country in package and content element identity.

3.9.1 LocationType Property Summary

Name

Type

*

Description

Address

DisplayTextType

0..1

The manufacturer’s address.

Country

DisplayTextType

0..1

The manufacturer’s country.

3.9.2 LocationType Property Usage Notes

§         Address: This is the mailing address or the physical address.

See the DisplayTextType section for structure and additional usage details [4.14.3].

§         Country: Recording the manufacturer’s country in the SDD provides information that may be of interest in relation to import and export of software.

See the DisplayTextType section for structure and additional usage details [4.14.3].

3.10 VersionType

VersionType provides the type definition for version elements in the package descriptor and deployment descriptor. It is a simple type that is based on xsd:string with no further restrictions. This means that versions in the SDD are represented simply as strings. Because resource versions exist in the deployment environment, their formats and semantics vary widely. For this reason, the format and semantics of versions are not defined by this specification.

3.11 ContentsType

Figure 11: Contents structure.

ContentsType is used in PackageDescriptor to provide a list of one or more Content elements.

3.11.1 ContentsType Property Summary

Name

Type

*

Description

Content

ContentType

1..*

Describes the physical contents of the software package.

3.11.2 ContentsType Property Usage Notes

§         Content: A PackageDescriptor MUST contain a Contents element that is a list of one or more Content elements.

See the ContentType section for structure and additional usage details [3.12].

3.12 ContentType

Figure 12: ContentType structure.

A software package includes one or more content files. ContentType defines the properties of a content file included in the package descriptor. Content defined in the package descriptor as part of the software package does not need to be physically co-located. Each element MUST be in a location that can be identified by a URI. The pathname attribute of each content file defines a URI for accessing the file. Characteristics of the content filessuch as their length, purpose and character encodingMAY be declared in the package descriptor.

3.12.1 ContentType Property Summary

Name

Data Type

*

Description

ds:DigestMethod

ds:DigestMethodType

0..1

Specifies the digest method applied to the file.

ds:DigestValue

ds:DigestValueType

0..1

Specifies the Base64-encoded value of the digest of the file.

id

xsd:ID

1

An identifier used in deployment descriptors to refer to the file definition in the associated package descriptor.

pathname

xsd:anyURI

1

The absolute or relative path of the content file including the file name.

purpose

ContentPurposeType

0..1

Associates a purpose classification with a file.

**default value=“content”

charEncoding

xsd:string

0..1

Specifies the character encoding of the contents of the file.

length

xsd:nonNegativeInteger

0..1

Specifies the size of the file in bytes.

 

xsd:anyAttribute

0..*

 

3.12.2 ContentType Property Usage Notes

§         ds:DigestMethod, ds:DigestValue: These values MAY be used to assist with file verification.

See the DigestInfoGroup section for structure and additional usage details [3.13].

§         id: This is the identifier for the content that is used as a reference in artifact elements in the deployment descriptor.

The id attribute may be useful to software that processes the SDD, for example, for use in creating log and trace messages.

§         pathname: pathname is used to access content in the package. The path of the file MUST be a URI that specifies an absolute path or a path relative to the location of the package descriptor. It MUST include the file name.

§         purpose: The purpose attribute enables the PackageDescriptor author to associate a classification with a file. The classification identifies the file as having a specific purpose. ContentPurposeType defines a union of SDDContentPurposeType with xsd:NCName. The purpose value MAY be chosen from one of the following values enumerated in SDDContentPurposeType or be a valid NCName value provided by the SDD author. If purpose is not specified, the default value is content.

Enumerated values for purpose are:

·         readMe: A file with information about the package. An implementation may choose to display this to a user as part of the deployment process.

·         endUserLicenseAgreement: A file containing an end user license agreement. An implementation may choose to display this to a user as part of the deployment process.

·         responseFile: A file that contains input values for an operation.

·         deploymentDescriptor: An XML file containing the DeploymentDescriptor definition associated with the PackageDescriptor. A valid PackageDescriptor MUST have exactly one Content element with a purpose value of deploymentDescriptor.

·         packageDescriptor: Supports aggregation of packages. This is used to reference a packageDescriptor of an aggregated package.

·         descriptorLanguageBundle: A file containing translations of text defined directly in the package descriptor or its associated deployment descriptor.

·         content: A file used during deployment of solution content. This is the default value for purpose.

§         charEncoding: This attribute need only be used for files that a run-time is required to render. Common charEncoding values include “ASCII”, “UTF-8”, “UTF-16” and “Shift_JIS”. For an extensive list of character encodings, see [IANA-CHARSET].

§         length: The file length MAY be used for simple file verification.

3.13 DigestInfoGroup

Figure 13: DigestInfoGroup structure.

When digest information is used to sign a content file, both the digest method and the digest value MUST be provided.

3.13.1 DigestInfoGroup Property Usage Notes

§         ds:DigestMethod, ds:DigestValue: ds:digestMethod and ds:digestValue MAY be used to digitally sign individual files. If files are signed, the digest value MUST be calculated over the whole of each file.

See [XMLDSIG-CORE] for details on the usage of ds:DigestMethod and ds:DigestValue.

4    Deployment Descriptor

A solution package contains a deployment descriptor in addition to a package descriptor. The deployment descriptor describes the topology, selectability, inputs, requirements and conditions of the deployment. The deployment descriptor is associated with a package descriptor and refers to content files in that package descriptor.

4.1 DeploymentDescriptor

Figure 14: DeploymentDescriptor structure.

DeploymentDescriptor is the top level element of a deployment descriptor. The DeploymentDescriptor defines the information required to support deployment of the package contents. This includes the Topology, which declares all of the resources that may participate in deployment. It also includes one atomic content element or one or more CompositeInstallable content elements. Atomic content elements are InstallableUnit, ConfigurationUnit, or LocalizationUnit. Atomic content elements define artifacts that can be processed to deploy software resources. They are atomic because they cannot aggregate other content elements. A CompositeInstallable element is the root of a content element hierarchy that defines content that performs the one deployment operation supported by the CompositeInstallable. A CompositeInstallable can define base, selectable and localization content as well as the aggregation of other content elements.

4.1.1 DeploymentDescriptor Property Summary

Name

Data Type

*

Description

Topology

TopologyType

1

Defines resources that are required, created or modified by deployment.

InstallableUnit

InstallableUnitType

0..1

Defines content that installs, updates and/or uninstalls resources. When an InstallableUnit is defined, no ConfigurationUnit, LocalizationUnit or CompositeInstallable elements can be defined.

ConfigurationUnit

ConfigurationUnitType

0..1

Defines content that configures resources. When a ConfigurationUnit is defined, no InstallableUnit, LocalizationUnit or CompositeInstallable elements can be defined.

LocalizationUnit

LocalizationUnitType

0..1

Defines content that installs, updates and/or uninstalls translated materials. When a LocalizationUnit is defined, no InstallableUnit, ConfigurationUnit or CompositeInstallable elements can be defined.

CompositeInstallable

CompositeInstallableType

0..*

Defines a hierarchy of base, selectable and/or localization content used to perform one deployment lifecycle operation. When one or more CompositeInstallable elements are defined, no InstallableUnit, ConfigurationUnit or LocalizationUnit elements can be defined.

Requisites

RequisitesType

0..1

A list of references to SDD packages that can optionally be deployed to satisfy deployment requirements of the defining SDD.

 

xsd:any

0..*

 

schemaVersion

xsd:string

1

The descriptor complies with this version of the Solution Deployment Descriptor Specification.

**fixed value=“1.0”

descriptorID

UUIDType

1

Identifier of the deployment descriptor for a particular set of deployable content.

lastModified

xsd:dateTime

1

The time the descriptor was last modified.

descriptorLanguageBundle

xsd:token

0..1

The root name of language bundle files containing translations for display text elements in the deployment descriptor.

 

xsd:anyAttribute

0..*

 

4.1.2 DeploymentDescriptor Property Usage Notes

§         Topology: Topology provides a logical view of all resources that may participate in any particular deployment. A resource can participate by being required, created or modified by the deployment. A required resource MAY also play the role of target resource, meaning that it can process artifacts to perform some portion of the deployment. The resources that actually participate in a particular deployment are determined by the user inputs, selections and resource bindings provided during that deployment.

See the TopologyType section for structure and additional usage details [4.2.1].

§         InstallableUnit, ConfigurationUnit, LocalizationUnit, CompositeInstallable: A simple software deployment that uses a single artifact for each supported deployment operation MAY be described using an SDD that defines a single atomic content element–InstallableUnit, ConfigurationUnit or LocalizationUnit.

A software deployment that requires multiple artifacts, aggregates other deployment packages or has selectable content MAY be described using an SDD that defines one or more CompositeInstallable elements. Each CompositeInstallable MUST describe one deployment lifecycle operation for the package.

See the respective sections (InstallableUnitType [4.3.1], ConfigurationUnitType [4.3.2], LocalizationUnitType [4.13.2] and CompositeInstallableType [4.9.1]) for structure and additional usage details.

§         Requisites: When the package author chooses to provide deployment packages for required software, those packages are described by Requisite elements in Requisites.

Including requisite packages in the SDD package MAY provide a convenient way for the deployer to satisfy one or more SDD requirements.

See the RequisitesType section for structure and additional usage details [4.10.5].

§         schemaVersion, descriptorID, lastModified, descriptorLanguageBundle: These attributes can be useful to tooling that manages, creates or modifies deployment descriptors and to tooling and deployment software that displays information from the deployment descriptor to humans.

See the DescriptorInfoGroup section for structure and additional usage details [3.2].

4.2 Topology

The SDD’s topology describes all the resources that may be required, created or modified when any of the deployment operations supported by the SDD are performed.

Primary identifying characteristics of the resources can be defined in topology. Constraints beyond these primary characteristics are not defined in topology; they are defined in content elements that reference the resource definitions in topology.

The topology includes identification of hosts–hostedBy relationships between resources. When both resources in that relationship participate in a particular deployment, the relationship is considered a requirement for that deployment.

It is possible that only a subset of the resources described in topology will play a role in a particular deployment. This is determined by the selection of content elements for the particular deployment. The resources that are required, created or modified by the content elements in scope for the deployment are the ones that will participate in the deployment and so are associated with resources in the deployment environment.

At deployment time, definitions of the resources that participate in that particular deployment are associated with actual resource instances in the deployment environment. The mechanisms for associating resource definitions with resource instances are not described by the SDD. The SDD metadata describes the characteristics of the participating resources. Whether associations of resource instances with matching characteristics are made by user choice or entirely by software does not affect the success of the deployment. Resource characteristics used when making this association include those defined in topology plus all those defined in constraints on the resource in the content elements that are in scope for the particular deployment.

Some topologies are variable. That is, a particular set of logical resources of the same type in the topology might be associated with different physical resource instances or the same physical resource during deployment. In this case, a separate logical resource definition is created in topology for each possible physical resource instance. Uniqueness constraints can then be used to describe the conditions under which the separate resources can be associated with a single resource.

All resource definitions in the SDD are in topology. All other descriptions of resources in the SDD are references to the resource definitions in the topology.

4.2.1 TopologyType

Figure 15: TopologyType structure.

The Topology element defines one or more hierarchies of resource specifications that describe the resources that MAY play a role in the deployment of the contents of the solution package. These resource specifications do not identify specific resource instances in a specific deployment environment. Instead, they are logical specifications of resources that can be associated with specific resource instances in the deployment environment for a particular deployment based on the described resource identity characteristics. These resources have a role in a particular solution deployment only when they are required, created or modified by a content element, or referred to by a variable, in that particular solution deployment.

4.2.1.1 TopologyType Property Summary

Name

Type

*

Description

Resource

ResourceType

1..*

The root of a tree of resources that play a role in the solution.

 

xsd:any

0..*

 

4.2.1.2 TopologyType Property Usage Notes

§         Resource: The SDD author’s decision to model a resource in the deployment environment as a resource in the SDD depends on the need to know about that resource when planning for deployment, aggregating, deploying and managing the resource lifecycle using the SDD. All resources required by the solution SHOULD be included. For all Requirements declared in the SDD, resources MUST be specified. Resources referred to by ResultingResource or ResultingChange elements MUST also be included. The more complete the SDD is, the more useful it will be in guiding successful deployment.

See the ResourceType section for structure and additional usage details [4.2.2].

4.2.2 ResourceType

Figure 16: ResourceType structure.

Elements of ResourceTypeboth the top level Resource elements and the HostedResource elements within the resource hierarchymake up the topology of an SDD. Each Resource element declares, at a minimum, the type of the resource. Values for resource type are not defined by this specification. A core assumption of this specification is that an understanding of specific resource types and resource characteristics are shared by the deployment descriptor author and the deployment software. Therefore, if the deployment descriptor author declares a new resource type, then deployment software operating on the SDD needs to understand how to handle that resource type.

In addition to defining type, the resource elements MAY specify a name and other identity properties that can be used to identify instances of the resource in the deployment environment. The resource identity elements, Name and Property, are optional and MAY be specified in content elements rather than in topology. Identity properties used in the resource specification in topology MUST be those that do not change during deployment, even when the resource is updated. Because resource versions can often change during an update, there is no version element in resource specifications in Topology. Values can be defined for resource name and resource properties that help to identify the resource. These represent the basic identity of the resource and are true for all uses of the resource in the solution.

ResourceType provides the type definition for the Resource and HostedResource elements defined in Topology. All resources MAY nest resource definitions for resources that they host. To host a resource means to provide the execution environment for that resource.

For example, an operating system provides the execution environment for software, and a database engine provides the execution environment for a database table. The operating system hosts the software and the database engine hosts the database table.

Each resource in these hierarchies may play a role in solution deployment.

Content elements determine a resource’s participation and role(s) in a particular solution deployment. Content elements can refer to resources in Topology in several ways. A resource can be identified via xsd:IDREF:

For example, an operating system may be the target of an artifact that is a zip file. When the files are unzipped, the file system resource is the host of those files.

See the targetResourceRef attribute in the InstallableUnitType [4.3.1], ConfigurationUnitType [4.3.2] and LocalizationUnitType [4.13.2] sections.

See the RequiredBaseType section [4.7.8].

See the ResultingResourceType section [4.8.1].

See the ResultingChangeType section [4.8.2].

See the LocalizationBase element in the LocalizationUnitType section [4.13.2].

See the RequirementsType section [4.7.1].

See the ResourcePropertyType section [4.6.12].

One resource MAY be referred to by any number of content elements and can be identified to play any or all of the roles just listed. When a content element participates in a particular solution deployment, the resources it references participate in that solution deployment and are associated with resource instances in the deployment environment.

4.2.2.1 ResourceType Property Summary

Name

Type

*

Description

Description

DisplayTextType

0..1

A description of the resource and its role in the solution described by the SDD.

ShortDescription

DisplayTextType

0..1

A short description of the resource and its role.

Name

VariableExpressionType

0..1

The name of the resource as known in the deployment environment.

Property

PropertyType

0..*

An identity property of the resource.

HostedResource

ResourceType

0..*

A resource that participates in the solution and that is hosted by the defining resource.

 

xsd:any

0..*

 

id

xsd:ID

1

An identifier of the resource scoped to the descriptor.

type

ResourceTypeNameType

1

A well-known resource type.

 

xsd:anyAttribute

0..*

 

4.2.2.2 ResourceType Property Usage Notes

§         Description, ShortDescription: If used, these elements MUST provide a human-readable description of the resource.

The Description element MUST be defined if the ShortDescription element is defined.

See the DescriptionGroup section for structure and additional usage details [4.14.1].

§         Name: The resource name is an identifying characteristic of the resource that correlates with a name for the resource in the deployment environment.

The type of the Name element, VariableExpressionType, allows the resource name to be expressed as a simple string or in terms of a user input parameter or other variable.

An example of a good use of a variable expression in Resource.Name is to make sure that the installation directory is hosted on a file system that has sufficient space available for deployment. In this example, the file system resource element would define a HostedResource element for the directory. The Name of the directory would be expressed as a variable expression that refers to a user input parameter for installation location. Content elements that use the installation directory would express a requirement on the directory and on the file system with the additional constraint that the file system have a certain amount of available space (to satisfy the consumption constraints). The fact that both resources are required and that they are defined with a hostshostedBy relationship in Topology, means that the directory that is used must be the installation directory and it must be hosted by a file system that meets the consumption constraint for available space.

Only the Variable elements defined in a top level content element can be used to define a resource Name, because these are the only variables visible within Topology.

If the name of a resource is changed during deployment, for example, during an update, then the resource name SHOULD NOT be included in the resource specification. Instead, the pre-update resource name SHOULD be specified in the RequiredBase element of the installable unit that provides the update, and the post-update name SHOULD be specified in the ResultingResource element of the same installable unit.

See the VariableExpressionType section for structure and additional usage details [4.6.1].

§         Property: Property elements SHOULD be used when Name alone is not sufficient to identify the resource. The property used represents an identifying characteristic of a resource.

See the PropertyType section for structure and additional usage details [4.2.3].

§         HostedResource: A Resource MAY define HostedResource elements. Each HostedResource element is an instance of ResourceType. When both the host and the hosted resource participate in a particular solution deployment, the associated resource instances selected for use during that deployment must have a hosts relationship.

For example, a Web application declared to be hosted on a Web server must be hosted on the instance of the Web server that is selected for use during the deployment.

If only the host resource is identified by the DeploymentDescriptor’s content elements as participating in the solution, then there is no assumption that the hosted resource exists.

§         id: The id attribute uniquely identifies the resource element within the DeploymentDescriptor. This id value is used by other elements in the DeploymentDescriptor to refer to this resource. This value is created by the descriptor author.

The id attribute may be useful to software that processes the SDD, for example, for use in creating log and trace messages.

§         type: The type attribute defines the class of resource. The value of type correlates with the resource type known for the resource in the deployment environment. ResourceTypeNameType restricts type to valid xsd:QNames. The values for type are not defined by this specification. Creators of DeploymentDescriptors rely on knowledge of resource types that are understood by supporting infrastructure in the target environment. To honor the descriptor author’s intent, the deploying infrastructure must be able to discover the existence of resources of the types defined in the SDD; the values of the resource’s properties; and the existence and type of resource relationships. The deploying infrastructure also needs to understand how to use the artifact types associated with the resource type to create, modify and delete the resource.

4.2.3 PropertyType

Figure 17: PropertyType structure.

PropertyType provides the type definition for elements used to declare an identity property of a resource, namely, the Property elements of Resource and HostedResource in Topology. It also provides the type definition for Property elements in Relationship and RelationshipConstraint.

4.2.3.1 PropertyType Property Summary

Name

Type

*

Description

PropertyName

xsd:QName

1

The property name.

Value

VariableExpressionType

1

The property value.

 

xsd:anyAttribute

0..*

 

4.2.3.2 PropertyType Property Usage Notes

§         PropertyName: The PropertyName MAY be used to provide additional identification for the resource in the deployment environment.

The PropertyName MAY be used to provide constraints on the configuration of a resource.

§         Value: Evaluation of the Value expression provides the value of the property.

See the VariableExpressionType section for structure and additional usage details [4.6.1].

4.2.4 ResultingPropertyType

Figure 18: ResultingPropertyType structure.

ResultingPropertyType provides the type definition for elements used to declare an identity property of a resulting resource or to declare a configuration change to a resource property which results from deployment of an artifact.

4.2.4.1 ResultingPropertyType Property Summary

Name

Type

*

Description

PropertyName

xsd:string

1

The resulting property name.

Value

VariableExpressionType

1

The resulting property value.

 

xsd:anyAttribute

0..*

Additional attributes of the resulting property.

4.2.4.2 ResultingPropertyType Property Usage Notes

§         PropertyName: The PropertyName MAY be used to provide additional identification for the resource in the deployment environment.

The PropertyName MAY be used to declare a configuration change to a resource.

§         Value: Evaluation of the Value expression provides the value of the resulting property.

See the VariableExpressionType section for structure and additional usage details [4.6.1].

4.3 Atomic Content Elements

The package descriptor defines package content that includes artifacts whose processing results in deployment of the software package. The deployment descriptor defines metadata associated with those artifacts. The metadata includes conditions, requirements, results, inputs, outputs and completion actions. Metadata throughout the deployment descriptor is associated with package content in the definition of atomic content elements. The atomic content elements are InstallableUnit, ConfigurationUnit and LocalizationUnit. These are the only content elements that define Artifacts elements.

Artifact elements identify an artifact file or set of files defined in package content whose processing will perform all or a portion of the deployment for a particular deployment lifecycle operation. The name of the artifact element indicates the operation supported by the artifact. Names of the artifact elements are created by prefixing “Artifacts” with the operation name. The artifacts defined for use in the SDD are InstallArtifact, UpdateArtifact, UndoArtifact, UninstallArtifact, RepairArtifact and ConfigArtifact.

Artifact elements define the inputs and outputs, substitution values and types associated with the artifact files. The content element’s target resource, identified by targetResourceRef, processes the artifact files with the defined inputs to perform deployment operations. Examples of artifact types include zip files, rpm files and executable install files. Artifact types are not defined by this specification. The artifact types defined in the SDD need to be understood by software that processes the SDD.

There MAY be multiple atomic content elements within a composite installable that describe the deployment of multiple resources as part of a single software deployment or there MAY be a single atomic content element (singleton) in the deployment descriptor that describes the entirety of a simple deployment. When an atomic content element is used in a CompositeInstallable, it MUST define exactly one artifact. When an atomic content element is a singleton, it MUST define at least one artifact element and MAY define one of each type of artifact element allowed for its type. The inclusion of an artifact element in a singleton atomic content element implies support for the associated operation.

For example, a singleton ConfigurationUnit that defines a ConfigArtifact associates a configure operation with the ConfigArtifact. Similarly, an SDD with a singleton InstallableUnit that defines an InstallArtifact and an UpdateArtifact associates an install operation with the InstallArtifact and an update operation with the UpdateArtifact.

When an atomic content element is defined within a CompositeInstallable hierarchy, its one artifact MUST support the single top level operation associated with the CompositeInstallable. The single artifact defined need not be an artifact for the operation defined for the CompositeInstallable.

For example, in a CompositeInstallable that defines metadata for an update operation, there may be one InstallableUnit that defines an InstallArtifact element and another InstallableUnit that defines an UpdateArtifact element. Both of these artifacts are used when performing the overall update operation defined for the CompositeInstallable.

 

4.3.1 InstallableUnitType

Figure 19: InstallableUnitType structure.

The InstallableUnit element is an atomic content element that defines artifacts that install or update software and defines requirements for applying those artifacts. It may also define artifacts that undo an update or that uninstall or repair existing software.

4.3.1.1 InstallableUnitType Property Summary

Name

Type

*

Description

Identity

IdentityType

0..1

Human-understandable identity information about the InstallableUnit.

Condition

ConditionType

0..1

A condition that determines if the content element is relevant to a particular deployment.

Variables

VariablesType

0..1

Variables for use within the InstallableUnit’s requirements and artifact definitions.

RequiredBase

RequiredBaseType

0..1

A resource that will be updated when the InstallableUnit’s UpdateArtifact is processed.

Requirements

RequirementsType

0..1

Requirements that must be met prior to successful processing of the InstallableUnit’s artifacts.

Languages

LanguagesType

0..1

Languages supported by the InstallableUnit.

Completion

CompletionType

0..*

Describes completion actions such as restart and the conditions under which the action is applied.

ResultingResource

ResultingResourceType

0..*

A resource that will be installed or updated by processing the InstallableUnit’s artifacts.

ResultingChange

ResultingChangeType

0..*

A resource that will be configured by processing the InstallableUnit’s artifacts.

Artifacts

InstallationArtifactsType

1

The set of artifacts associated with the InstallableUnit.

 

xsd:any

0..*

 

id

xsd:ID

1

An identifier for the InstallableUnit scoped to the deployment descriptor.

targetResourceRef

xsd:IDREF

1

Reference to the resource that can process the InstallableUnit’s artifacts.

 

xsd:anyAttribute

0..*

 

4.3.1.2 InstallableUnitType Property Usage Notes

§         Identity: The InstallableUnit’s Identity element defines human-understandable information that reflects the identity of the solution as understood by the end user of the solution.

If the InstallableUnit defines a resulting resource, the Identity of the InstallableUnit SHOULD reflect the identity of the resulting resource.

When the InstallableUnit is the only content element in the deployment descriptor, its Identity MAY define values that are the same as the corresponding PackageIdentity element values.

This would be useful, for example, in a case where the package is known by the same name as the resource created by the InstallableUnit.

See the IdentityType section for structure and additional usage details [3.4].

§         Condition: A Condition is used when the InstallableUnit’s content should be deployed only when certain conditions exist in the deployment environment.

For example, one InstallableUnit may be applicable only when the operating system resource is resolved to a Linux®[2] operating system during deployment. The InstallableUnit would define a Condition stating that the type of the operating system must be Linux for the InstallableUnit to be considered in scope for a particular deployment.

See the ConditionType section for structure and additional usage details [4.5.1].

§         Variables: An InstallableUnit’s Variables element defines variables that are used in the definition of the InstallableUnit’s requirements and in parameters and properties passed to the InstallableUnit’s target resource.

When the deployment descriptor defines a single InstallableUnit at the top level, that is, not inside a CompositeInstallable, the variables it defines MAY be referred to by any element under Topology.

See the VariablesType section for structure and additional usage details [4.6.3].

§         Languages: When translated materials are deployed by the InstallableUnit’s artifacts, the languages of the translations are listed in Languages.

See the LanguagesType section for structure and additional usage details [4.13.6].

§         RequiredBase: When an InstallableUnit can be used to update resources, the RequiredBase element identifies the resources that can be updated.

See the RequiredBaseType section for structure and additional usage details [4.7.8].

§         Requirements: Requirements specified in an InstallableUnit identify requirements that must be met prior to successful processing of the InstallableUnit’s artifacts.

See the RequirementsType section for structure and additional usage details [4.7.1].

§         Completion: A Completion element MUST be included if the artifact being processed requires a system operation such as a reboot or logoff to occur to function successfully after deployment or if the artifact executes a system operation to complete deployment of the contents of the artifact.

There MUST be an artifact associated with the operation defined by a Completion element.

For example, if there is a Completion element for the install operation, the InstallableUnit must define an InstallArtifact.

See the CompletionType section for structure and additional usage details [4.3.14].

§         ResultingResource: An InstallableUnit’s ResultingResource element identifies the resources in Topology that will be installed or updated when the InstallableUnit’s artifacts are processed.

See the ResultingResourceType section for structure and additional usage details [4.8.1].

§         ResultingChange: Multiple content elements within the SDD MAY specify the same resource in their ResultingChange elements. In this case each content element is capable of modifying the configuration of that resource.

An example use of the ResultingChange element is to understand whether or not one content element can satisfy the requirements specified in another content element.

See the ResultingChangeType section for structure and additional usage details [4.8.2].

§         Artifacts: When the InstallableUnit is a singleton defined outside of a CompositeInstallable, it MUST define at least one artifact element and MAY define one of each type of artifact element allowed for its type. The inclusion of an artifact element in a singleton InstallableUnit implies support for the associated operation.

When the InstallableUnit is defined within a CompositeInstallable, it MUST define exactly one artifact. The artifact defined MAY be any artifact allowed in an InstallableUnit and it MUST support the single top level operation defined by the CompositeInstallable. This does not mean the operation associated with the artifact has to be the same as the one defined by the CompositeInstallable.

For example, an update of a resource may be required to support an install of the overall solution, in which case the InstallableUnit would define an UpdateArtifact to support the top level install operation.

See the InstallationArtifactsType section for structure and additional usage details [4.3.4].

§         id: The id attribute is referenced in features to identify an InstallableUnit selected by the feature and Dependency elements to indicate a dependency on processing of the content element.

The id attribute may be useful to software that processes the SDD, for example, for use in creating log and trace messages.

§         targetResourceRef: The targetResourceRef attribute identifies the resource that will process the InstallableUnit’s artifacts.

The resources created or modified by artifact processing are frequently, but not necessarily, hosted by the target resource.

This value MUST match an id of a resource element in Topology.

The target may be a resource that has not yet been created. In this case, there is a dependency on the complete installation of the target resource prior to applying the InstallableUnit. This dependency MUST be represented in a Dependency element within Requirements that apply to the InstallableUnit.

4.3.2 ConfigurationUnitType

Figure 20: ConfigurationUnitType structure.

The ConfigurationUnit element defines artifacts that configure one or more existing resources. It also defines the requirements for applying those artifacts. It MUST NOT install, update, or uninstall resources.

4.3.2.1 ConfigurationUnitType Property Summary

Name

Type

*

Description

Identity

IdentityType

0..1

Human-understandable identity information about the ConfigurationUnit.

Condition

ConditionType

0..1

A condition that determines if the content element is relevant to a particular deployment.

Variables

VariablesType

0..1

Variables for use within the ConfigurationUnit’s requirement and artifact definitions.

Requirements

RequirementsType

0..1

Requirements that must be met prior to successful processing of the ConfigurationUnit’s artifacts.

Completion

CompletionType

0..*

Describes completion actions such as restart and the conditions under which the action is applied.

ResultingChange

ResultingChangeType

0..*

A definition of changes made to a resource that is configured by processing the ConfigurationUnit’s ConfigArtifact.

Artifacts

ConfigurationArtifactsType

1

The artifact associated with the ConfigurationUnit.

 

xsd:any

0..*

 

id

xsd:ID

1

An identifier for the ConfigurationUnit scoped to the deployment descriptor.

targetResourceRef

xsd:IDREF

1

Reference to the resource that can process the ConfigurationUnit’s artifacts.

 

xsd:anyAttribute

0..*

 

4.3.2.2 ConfigurationUnitType Property Usage Notes

§         Identity: The ConfigurationUnit’s Identity element defines human-understandable information that reflects the identity of the provided configuration as understood by the end user of the solution. Identity has elements that are common with elements in the corresponding PackageDescriptor’s PackageIdentity element, for example, Name and Version. The values of these common elements SHOULD be the same as the corresponding PackageIdentity element values.

See the IdentityType section for structure and additional usage details [3.4].

§         Condition: A Condition is used when the deployment of configuration content is dependent on the existence of certain conditions in the deployment environment.

For example, a package that has one configuration artifact that creates a database table for one database product and a different artifact that creates a table for a different database product would have two configuration units, each with a condition on the associated database product.

See the ConditionType section for structure and additional usage details [4.5.1].

§         Variables: A ConfigurationUnit’s Variables element defines variables that are used in the definition of requirements and artifact parameters.

When the deployment descriptor defines a single ConfigurationUnit at the top level, that is, not inside a CompositeInstallable, the variables it defines MAY be referred to by any element under Topology.

See the VariablesType section for structure and additional usage details [4.6.3].

§         Requirements: Requirements specified in a ConfigurationUnit identify requirements that MUST be met prior to successful processing of the ConfigurationUnit’s artifacts.

See the RequirementsType section for structure and additional usage details [4.7.1].

§         Completion: A Completion element MUST be included if the artifact being processed requires a system operation such as a reboot or logoff to occur to function successfully after deployment or if the artifact executes a system operation to complete deployment of the contents of the artifact.

There MUST be an artifact associated with the operation defined by a Completion element.

For example, if there is a Completion element for the configure operation, the ConfigurationUnit must define a ConfigArtifact.

See the CompletionType section for the structure and additional usage details [4.3.14].

§         ResultingChange: Configuration changes made when the configuration artifact is processed SHOULD be declared here. This information may be necessary when the SDD is aggregated into another SDD and the resulting change satisfies a constraint in the aggregation. The information declared here can be compared with resource constraints to determine if application of the ConfigurationUnit will satisfy the constraint.

See the ResultingChangeType section for structure and additional usage details [4.8.2].

§         Artifacts: When the ConfigurationUnit is a singleton defined outside of a CompositeInstallable, it MUST define at least one artifact element. The inclusion of an artifact element in a singleton ConfigurationUnit implies support for the associated operation.

When the ConfigurationUnit is defined within a CompositeInstallable, it MUST define exactly one artifact. The artifact defined MUST be a ConfigArtifact and it MUST support the single top level operation defined by the CompositeInstallable.   

See the ConfigurationArtifactsType section for structure and additional usage details [4.3.5].

§         id: The id attribute may be useful to software that processes the SDD, for example, for use in creating log and trace messages.

§         targetResourceRef: The targetResourceRef attribute identifies the resource in Topology that will process the ConfigurationUnit’s artifacts to configure the resources identified by the ConfigurationUnit’s ResultingChange definition.

This value MUST match an id of a resource element in Topology.

4.3.3 ArtifactType

Figure 21: ArtifactType structure.

ArtifactType elements define the files, arguments and other information required to perform a particular deployment operation. Every artifact that can be defined in a content element is an instance of ArtifactType. These are InstallArtifact, UpdateArtifact, UndoArtifact, UninstallArtifact, RepairArtifact and ConfigArtifact.

4.3.3.1 ArtifactType Property Summary

Name

Type

*

Description

Arguments

ArgumentListType

0..1

Arguments used during processing of the artifact.

OutputVariables

OutputVariableListType

0..1

Variables whose values are set during processing of the artifact.

AdditionalContent

AdditionalContentType

0..*

Additional content files that are part of the artifact.

 

xsd:any

0..*

 

contentRef

xsd:token

0..1

The primary artifact file. Not used if resourceRef is used.

resourceRef

xsd:IDREF

0..1

The resulting resource representing the artifact file. Not used if contentRef is used.

type

ArtifactTypeNameType

0..1

Type of the primary artifact file.

weight

xsd:positiveInteger

0..1

The time required to process this artifact relative to all other artifacts in the SDD.

 

xsd:anyAttribute

0..*

 

4.3.3.2 ArtifactType Property Usage Notes

§         Arguments: Inputs to the processing of the artifact MUST be specified by defining an Arguments element. All required inputs MUST be included in the arguments list. There are no implied arguments.

For example, there is no implication that the selected required resource instances will be passed with an InstallArtifact on the install operation. If knowledge of those selections is required, instance identifiers should be passed as arguments.

When one Argument refers to the OutputVariable of another artifact, the output value must be available at the time of processing the dependent artifact.

For example, an artifact in a content element that is conditioned on the operating system being Linux should not refer to the output of an artifact in a content element conditioned on the operating system being Windows[3].

A Dependency requirement MUST be defined between the content elements to indicate that the artifact that defines the output variable is a pre-requisite of the content element with the dependent artifact.

See the ArgumentListType section for structure and additional usage details [4.3.8].

§         OutputVariables: OutputVariables are variables whose values are set by artifact processing.

OutputVariables can also be useful in log and trace messages.

See the OutputVariableListType section for structure and additional usage details [4.3.10].

§         AdditionalContent: AdditionalContent elements MUST be defined when supporting files are needed by the artifact for this operation. The content file reference is specified via the contentRef attribute of AdditionalContent.

See the AdditionalContentType section for structure and additional usage details [4.3.12].

§         contentRef: The value MUST be a reference to the id of the primary artifact file defined in a Content element in the package descriptor.

Note that it is valid to have no artifact file and drive the operation from arguments alone.

When more than one artifact file is needed, contentRef points to the primary artifact file and AdditionalContent.contentRef points to any other files used during application of the content element.

When resourceRef is defined, contentRef MUST NOT be defined.

§         resourceRef: Sometimes, artifact files are created during a deployment rather than being contained in the package.

For example, some install programs create an uninstall program when the software is deployed. The uninstall program is the artifact file that is needed by the UninstallArtifact, but is created by, but not contained in, the package. In this case, the created artifact file is represented as a ResultingResource.

An Artifact element that defines resourceRef identifies the resulting resource as its artifact file.

When contentRef is defined, resourceRef MUST NOT be defined.

The value MUST reference the id of a resource element in Topology.

§         type: The type attribute identifies the format of the artifact file or files. When there is no artifact file identified, type MAY be left undefined. If there is an artifact file or additional files defined, type MUST be defined.

Values for this attribute are not defined by this specification. ArtifactTypeNameType restricts type to valid xsd:QNames.

§         weight: Defining weights for all artifacts and referenced packages in an SDD provides useful information to software that manages deployment. The weight of the artifact refers to the relative time taken to deploy the artifact with respect to other artifacts and referenced packages in this SDD.

For example, if the artifact takes three times as long to deploy as another artifact whose weight is “2”, then the weight would be “6”. The weight numbers have no meaning in isolation and do not describe actual time elapsed. They simply provide an estimate of relative time.

4.3.4 InstallationArtifactsType

Figure 22: InstallationArtifactsType structure.

InstallationArtifactsType provides the type definition for the Artifacts element of InstallableUnit and LocalizationUnit. At least one Artifact element MUST be defined. Within a CompositeInstallable definition, exactly one Artifact element MUST be defined.

4.3.4.1 InstallationArtifactsType Property Summary

Name

Type

*

Description

InstallArtifact

ArtifactType

0..1

Artifact for install operation.

UpdateArtifact

ArtifactType

0..1

Artifact for update operation.

UndoArtifact

ArtifactType

0..1

Artifact for undo operation.

UninstallArtifact

ArtifactType

0..1

Artifact for uninstall operation.

RepairArtifact

ArtifactType

0..1

Artifact for repair operation.

 

xsd:any

0..*

 

4.3.4.2 InstallationArtifactsType Property Usage Notes

§         InstallArtifact: The InstallArtifact element declares deployment information sufficient to enable the target resource to perform an install using the named artifact files. The ResultingResource and ResultingChange elements describe the characteristics of the new or modified resource(s).

See the ArtifactType section for structure and additional usage details [4.3.3].

§         UpdateArtifact: The UpdateArtifact element declares deployment information sufficient to enable the target resource to perform an update using the named artifact files. The RequiredBase element defines the resource(s) that can be updated. The ResultingResource and ResultingChange elements describe the updated characteristics of the resource(s).

See the ArtifactType section for structure and additional usage details [4.3.3].

§         UndoArtifact: The UndoArtifact element declares deployment information sufficient to enable the target resource to undo an update. This undo will put the resource back to a previous level.

The update that can be undone is described in the RequiredBase element. The ResultingResource definition can be used to describe the state of the resource(s) after the undo completes.