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.
The purpose of this document is to provide the normative
specification of the SDD, including concepts, structure, syntax, semantics and
usage.
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]).
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.
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].
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.
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™
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.
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].
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.
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.
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.
[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
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.
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.
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.
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].
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.
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:
- CapacityConstraint
- ConsumptionConstraint
- PropertyConstraint
- VersionConstraint
- UniquenessConstraint
- RelationshipConstraint
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.
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.
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.
|
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..*
|
|
§
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.
§
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].
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].
|
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..*
|
|
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.
|
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..*
|
|
§
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.
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 fixes—for
example, a fix pack—MaintenanceInformation
describes each of the fixes provided by the fix pack.
|
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..*
|
|
§
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].
Figure 7: FixIdentityType structure.
Elements of FixIdentityType
describe fixes that will be applied when the package is deployed or the content
element is applied.
|
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..*
|
|
§
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].
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.
|
Name
|
Type
|
*
|
Description
|
|
buildID
|
xsd:token
|
1
|
Identifies the
build of the package or package element.
|
|
|
xsd:anyAttribute
|
0..*
|
|
§
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.
|
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..*
|
|
§
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].
Figure 10: LocationType structure.
LocationType supports inclusion of the
manufacturer’s address and country in package and content element identity.
|
Name
|
Type
|
*
|
Description
|
|
Address
|
DisplayTextType
|
0..1
|
The
manufacturer’s address.
|
|
Country
|
DisplayTextType
|
0..1
|
The
manufacturer’s country.
|
§
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].
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.
Figure 11: Contents structure.
ContentsType
is used in PackageDescriptor to
provide a list of one or more Content
elements.
|
Name
|
Type
|
*
|
Description
|
|
Content
|
ContentType
|
1..*
|
Describes
the physical contents of the software package.
|
§
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].
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 files—such as their length, purpose and
character encoding—MAY be
declared in the package descriptor.
|
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..*
|
|
§
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.
§
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.
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.
|
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..*
|
|
§
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.
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.
|
Name
|
Type
|
*
|
Description
|
|
Resource
|
ResourceType
|
1..*
|
The root of a
tree of resources that play a role in the solution.
|
|
|
xsd:any
|
0..*
|
|
§
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 ResourceType—both the top level Resource elements and the HostedResource elements within the
resource hierarchy—make 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:
- as
the target of the content element’s artifacts. A target resource is a
resource that is capable of processing a particular artifact. A target
resource is often, but not always, the host of the resources created by
the artifacts it processes.
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.
- as
the required base for an update applied by the artifact referenced by the content
element.
See the RequiredBaseType section [4.7.8].
- as
the resource that will be created by deploying the artifact referenced by
the content element.
See the ResultingResourceType section [4.8.1].
- as
the resource that will be changed by deploying the artifact referenced by
the content element.
See the ResultingChangeType section [4.8.2].
- as
the localization base for translated materials. The localization base is
the resource that is localized by deploying the translated materials.
See the LocalizationBase element in the LocalizationUnitType
section [4.13.2].
- as a
required resource named in the content element’s Requirements.
See the RequirementsType section [4.7.1].
- to
establish a variable value from a resource property.
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.
|
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 hosts–hostedBy 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].
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].
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.
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.
|
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..*
|
|
§
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®
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.
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.
|
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..*
|
|
§
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.
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™.
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.
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.
See
the ArtifactType section for structure
and additional usage details [4.3.3].
§
UninstallArtifact:
The UninstallArtifact element
declares deployment information sufficient to enable the target resource to perform
an uninstall.
If an InstallArtifact
is defined in the same InstallableUnit,
the ResultingResource element defines
the resource(s) that will be uninstalled.
When an UninstallArtifact
is the only artifact defined for an InstallableUnit,
the RequiredBase MUST be defined to
declare the resource(s) that will be uninstalled. The ResultingResource element MUST be left blank because the result of
the uninstall is that the resource(s) are removed.
See
the ArtifactType section for structure
and additional usage details [4.3.3].
§
RepairArtifact:
The RepairArtifact element declares
deployment information sufficient to enable the target resource to repair an
installation.
If
an InstallArtifact is defined in the
same InstallableUnit, the ResultingResource element defines the
resource(s) that will be repaired.
When
a RepairArtifact is the only artifact
defined for an InstallableUnit, the RequiredBase MUST be defined to declare
the resource(s) that will be repaired.
See
the ArtifactType section for structure
and additional usage details [4.3.3].
Figure
23:
ConfigurationArtifactsType structure.
ConfigurationArtifactsType provides the
type definition for the Artifacts
element of ConfigurationUnit.
4.3.5.1 ConfigurationArtifactsType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
ConfigArtifact
|
ArtifactType
|
0..1
|
Artifact for configure operation.
|
|
|
xsd:any
|
0..*
|
|
4.3.5.2 ConfigurationArtifactsType
Property Usage Notes
§
ConfigArtifact:
The ConfigArtifact element declares
deployment information sufficient to allow the target resource to configure the
resources identified in the content element’s ResultingChange elements.
See
the ArtifactType section for
structure and additional usage details [4.3.3].
This
simple type extends the xsd:list type
as defined in [XSD], and adds the restriction that each value in the
list must be one of the operations from the enumeration defined by OperationType [4.3.7].
4.3.7 OperationType
Operations
are used in the SDD to associate requirements and completion actions with
particular artifacts.
For
example, when a requirement defines an operation
attribute with value undo, it is a
statement that the requirement must be met prior to processing of the undo
artifact.
OperationType enumerates the basic resource
lifecycle operations that use the content and information defined in the SDD to
change the state of the resources being installed, updated, or configured.
4.3.7.1 OperationType
Property Usage Notes
Elements
and attributes of OperationType MUST
be set to one of the following values:
§
configure:
Uses the ConfigArtifact to perform
configuration actions on a resource.
§
install:
Uses the InstallArtifact to install
resources.
§
repair:
Uses the RepairArtifact to repair an
installation.
§
undo:
Uses the UndoArtifact to restore a
resource to the state before the most recent update was applied.
§
update:
Uses the UpdateArtifact to update an
existing instance of a resource, as specified by the required base.
§
use:
Associates a requirement or completion action with use of the deployed software
resources. Setting the operation attribute to use indicates that the requirement or completion action is not
associated with an artifact.
§
uninstall:
Uses the UninstallArtifact to
uninstall a resource.
Figure
24: ArgumentListType
structure.
Each
artifact MAY optionally include an Arguments
element whose type is provided by ArgumentListType.
This simply defines a list of Argument
elements.
4.3.8.1 ArgumentListType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
Argument
|
ArgumentType
|
1..*
|
An input to artifact processing.
|
4.3.8.2 ArgumentListType
Property Usage Notes
§
Argument:
An argument value is a variable expression used to define a fixed value for the
argument or to define a value in terms of one of the variables visible to the
artifact.
See
the ArgumentType section for
structure and additional usage details [4.3.9].
Figure
25: ArgumentType structure.
ArgumentType provides the type
definition for Argument elements in
artifacts [4.3.3]. This complex type is used to declare the argument
name and optionally include a value for that argument.
4.3.9.1 ArgumentType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
name
|
VariableExpressionType
|
1
|
The argument name.
|
|
value
|
VariableExpressionType
|
0..1
|
The argument value.
|
|
required
|
xsd:boolean
|
0..1
|
Indicates that the argument value must result in a valid
expression for each particular deployment.
**default value=“true”
|
|
|
xsd:anyAttribute
|
0..*
|
|
4.3.9.2 ArgumentType
Property Usage Notes
§
name:
Evaluation of the name expression
produces the name of the argument. This can be useful for arguments with only a
name, for example, those that are not name-value pairs.
When the argument name alone is sufficient
to communicate its meaning, the argument value SHOULD be omitted.
See the VariableExpressionType
section for structure and additional usage details [4.6.1].
§
value:
Evaluation of the value expression
provides the value of the argument.
The variable expression MAY be used to
define a fixed value for the argument or to define a value in terms of one of
the variables visible to the artifact.
See the VariableExpressionType
section for structure and additional usage details [4.6.1].
§
required:
In cases where the argument should be ignored when the value expression is not
valid for a particular deployment, set required to "false".
Figure 26:
OutputVariableListType structure.
An
artifact can set variables. The variables set by the artifact are defined in
the artifact’s OutputVariables.
4.3.10.1 OutputVariableListType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
OutputVariable
|
OutputVariableType
|
1..*
|
An
output from artifact processing.
|
4.3.10.2 OutputVariableListType
Property Usage Notes
§
OutputVariable:
This is the definition of the variable, not a reference to a variable defined
elsewhere.
See the OutputVariableType
section for structure and additional usage details [4.3.11].
Figure 27: OutputVariableType
structure.
Output
variables are variables whose value is set by artifact processing. OutputVariableType extends BaseVariableType and so has all of the
attributes defined there, including an id
attribute that is used to refer to the output variable within the SDD. Output
variables can be useful in log and trace messages.
4.3.11.1 OutputVariableType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
|
[extends]
BaseVariableType
|
|
See
the BaseVariableType section for additional properties [4.6.2].
|
|
outputParameterName
|
xsd:NCName
|
0..1
|
An
output from artifact processing.
|
|
|
xsd:anyAttribute
|
0..*
|
|
4.3.11.2 OutputVariableType
Property Usage Notes
See the BaseVariableType
section for details of the inherited attributes and elements [4.6.2].
§
outputParameterName:
This is the name of the output variable as understood within the artifact
processing environment. The output value is associated with the output
variable’s id. The SDD author uses
this id within the SDD to refer to
this output value.
Figure 28: AdditionalContentType
structure.
When artifact processing requires more than
a single file, the artifact declaration includes information about the
additional files needed. AdditionalContentType
provides the type definition. Additional content MAY include input files that
need to be edited to include values received as input to a particular solution
deployment. In this case, the additional file can include a Substitution element.
4.3.12.1 AdditionalContentType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
Substitution
|
SubstitutionType
|
0..*
|
A
value to substitute into the file.
|
|
|
xsd:any
|
0..*
|
|
|
contentRef
|
xsd:token
|
1
|
A reference to the content element’s id defined in
the package descriptor.
|
|
type
|
ArtifactTypeNameType
|
0..1
|
Type
of the additional artifact file.
|
|
|
xsd:anyAttribute
|
0..*
|
|
4.3.12.2 AdditionalContentType
Property Usage Notes
§
Substitution:
The Substitution element supports the
use of files that require some editing before they can be used in artifact
processing. The definitions in this element support placement of values
determined during a particular deployment into the file identified by the contentRef attribute.
See the SubstitutionType
section for structure and additional usage details [4.3.13].
§
contentRef:
The contentRef attribute points back
to the package descriptor for information about the physical file. This value
MUST match an id of a content element
in the package descriptor.
§
type:
The type attribute identifies the
format of the additional file. Values for this attribute are not defined by
this specification. ArtifactTypeNameType
restricts values of type to valid xsd:QNames.
Figure 29: SubstitutionType
structure.
SubstitutionType
provides the type definition for the Substitution
element in AdditionalContent
declarations. It enables declaration of patterns in the file and the values
that should replace the patterns before the file is used in artifact
processing.
4.3.13.1 SubstitutionType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
Pattern
|
xsd:string
|
1
|
The
search pattern in the file that needs to be substituted.
|
|
Value
|
VariableExpressionType
|
1
|
The
value to be substituted in the file.
|
|
limit
|
xsd:positiveInteger
|
0..1
|
The
number of substitutions that should be made.
|
|
required
|
xsd:boolean
|
0..1
|
Indicates
that substitution's value must result in a valid expression for each
particular deployment.
**default
value=“true”
|
|
|
xsd:anyAttribute
|
0..*
|
|
4.3.13.2 SubstitutionType
Property Usage Notes
§
Pattern:
This is the string that will be replaced with the value when found in the file.
§
Value:
Evaluation of the variable expression results in the value that will be
substituted for the pattern.
See the VariableExpressionType
section for structure and additional usage details [4.6.1].
§
limit:
If limit is not defined, there is no
limit and all instances of the pattern found in the file will be replaced.
§
required:
In cases where the substitution should be ignored when the value expression is
not valid for a particular deployment, set required to “false”.
Figure 30: CompletionType
structure.
For some deployments certain completion
actions such as restart and logoff are required before a deployment operation
using a particular content element can be considered complete. The CompletionType elements enable the SDD
author to indicate either that one of these actions is required or that one of
these actions will be performed by the associated artifact.
4.3.14.1 CompletionType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
DisplayName
|
DisplayTextType
|
0..1
|
Name
of the completion action.
|
|
Description
|
DisplayTextType
|
0..1
|
Description
of the completion action.
|
|
ShortDescription
|
DisplayTextType
|
0..1
|
Short
description of the completion action.
|
|
Condition
|
ConditionType
|
0..1
|
Conditions
that determine when the completion action will be used.
|
|
|
xsd:any
|
0..*
|
|
|
type
|
CompletionTypeNamesType
|
1
|
The
type of the completion action.
|
|
resourceRef
|
xsd:IDREF
|
1
|
The
resource where the completion action will be executed.
|
|
operation
|
OperationListType
|
1
|
Associates
a completion action with the processing of a particular artifact.
|
|
|
xsd:anyAttribute
|
0..*
|
|
4.3.14.2 CompletionType
Property Usage Notes
§
DisplayName:
This element MAY be
used to provide human-understandable information. If used, it MUST
provide a label for the Completion element.
See the DisplayElementGroup
section for structure and additional usage details [4.14.2].
§
Description,
ShortDescription: These elements MAY be
used to provide human-understandable information. If used, they MUST
provide a description of the Completion
element.
The
Description element MUST be defined
if the ShortDescription element is
defined.
See
the DisplayElementGroup section for
structure and additional usage details [4.14.2].
§
Condition:
Conditions specified on resource characteristics
determine if the completion action applies. If the conditions are met, the
action applies. If not met, then the action is not needed. Unmet conditions are
not considered a failure. When no conditions are defined, the action always
applies.
See the ConditionType
section for structure and additional usage details [4.5.1].
§
type:
This is the completion action that applies when conditions defined in ResourceConstraint are met. Allowed
values defined in CompletionTypeNameType
are:
·
restartRequiredImmediately:
A system restart is required before the deployment operation is
considered complete and the artifact associated with the operation does not
perform the restart. The restart MUST happen before further deployment actions
are taken.
·
restartRequiredBeforeUse:
A system restart is required before the deployment operation is
considered complete and the artifact associated with the operation does not
perform this action. The restart MUST happen before the associated resources
are used.
·
restartOccurs:
The artifact associated with the lifecycle operation will initiate a
system restart.
·
logoffRequired:
A logoff and logon to the user account is required before the deployment
operation is considered complete and the artifact associated with the operation
does not perform this action. The logoff and logon MUST happen before the
operation can be considered complete.
§
resourceRef:
This will often be the resource named as the target resource for the defining
content element.
The
value MUST reference the id of a
resource element in Topology.
§
operation:
A completion action is associated with the processing of one artifact by
setting operation to the operation
associated with that artifact. The element that defines the Completion MUST also define an artifact
associated with the operation defined for the Completion element.
See the OperationListType
section for operation enumerations
and their meaning [4.3.6].
4.4 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. See the RequirementsType section [4.7.1].
§
Other constraints must be met for a resource to
serve as the required base for an update. See the RequiredBaseType section [4.7.8].
§
Still others must be met for to satisfy a
condition that determines the applicability of a content element or completion
action. See the ConditionType section
[4.5.1] and the CompletionType
section [4.3.14].
The Constraint
types described in this section support identification of resource constraints
in these various contexts. These types are:
§
CapacityConstraint
§
ConsumptionConstraint
§
PropertyConstraint
§
VersionConstraint
§
UniquenessConstraint
§
RelationshipConstraint
All of these constraint types are
constraints on a property of a resource. There are different constraint types
because there are distinct semantics for different types of resource properties.
Examples of these varying semantics include constraints that the property value
be:
·
within a certain range;
·
one of a set of values;
·
all of a set of values;
·
equal to a certain value;
·
no more than or no less than a certain value;
·
no more than or no less than a certain value
when all constraints of that type are added together.
In all cases, deployment software must be
able to discover the property’s value to honor the SDD author’s intent.
Figure 31:
CapacityConstraintType structure.
CapacityConstraintType
provides the type definition of the Capacity
elements of RequirementResourceConstraintType
[4.7.5]. These elements are used to express a requirement on
the capacity of a particular resource property such as memory available from an
operating system. Capacity is shared: multiple capacity constraints expressed
on the same property are evaluated individually without assuming any change to
the available quantity of the property.
4.4.1.1 CapacityConstraintType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
Description
|
DisplayTextType
|
0..1
|
A
description of the capacity constraint. Required if ShortDescription is
defined.
|
|
ShortDescription
|
DisplayTextType
|
0..1
|
A
short description of the capacity constraint.
|
|
PropertyName
|
xsd:QName
|
1
|
Name
of the constrained property.
|
|
Value
|
CapacityValueType
|
1
|
Bounds
on the value of the constrained property.
|
4.4.1.2 CapacityConstraintType
Property Usage Notes
§
Description,
ShortDescription: These elements MAY be
used to provide human-understandable information. If used, they MUST provide
a description of the capacity constraint on 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].
§
PropertyName:
This name corresponds to the name of the constrained resource property in the
environment. This name may be specified in profiles [5.3].
§
Value:
Value specifies the bound and
optional recommended bound on the resource property identified in the PropertyName element.
See the CapacityValueType
section for structure and additional usage details [4.4.2].
Figure 32: CapacityValueType
structure.
Capacity value is expressed in terms of a
minimum or maximum capacity. CapacityValueType
provides the elements that support this expression. It also supports expression
of a recommended minimum or maximum capacity.
4.4.2.1 CapacityValueType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
Minimum
|
VariableExpressionType
|
0..1
|
Minimum
capacity.
|
|
Maximum
|
VariableExpressionType
|
0..1
|
Maximum
capacity.
|
|
MinimumRecommended
|
VariableExpressionType
|
0..1
|
Minimum
recommended capacity.
|
|
MaximumRecommended
|
VariableExpressionType
|
0..1
|
Maximum
recommended capacity.
|
|
unit
|
xsd:string
|
0..1
|
Unit
of measure used to interpret the capacity value.
|
|
|
xsd:anyAttribute
|
0..*
|
|
4.4.2.2 CapacityValueType
Property Usage Notes
§
Minimum:
There will usually be either a minimum value or a maximum value defined, but
not both. When minimum is specified, the actual value of the capacity property
MUST be equal to or greater than the minimum value.
See the VariableExpressionType
section for structure and additional usage details [4.6.1].
§
Maximum:
When specified, the actual value of the capacity property MUST be less than or
equal to the defined maximum.
If Minimum
and Maximum are both defined, Minimum MUST be less than or equal to Maximum.
See the VariableExpressionType
section for structure and additional usage details [4.6.1].
§
MinimumRecommended:
The SDD author can indicate a preferred, but not required, minimum by defining
a value for this element.
See the VariableExpressionType
section for structure and additional usage details [4.6.1].
§
MaximumRecommended:
The SDD author can indicate a preferred, but not required, maximum by defining
a value for this element.
If MinimumRecommended
and MaximumRecommended are both
defined, MinimumRecommended MUST be
less than or equal to MaximumRecommended.
See the VariableExpressionType
section for structure and additional usage details [4.6.1].
§
unit:
Values for unit SHOULD be well-known
units of measure from the International System of Units [UNIT]. A unit of measure SHOULD be specified for all properties that
are measured in any kind of unit.
Figure 33:
ConsumptionConstraintType structure.
ConsumptionConstraintType
provides the type definition of the Consumption
elements of RequirementResourceConstraintType
[4.7.5]. These elements are used to express a requirement on
the available quantity of a particular resource property such as disk space on
a file system. ConsumptionConstraints
represent exclusive use of the defined quantity of the resource property. In
other words, consumption constraints are additive, with each consumption
constraint specified in the SDD adding to the total requirement for the
specified resource(s). A consumption constraint is assumed to alter the
available quantity such that the portion of the property used to satisfy one
constraint is not available to satisfy another consumption constraint on the
same property.
For example, suppose that the target file
system has 80 megabytes available. The application of a content element’s InstallArtifact results in installation
of files that use 5 megabytes of file space.
The application of a second InstallArtifact
results in installation of files that use 2 megabytes of file space.
Consumption constraints are additive, so the total space used for this content
element is 7 megabytes, leaving 73 (80–7) megabytes available on the target
file system.
4.4.3.1 ConsumptionConstraintType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
Description
|
DisplayTextType
|
0..1
|
A
description of the consumption constraint. Required if ShortDescription is
defined.
|
|
ShortDescription
|
DisplayTextType
|
0..1
|
A
short description of the consumption constraint.
|
|
PropertyName
|
xsd:QName
|
1
|
Names
the resource property to test.
|
|
Value
|
ConsumptionConstraintValueType
|
1
|
A
variable expression defining the minimum available quantity.
|
4.4.3.2 ConsumptionConstraintType
Property Usage Notes
§
Description,
ShortDescription: These elements MAY be
used to provide human-understandable information. If used, they MUST provide
a description of the consumption constraint on 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].
§
PropertyName:
The property name can be used to find the property value in the deployment environment.
This name may be specified in profiles [5.3].
§
Value:
The result of evaluating this variable expression represents the minimum
quantity of the named resource property that MUST be available for successful
deployment of the defining content element’s artifacts. This quantity will be
consumed by application of the associated artifact.
See the ConsumptionConstraintValueType
section for structure and additional usage details [4.4.4].
Figure 34:
ConsumptionConstraintValueType structure.
A consumption value is defined using a
variable expression. ConsumptionConstraintValueType
provides the variable expression by extending VariableExpressionType.
4.4.4.1 ConsumptionConstraintValueType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
|
[extends]
VariableExpressionType
|
|
See
the VariableExpressionType section for additional properties [4.6.1].
|
|
unit
|
xsd:string
|
0..1
|
Unit
of measure used to interpret the consumption value.
|
|
|
xsd:anyAttribute
|
0..*
|
|
4.4.4.2 ConsumptionConstraintValueType
Property Usage Notes
See the VariableExpressionType
section for details of the inherited attributes and elements [4.6.1].
§
unit:
Values for unit SHOULD be well-known
units of measure from International System of Units [UNIT]. A unit of measure SHOULD be specified for all
properties which are measured in any kind of unit.
Figure 35:
PropertyConstraintType structure.
PropertyConstraintType
provides the type definition of the Property
elements of RequirementResourceConstraintType
[4.7.5]. It supports definition of a required value or set
of acceptable values for a particular resource property.
4.4.5.1 PropertyConstraintType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
Description
|
DisplayTextType
|
0..1
|
A
description of the property constraint. Required if ShortDescription is
defined.
|
|
ShortDescription
|
DisplayTextType
|
0..1
|
A
short description of the property constraint.
|
|
PropertyName
|
xsd:QName
|
1
|
Name
of the constrained property.
|
|
Value
|
VariableExpressionType
|
0..1
|
Required
property value.
|
|
ListOfValues
|
PropertyValueListType
|
0..1
|
List
of required property values.
|
4.4.5.2 PropertyConstraintType
Property Usage Notes
§
Description,
ShortDescription: These elements MAY be
used to provide human-understandable information. If used, they MUST provide
a description of the property constraint on 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].
§
PropertyName:
The property name can be used to find the property value in the deployment
environment. This name may be specified in profiles [5.3].
§
Value:
The result of evaluating this variable expression represents the required value
of the named resource property.
See the VariableExpressionType
section for structure and additional usage details [4.6.1].
§
ListOfValues:
A list of required values can be defined in place of a single required value.
See the PropertyValueListType
section for structure and additional usage details [4.4.6].
Figure 36: PropertyValueListType
structure.
A property value list is expressed as one or
more strings representing valid values for the property.
4.4.6.1 PropertyValueListType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
Value
|
VariableExpressionType
|
1..*
|
A
property value.
|
|
match
|
PropertyMatchType
|
0..1
|
Determines
whether the actual property value must match any or all of the listed values.
**default
value=“any”
|
|
|
xsd:anyAttribute
|
0..*
|
|
4.4.6.2 PropertyValueListType
Property Usage Notes
§
Value:
The result of this variable expression represents one possible required value
of the named resource property.
See the VariableExpressionType
section for structure and additional usage details [4.6.1].
§
match:
The value or values of the property found in the deployment environment are
compared to the value or values listed in the property constraint. PropertyMatchType defines two enumerated
values: any and all. When match is set to
any, the property constraint is
considered met when any one of the found property values matches any one of the
declared property values. When match
is set to all, the constraint is
considered met when all of the declared property values match values found for
the property.
Figure 37: VersionConstraintType
structure.
VersionConstraintType
provides the type definition of the VersionConstraint
elements of RequirementResourceConstraintType
[4.7.5]. A VersionConstraint
can define a set of individual versions or ranges of versions that are
supported and a similar set that are certified.
4.4.7.1 VersionConstraintType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
Description
|
DisplayTextType
|
0..1
|
A
description of the version constraint. Required if ShortDescription is
defined.
|
|
ShortDescription
|
DisplayTextType
|
0..1
|
A
short description of the version constraint.
|
|
Supported
|
VersionConstraintValueType
|
1
|
A
supported version or set of versions.
|
|
Certified
|
VersionConstraintValueType
|
0..1
|
A
subset of the supported versions that are certified as tested.
|
4.4.7.2 VersionConstraintType
Property Usage Notes
§
Description,
ShortDescription: These elements MAY be
used to provide human-understandable information. If used, they MUST provide
a description of the version constraint on 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].
§
Supported:
If the resource version is in the Supported
set, it meets the requirements.
See the VersionConstraintValueType
section for structure and additional usage details [4.4.8].
§
Certified:
In some cases the set of required versions may be different from the set of
versions that are certified by the manufacturer as thoroughly tested.
See the VersionConstraintValueType
section for structure and additional usage details [4.4.8].
Figure 38:
VersionConstraintValueType structure.
A version constraint can be specified using
any number of individual version values in combination with any number of
version ranges.
4.4.8.1 VersionConstraintValueType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
Value
|
VersionValueType
|
0..*
|
A
version value with associated fixes specified.
|
|
Range
|
VersionRangeType
|
0..*
|
A
range of version values with associated fixes specified for each range.
|
4.4.8.2 VersionConstraintValueType
Property Usage Notes
§
Value:
Discrete version values can be defined when the set of required versions
includes versions that do not fall within a range. There is no assumption by
this specification that version values are numerically comparable. The method
of comparing version values may be resource-specific.
See the VersionValueType
section for structure and additional usage details [4.4.9].
§
Range:
See the VersionRangeType section for
structure and additional usage details [4.4.10].
Figure 39: VersionValueType
structure.
A version value includes a version and a
list of required fixes associated with that version.
4.4.9.1 VersionValueType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
Version
|
VersionType
|
1
|
An
allowable version value.
|
|
FixName
|
xsd:string
|
0..*
|
The
name of a fix.
|
4.4.9.2 VersionValueType
Property Usage Notes
§
Version:
A string containing a single, exact version value. This is compared with the
version value of specific resource instances. Only equal values satisfy this
part of the constraint.
See the VersionType
section for structure and additional usage details [3.10].
§
FixName:
Any number of FixName elements can be
defined, identifying fixes that must be discovered to be applied for the
version constraint to be considered met.
Figure 40: VersionRangeType
structure.
A VersionRange
is specified with a minimum and maximum version value and a list of required
fixes associated with that range. The method of comparing version strings in a
version range is resource-specific.
4.4.10.1 VersionRangeType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
MinVersion
|
VersionType
|
0..1
|
The
least allowable version value.
|
|
MaxVersion
|
MaxVersionType
|
0..1
|
The
greatest allowable version value.
|
|
FixName
|
xsd:string
|
0..*
|
The
name of a fix.
|
4.4.10.2 VersionRangeType
Property Usage Notes
§
MinVersion:
This is the lower bound of a version range. If MinVersion is defined but MaxVersion
is not, there is no upper bound. A version that is equal to MinVersion is within the defined range.
See the VersionType
section for structure and additional usage details [3.10].
§
MaxVersion:
This is the upper bound of a version range. If MaxVersion is defined but MinVersion
is not, there is no lower bound. A version that is equal to MaxVersion may be within the defined
range depending on the value specified for the inclusive attribute.
See the MaxVersionType
section for structure and additional usage details [4.4.11].
§
FixName:
Any number of FixNames can be defined
identifying fixes that must be found to be applied for the version constraint
is to be considered satisfied. This is true for all versions within the defined
range.
When
FixName is defined, either a MinVersion or a MaxVersion element MUST also be defined.
Figure 41: MaxVersionType
structure.
A maximum version can be inclusive or
exclusive.
4.4.11.1 MaxVersionType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
|
[extends]
VersionType
|
|
See
the VersionType section for additional properties [3.10].
|
|
inclusive
|
xsd:boolean
|
0..1
|
Indicates
whether the max version value is included in the supported range of versions.
**default
value=“false”
|
|
|
xsd:any
|
0..*
|
|
4.4.11.2 MaxVersionType
Property Usage Notes
See the VersionType
section for details of the inherited attributes and elements [3.10].
§
inclusive:
The inclusive attribute allows the
SDD author to choose the semantics of maximum version. Supported ranges are
often everything equal to or greater than the minimum version and up to, but
not including, the maximum version. Sometimes it is more convenient for the
range to include the maximum version.
Figure 42:
UniquenessConstraintType structure.
A UniquenessConstraint
is used to indicate when two resources defined in topology MUST or MUST NOT
resolve to the same resource instance during a particular deployment. A UniquenessConstraint indicates that the
two resources MUST NOT be the same when it is defined in a ResourceConstraint element with testValue=“true”. A UniquenessConstraint indicates that the
two resources MUST be the same when defined in a ResourceConstraint with testValue=“false”.
When no UniquenessConstraint
is in scope for a particular pair of resources, the two resources MAY resolve
to the same resource when their identifying characteristics are the same and
when all in-scope constraints on both resources are satisfied.
The first of the pair of resources is
identified in the resourceRef
attribute of the ResourceConstraint
element that defines the UniquenessConstraint.
The second of the pair is identified in the distinctResourceRef
attribute of the UniquenessConstraint.
4.4.12.1 UniquenessConstraintType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
Description
|
DisplayTextType
|
0..1
|
A
description of the uniqueness constraint, for example what must or must not
be unique and why.
|
|
ShortDescription
|
DisplayTextType
|
0..1
|
A
short description of the uniqueness constraint.
|
|
distinctResourceRef
|
xsd:IDREF
|
1
|
One
of the pair of resources referred to by the constraint.
|
4.4.12.2 UniquenessConstraintType
Property Usage Notes
§
Description,
ShortDescription: These elements MAY be
used to provide human-understandable information. If used, they MUST provide
a description of the uniqueness constraint on 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].
§
distinctResourceRef:
The second resource in the pair of resources.
The
value MUST reference the id of a
resource element in Topology.
Figure 43:
RelationshipConstraintType structure.
A RelationshipConstraint
identifies a particular relationship between two resources that is constrained
in some way by the SDD. The value of the testValue
attribute of the ResourceConstraint
that contains the RelationshipConstraint
determines whether the constraint MUST be satisfied or MUST NOT be satisfied.
The first resource of the pair is defined by
the resourceRef attribute of the ResourceConstraint containing the RelationshipConstraint.
4.4.13.1 RelationshipConstraintType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
Description
|
DisplayTextType
|
0..1
|
A
description of the relationship and its purpose in the overall solution.
|
|
ShortDescription
|
DisplayTextType
|
0..1
|
A
short description of the relationship.
|
|
Property
|
PropertyType
|
0..*
|
A
property constraint that further constrains the relationship.
|
|
relatedResourceRef
|
xsd:IDREF
|
0..1
|
The
second resource in the relationship.
|
|
type
|
xsd:QName
|
1
|
The
type of the relationship.
|
|
|
xsd:anyAttribute
|
0..*
|
|
4.4.13.2 RelationshipConstraintType
Property Usage Notes
§
Description,
ShortDescription: These elements MAY be
used to provide human-understandable information. If used, they MUST provide
a description of the relationship constraint on 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].
§
Property:
This element MAY be used to provide additional constraints on the relationship.
For example, a connectivity relationship
might specify additional information such as the specific protocol used (for
instance, TCP/IP) and/or particular characteristics of a protocol (for
instance, port number).
See the PropertyType
section for structure and additional usage details [4.2.3].
§
relatedResourceRef:
Naming the second resource is optional. When it is not named, the relationship
constraint is satisfied if the first resource has the defined relationship with
any other resource.
When
it is named, the value MUST reference the id
of a resource element in Topology.
§
type:
Values for relationship type are not defined by the SDD specification.
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.
Figure 44: ConditionType
structure.
ConditionType
allows expression of the particular resource characteristics that must be true
for the condition to be considered met. These are resource characteristics that
may vary from one particular deployment to another.
For example, one deployment using the SDD
might use one version of an application server and a different deployment might
use a different version. The differences in the version might be great enough
to:
·
select among content elements.
For example, one content element has an
artifact for a Web application that works in a particular version and a
different content element has an artifact for a later version of the same Web
application.
·
select among variable values.
For example, the default installation path
on one operating system may be different from the default install path on
another operating system.
·
select among completion actions.
For example, a reboot may be required when
deploying on one operating system but not another.
4.5.1.1 ConditionType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
DisplayName
|
DisplayTextType
|
0..1
|
Name
of the condition.
|
|
Description
|
DisplayTextType
|
0..1
|
Description
of the condition.
|
|
ShortDescription
|
DisplayTextType
|
0..1
|
Short
description of the condition.
|
|
Alternative
|
AlternativeConditionalType
|
0..*
|
An
alternative set of resource constraints.
|
|
ResourceConstraint
|
ConditionalResourceConstraintType
|
0..*
|
A
set of constraints on one resource.
|
|
|
xsd:any
|
0..*
|
|
|
operation
|
OperationListType
|
0..1
|
The
condition applies only when processing the artifact associated with this
operation.
|
|
|
xsd:anyAttribute
|
0..*
|
|
4.5.1.2 ConditionType
Property Usage Notes
§
DisplayName:
This element MAY be
used to provide human-understandable information. If used, it MUST provide
a label for the condition.
See the DisplayElementGroup
section for structure and additional usage details [4.14.2].
§
Description,
ShortDescription: These elements MAY be
used to provide human-understandable information. If used, they MUST provide
a description of the condition.
The
Description element MUST be defined
if the ShortDescription element is
defined.
See
the DisplayElementGroup section for
structure and additional usage details [4.14.2].
§
Alternative:
When a condition can be satisfied in multiple ways, two or more Alternative elements are defined.
As a convenience for tooling that produces
SDDs, it is also possible to define a single Alternative. This is semantically identical to directly defining ResourceConstraints.
To meet a condition, at least one of the
specified Alternatives must be
satisfied.
See the AlternativeConditionalType
section for structure and additional usage details [4.5.2].
§
ResourceConstraint:
When a condition can be satisfied in only one way, constraints MAY be defined
directly under Condition or in a
single Alternative element.
Constraints are defined using a sequence of ResourceConstraints. Every constraint in
the sequence must be met for the condition to be met.
See
the ConditionalResourceConstraintType
section for structure and additional usage details [4.5.3].
§
operation:
In a singleton atomic content element, a condition MAY be associated with
application of one or more artifacts. The association is made by setting the operation attribute to the operations
associated with those artifacts.
Conditions
defined for CompositeInstallable and
for atomic content elements defined within a CompositeInstallable SHOULD NOT define operation. If the operation
is defined for a CompositeInstallable
Condition, it MUST be set to the operation defined in the CompositeInstallable’s operation attribute. If operation is defined for an atomic
content element’s Condition, it MUST
be set to the operation associated with the single artifact defined by the
atomic content element.
When operation
is not specified, the condition applies to the processing of all artifacts.
See the OperationListType
section for operation enumerations
and their meaning [4.3.6].
Figure 45:
AlternativeConditionalType structure.
When a condition can be met in more than one
way, alternative sets of conditional resource constraints can be defined. AlternativeConditionalType provides the
type definition for these elements.
4.5.2.1 AlternativeConditionalType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
DisplayName
|
DisplayTextType
|
0..1
|
Name
of the alternative.
|
|
Description
|
DisplayTextType
|
0..1
|
Description
for the alternative.
|
|
ShortDescription
|
DisplayTextType
|
0..1
|
Short
description of the alternative.
|
|
ResourceConstraint
|
ConditionalResourceConstraintType
|
1..*
|
A set of constraints on one resource.
|
|
|
xsd:any
|
0..*
|
|
|
id
|
xsd:IDREF
|
1
|
Identifier
for the alternative that is unique within the deployment descriptor.
|
|
|
xsd:anyAttribute
|
0..*
|
|
4.5.2.2 AlternativeConditionalType
Property Usage Notes
§
DisplayName:
This element MAY be
used to provide human-understandable information. If used, it MUST provide
a label for the alternative condition.
See the DisplayElementGroup
section for structure and additional usage details [4.14.2].
§
Description,
ShortDescription: These elements MAY be
used to provide human-understandable information. If used, they MUST provide
a description of the alternative condition.
The
Description element MUST be defined
if the ShortDescription element is
defined.
See
the DisplayElementGroup section for
structure and additional usage details [4.14.2].
§
ResourceConstraint:
All constraints defined in the individual Alternative
MUST be met for the Alternative
condition to evaluate to true.
See the ConditionalResourceConstraintType
section for structure and additional usage details [4.5.3].
§
id:
The id attribute may be useful to
software that processes the SDD, for example, for use in creating log and trace
messages.
Figure 46:
ConditionalResourceConstraintType structure.
ConditionalResourceConstraintType
provides the type definitions for the ResourceConstraint
elements used in conditions. These constraints do not represent requirements
for deployment. They identify the resource characteristics associated with a
condition. Name, version, property and the existence or absence of the resource
can be specified with a resource constraint used in a condition.
4.5.3.1 ConditionalResourceConstraintType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
DisplayName
|
DisplayTextType
|
0..1
|
Name
of the resource constraint.
|
|
Description
|
DisplayTextType
|
0..1
|
Description
for the resource constraint.
|
|
ShortDescription
|
DisplayTextType
|
0..1
|
Short
description of the resource constraint.
|
|
Name
|
VariableExpressionType
|
0..1
|
Name
of the resource constraint.
|
|
VersionConstraint
|
VersionConstraintValueType
|
0..1
|
A
resource version set.
|
|
PropertyConstraint
|
ConditionalPropertyConstraintType
|
0..*
|
A
resource property name and required value.
|
|
UniquenessConstraint
|
UniquenessConstraintType
|
0..*
|
A required mapping of two resources in the
topology to unique instances in the deployment environment.
|
|
RelationshipConstraint
|
RelationshipConstraintType
|
0..*
|
A
required relationship between the resource identified in the resourceRef and
another resource in the topology.
|
|
|
xsd:any
|
0..*
|
|
|
id
|
xsd:ID
|
1
|
Identifier
for the resource constraint that is unique within the deployment descriptor.
|
|
resourceRef
|
xsd:IDREF
|
1
|
The
resource to which the conditions apply.
|
|
testValue
|
xsd:boolean
|
0..1
|
The
result of evaluating the contained constraints, which will result in the ResourceConstraint
being met.
**default
value=“true”
|
|
|
xsd:anyAttribute
|
0..*
|
|
4.5.3.2 ConditionalResourceConstraintType
Property Usage Notes
§
DisplayName:
This element MAY be
used to provide human-understandable information. If used, it MUST provide
a label for the resource constraint.
See the DisplayElementGroup
section for structure and additional usage details [4.14.2].
§
Description,
ShortDescription: These elements MAY be
used to provide human-understandable information. If used, they MUST provide
a description of the resource constraint.
The
Description element MUST be defined
if the ShortDescription element is
defined.
See
the DisplayElementGroup section for
structure and additional usage details [4.14.2].
§
Name:
The name of the resource identified by resourceRef.
If the resource name is defined in topology it SHOULD NOT be defined here. If
it is defined in both places, the one defined in the condition is used when
evaluating the condition.
See the VariableExpressionType
section for structure and additional usage details [4.6.1].
§
VersionConstraint:
The actual version of the resource MUST be one of the set of versions defined
here for the version condition to be considered met.
See the VersionConstraintValueType
section for structure and additional usage details [4.4.8].
§
PropertyConstraint:
The actual value of the property MUST match the value defined here for the
condition to be considered met.
See the ConditionalPropertyConstraintType
section for structure and additional usage details [4.5.4].
§
UniquenessConstraint:
UniquenessConstraint elements are
used in ResourceConstraints to indicate
when two resources defined in topology MUST or MUST NOT resolve to the same
resource instance during a particular deployment.
See the UniquenessConstraintType
section for structure and additional usage details [4.4.12].
§
RelationshipConstraint:
RelationshipConstraint elements are
used in ResourceConstraints to indicate
a constraint on a particular relationship between resources.
See the RelationshipConstraintType
section for structure and additional usage details [4.4.13].
§
id:
The id attribute may be useful to
software that processes the SDD, for example, for use in creating log and trace
messages.
§
resourceRef:
The version and property constraints defined here all apply to the one resource
specification in topology identified by this attribute.
The
value MUST reference the id of that
resource element in Topology.
§
testValue:
When the result of evaluating Name
and all of the constraints defined in the ResourceConstraint
matches the value of testValue, the ResourceConstraint is considered met.
When
no name, version or property constraints are defined, and testValue is “true”, the constraint is met if the resource exists
as defined in topology.
When
no name, version or property constraints are defined, and testValue is “false”, the constraint is met if the resource, as
defined in topology, does not exist.
Figure 47:
ConditionalPropertyConstraintType structure.
ConditionalPropertyConstraintType
provides the type definition for a PropertyConstraint
included within Alternatives specified
in Condition elements. The ConditionalPropertyConstraintType is
very similar to the PropertyConstraintType;
the only difference is that the Value
element defined in the ConditionalPropertyConstraintType
is of type xsd:string which is less restrictive than the Value element defined in the PropertyConstraintType which is of VariableExpressionType.
4.5.4.1 ConditionalPropertyConstraintType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
Description
|
DisplayTextType
|
0..1
|
A
description of the property constraint. Required if ShortDescription is
defined.
|
|
ShortDescription
|
DisplayTextType
|
0..1
|
A
short description of the property constraint.
|
|
PropertyName
|
xsd:QName
|
1
|
Name
of the constrained property.
|
|
Value
|
xsd:string
|
0..1
|
Required
property value.
|
|
ListOfValues
|
PropertyValueListType
|
0..1
|
List
of required property values.
|
4.5.4.2 ConditionalPropertyConstraintType
Property Usage Notes
§
Description,
ShortDescription: These elements MAY be
used to provide human-understandable information. If used, they MUST provide
a description of the PropertyConstraint
element.
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].
§
PropertyName:
The property name can be used to find the property value in the deployment
environment. The name may be defined in a profile [5.3].
§
Value:
In a condition, the value used in a property constraint is a string rather than
a variable expression.
§
ListOfValues:
A list of required values can be defined in place of a single required value.
See
the PropertyValueListType section for
structure and additional usage details [4.4.6].
Variables provide a means to associate user
inputs, resource property values, fixed strings and values derived from these
with input arguments for artifacts and with constraints on resources.
Figure 48:
VariableExpressionType structure.
Variable expressions are used in many places
in the SDD. They allow the value of a variable to be used as all, or part of, the
value of some other SDD element. A variable expression is a string that can
include a reference to a variable. The string is evaluated by replacing all
references to variables with the value of the variable. A variable reference is
a variable id placed inside parentheses preceded by a dollar sign.
For example, the variable expression
“C:\Program Files\$(InstallDirectory)” resolves to “C:\Program Files\Acme
Software Product” if the value of the variable with the id “InstallDirectory”
has the value “Acme Software Product”.
The value of a variable that is replaced
into a variable expression can itself have a variable reference. This reference
is resolved before using the value. This nesting of variable expressions is
unlimited. Any number of variable references can be used in a variable
expression. If a variable expression string does not contain a variable
reference, it is used as is.
A variable is considered defined if it has a
value provided, even if that value is the empty string. A variable expression
is considered valid if it contains no variable references, or if all contained
variable references are defined.
Specifically, a ResourceProperty
variable is undefined when the resource does not participate in the particular
deployment or when the specified property has no value. A Parameter
variable is undefined when it has no default value and has no value provided by
the deployer. A DerivedVariable that uses ConditionalExpression
elements is undefined when none of its conditions evaluates to true, or the
selected condition's value expression is not valid. A DerivedVariable
that uses an unconditioned Expression is undefined when its value expression
is undefined.
To avoid an undefined Parameter
variable, default parameter values may be used. To avoid an undefined ResourceProperty
variable, replace references to the ResourceProperty variable with
references to a DerivedVariable defined to provide a default value in
cases where the ResourceProperty is undefined. This DerivedVariable
would define one expression, conditioned on the resource, that refers to the ResourceProperty
variable and another, low priority, catch-all expression that defines the
desired “default” value. Note that the
default value in either of these cases MAY be an empty string, for example, “”. An empty string acts just like
any other defined variable value. When the provided value of a variable is an
empty string, the variable reference in a variable expression is replaced by an
empty string.
Figure 49: BaseVariableType
structure.
BaseVariableType
is the base type of the DerivedVariable
and ResourceProperty elements defined
by VariablesType [4.6.3]. It provides the id
attribute, which is used to reference the variable in a variable expression.
4.6.2.1 BaseVariableType
Property Summary
|
Name
|
Type
|
*
|
Description
|
|
Description
|
DisplayTextType
|
0..1
|
Description
of the variable.
|
|
ShortDescription
|
DisplayTextType
|
0..1
|
Short
description of the variable.
|
|
id
|
xsd:ID
|
1
|
Identifier
used for referencing the variable within the descriptor. |
