Chapter 1 XML Schema Overview

This chapter provides an overview of the XML schemas that are used by the Sun N1 Service Provisioning System (N1 SPS).

The following topics are covered in this chapter:

• Service Provisioning Languages and Schemas

• Requirements for Locales and Character Sets

• Pattern Matching

• Variables and Parameter Passing

• Component Compatibility

• Targetable Components

• Common Attribute Types

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

Service Provisioning Languages and Schemas

The N1 SPS software uses XML to implement plans, components, resource descriptors, and plug-in definitions. Each of these N1 SPS constructs use a specific kind of XML schema.

The N1 SPS product includes these XML schemas:

• component.xsd – Schema used to define components and component types. See Chapter 3, Component Schema.

• plan.xsd – Schema used to define execution plans. See Chapter 4, Plan Schema.

• planCompShared.xsd – Schema that contains elements common to plans and components. See Chapter 2, Shared Schema Used by Components and Simple Plans.

• resourceDescriptor.xsd – Schema used to define resource descriptors. See Chapter 5, Resource Descriptor Schema.

• plugin.xsd – Schema used to define a plug-in in a plug-in descriptor file. See Chapter 6, Plug-In Descriptor Schema.

• .pluginUI.xsd – Schema used to define a user interface to a plug-in in the N1 SPS browser interface. See Chapter 7, Plug-In User Interface Schema.

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 when 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 modify or create new versions of a component that has already been deployed. Each time you modify a component and check it in, you create a new version of that component. When you modify a component, you must ensure that other objects that use or reference that component are not broken as a result of the changes. The ways in which you can use or reference components are by using dependencies, component targeters, component containment, and inheritance.

The N1 SPS product supports the following types of component compatibility:

• Call compatibility describes the set of changes that you can make to a component and still ensure that relationships that exist through dependencies and component targeters are not violated.

• Install compatibility describes the set of changes that you can make to a component and still ensure that relationships that exist through inheritance and component containment relationships are not violated.

Different versions of components can be deployed to different parts of the data center at different points in time. Thus, you should be aware of compatibility requirements and understand the way in which changes to one component might affect other existing components. In certain cases, the N1 SPS product enforces compatibility requirements, while in other cases 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:

• When making a call to a <control>, <uninstall>, or <snapshot> block of the first component

• When checking for dependencies of the first component by using <checkDependency> or <createDependency>

• When referring to a variable of the first component, by using configuration generation :[component:AB:var]

Call compatibility is also known as API compatibility or interface compatiblity.

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 N1 SPS product 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 N1 SPS product also optionally verifies call compatibility when it resolves components that are referenced by certain installed component targeters. See Installed Component Targeters.

Though not required, ensure that a component is 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:

• When making a call to an install block of the other component

• When a component extends from the other component

• When a component contains a reference to the other component

Install compatibility is also known as structural compatibility.

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.

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

The N1 SPS product 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.

If you make a change to a component type that is not install compatible, you must create a new component type in a new version tree with a new 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 a component is not call compatible, it cannot be 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 Solaris^TM Zone.

A component that defines a <targetRef> element is called 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 512 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}-_. ]+.

You can use the / separator to string together pathParts, such as /pathPart/pathPart/pathPart.

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:
    .
    ..
    pathPart

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:

• PUBLIC – Indicates that the associated entity can be accessed by any object

• PROTECTED – Indicates that the associated entity can be accessed by derived components and other entities that are in the same path

• PATH – Indicates that the associated entity can be accessed by other entities that are in the same path

• PRIVATE – Indicates that the associated entity can be accessed by the declaring component

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 of these values, 5.0 or 5.1.

HostEntityName Attribute Type

Attributes of type HostEntityName have a maximum length of 64, and can include any combination of Unicode letters and numbers.

pluginName Attribute Type

Attributes of type pluginName have a maximum length of 64, and can include any combination of Unicode letters and numbers.

pluginHostEntityName Attribute Type

Attributes of type pluginHostEntityName have a maximum length of 64, and can include any combination of Unicode letters and numbers.