test

N1 Grid Service Provisioning System 5.0 XML Schema Reference Guide

Chapter 1 XML Schema Overview

This chapter provides an overview of the XML schemas and describes general information that you need to know before you work with them in detail.

The following topics are covered in this chapter:

Note –

In this book, the terms “derived component,” “child component,” and “parent component” refer to component inheritance relationships, not component composition relationships.

Service Provisioning Languages and Schemas

The N1 Grid Service Provisioning System software implements plans, components, and plug-in definitions through XML. Each piece of the provisioning software environment has a specific XML schema. Each XML schema defines a specific set of elements that you use to define the appropriate part of the provisioning software environment.

The N1 Grid Service Provisioning System software includes five XML schemas, which are grouped into two languages:

Each schema is described in detail in the referenced chapter of this book. General information that relates to all of the schemas is contained in the remainder of this chapter.

Requirements for Locales and Character Sets

Plans and components can include multibyte data. If a plan or component is authored in XML, the input files must be in UTF-8 format or use a byte order mark at the start of the file to signify their Unicode encoding. When plans and components are downloaded, they are always written in UTF-8 format. If a simple component refers to a configurable resource, that resource should be encoded in the native encoding of the master server or should use a byte order mark to note its encoding.

Pattern Matching

A number of element attributes can contain regular expression patterns. Unless otherwise specified, these patterns are glob-style patterns rather than fully generic regular expressions. Thus, an asterisk (*) is used to match zero or more characters, and a question mark (?) is used to match exactly one character. Characters listed inside of square brackets ([]) match any one of the enclosed characters. Characters that are separated by a hyphen (-) match any character that is lexically between the range of characters and includes the characters specified.

For example, [ab] matches either a or b. [a-z] matches any lowercase character. In this case, only the strict ASCII characters are matched, but not extended variants of the characters such as those with accents.

To match all Unicode letters, the pattern would have to include a POSIX character class like the Perl 5 regex [[:lower]]. You can also include non-ASCII characters directly, for example, [eé] matches either e or é.

Variables and Parameter Passing

Both plans and components can declare variables that are used by their steps.

Component variables are evaluated and bound at the time the component is installed. Thus, if a step in a component control block refers to a component-scoped variable, the value used is the same as when the component was installed.

Plan variables, however, are evaluated and bound each time the plan is run. If a step in a plan refers to a plan variable, the value used is the value defined at the time the plan was run. Thus, the value might vary from one run to another.

A plan can declare both parameters and variables. The value of a variable is defined at the point of declaration based on the values of other variables and constants. A parameter is a special kind of variable whose value is defined by the caller. In the case of a top-level plan, the caller is the user who initiates the plan run. For each parameter that is declared by the plan, the user specifies the value for that parameter before running the plan. When a plan is invoked as the result of an <execSubplan> call, the plan that contains the call must explicitly pass values for each parameter that is declared by the called plan.

The <install>, <uninstall>, <snapshot>, and <control> blocks can declare parameters and local variables. As with plans, local variable values are locally defined, while parameter values are defined based on the values passed by the caller of the block. Both types of values can vary each time a plan is run.

You cannot reassign the value of a variable or parameter.

Component Compatibility

Compatibility is a concern when you create new versions of a component that has already been deployed. When you create a new version of a component, you must ensure that the other objects that use or refer to the component are not broken as a result of the changes. You can use and refer to components by using dependencies, component containment, inheritance, and component targeters.

The provisioning software supports the following types of component compatibility:

Because different versions of components can be deployed to different parts of the data center at different points in time, you should be aware of compatibility requirements and understand the way that changes to one component might affect other existing components. In certain cases, the system will enforce compatibility requirements, in other places you must ensure that the new component is compatible.

For a list of the types of changes that can be made to a component, see Appendix A, Component Change Compatibility.

Call Compatibility

A component is call compatible with another component if uses of the first component can be safely replaced with uses of the other in these cases:

Call compatibility is the same as API compatibility or interface compatiblity.

Note –

Usually, two call-compatible components are different versions of a component that are in the same version tree. However, the second component can also be in a distinct version tree if it is an instance of the first component.

The provisioning software enforces call compatibility for components that provide system services. When a system service is updated to refer to a new component, the new component must be call compatible with the original component. This policy ensures that clients of the system service can continue to function properly when the system service is upgraded.

The provisioning software also optionally verifies call compatibility when it resolves components that are referenced by certain installed component targeters. See Installed Component Targeters.

Though not required, try to make a component call compatible with earlier versions of itself.

Install Compatibility

A component can be install compatible with another component. The first component must be call compatible with the other component. Uses of the other component must also be able to be replaced safely with uses of the first component in these cases:

Install compatibility is the same as structural compatibility.

The constraints imposed by install compatibility mean that any existing installed component can be safely replaced by another install-compatible component. You do not have to modify the data structures that describe how the original was installed. Call compatibility is a much weaker statement, because the call-compatible component might need to be reinstalled to properly update the data structures.

Note –

For install compatibility to hold, both components must belong to the same version tree. They cannot be components from two distinct version trees.

The provisioning software only enforces install compatibility for components that serve as types, which are called component types. When a component type is updated to refer to a new version of a component, the new version is install compatible with the original version. Thus, you can make install-compatible updates to component types without rebuilding and reinstalling all of the existing components that have been derived from that type. A change made to a component type that is not install compatible must be encoded as a new, distinct component version tree with its own type name. In such cases, the new component type can maintain call compatibility with the original by extending from the original component type. To easily identify the relationship between types, use a versioning system to encode component type names. For example, the component names EJB-1.0 and EJB-1.1 are an easy way to indicate that EJB-1.1 is a later version of the EJB-1.0 component type.

Install compatible implies call compatible, but the reverse is not true. Also, if components are not call compatible, they are not install compatible.

Targetable Components

The presence of a <targetRef> element indicates that the component, once installed, can be used as a deployment target for other components. This targetability is achieved by associating a unique virtual host or physical host with each installed instance of the component.

By using targetable components, plans can logically target an installed component by targeting its associated host. Usually, a targetable component creates a virtual host. However, you can have the targetable component create a physical host, as well. A physical host is useful for models in which the associated host has its own remote agent. Such is the case for a component that models a SolarisTM Zone.

A component that defines a <targetRef> element is a targetable component. When a targetable component is installed, it creates a host that serves as a deployment target for other components. When a targetable component is uninstalled, the host it created is automatically deleted. Such hosts still appear in the list of hosts on the Hosts page, but cannot be deleted and are restricted in the types of edits that can be made to them.

Common Attribute Types

An attribute type serves as a constraint on the value of a plan or component attribute. If an attribute does not list a specific type, its value is unconstrained.

The following sections describe the format of the attribute types that are used by the schema. \p{N} represents all Unicode numbers, while \p{L} represents all Unicode letters.

entityName Attribute Type

Attributes of type entityName have a maximum length of 512 characters and match the following pattern:


[\p{N}\p{L}-_. ]+

As a special case, dot (.) and dot-dot (..) are not permitted to be entity names.

systemName Attribute Type

Attributes of type systemName consist of a simpleSystemName that has a maximum length of 64 characters, and optionally, a pluginName that also has a maximum length of 64 characters, as follows:


simpleSystemName
pluginName#
simpleSystemName

where simpleSystemName matches the following pattern:


[\p{L}_][\p{N}\p{L}-_. +]*

identifier Attribute Type

Attributes of type identifier have a maximum length of 32 characters and match the following pattern:


[\p{L}_][\p{N}\p{L}_]*

pathName Attribute Type

Attributes of type pathName have a maximum length of 512 characters and match one of the following patterns:


"/"
( "/" pathPart )+

where pathPart is [\p{N}\p{L}-_. ]+.

As a special case, dot (.) and dot-dot (..) are not permitted to be included in pathPart.

pathReference Attribute Type

Attributes of type pathReference have the following syntax:


pathReference:
    absolutePath
    relativePath

absolutePath:
    "/"
    "/" relativePath

relativePath:
    relativePathStart
    relativePathStart "/" relativePath

relativePathStart:
    "."
    ".."
    identifier

modifierEnum Attribute Type

Attributes of type modifierEnum have either ABSTRACT or FINAL as their value. In general, a value of ABSTRACT indicates that the associated entity must be overridden by a derived component. A value of FINAL indicates that the associated entity cannot be overridden.

accessEnum Attribute Type

Attributes of type accessEnum have one of these values:

version Attribute Type

Attributes of type version match the following pattern:


[0-9]+\.[0-9]+

schemaVersion Attribute Type

Attributes of type schemaVersion can have only one value, 5.0.