Chapter 5 Resource Descriptor Schema

This chapter describes the XML schema for the resource descriptor files, and covers these topics:

• Using a Resource Descriptor File

• <resourceDescriptor> Element Overview

• <entryList> Element

• Sample XML for the <resourceDescriptor> Element

Using a Resource Descriptor File

A resource descriptor file specifies the owner, group, and permission settings to use for the files and directories that comprise the resource of a simple component. This resource descriptor is an XML file. By using a resource descriptor file, you can override the permissions that are determined at component check-in time.

When a resource descriptor file is not used, a resource uses the owner, group, and permission settings it has at check-in time. This situation is the default case when you perform the check-in on a UNIX system. When you check in a component on a Windows system, the default settings are as if you used the :NONE: value for each of the settings in a resource descriptor file.

When you use a resource descriptor file, a resource uses the owner, group, and permission settings specified by the resource descriptor. If an <entry> element is specified for a resource, the settings are taken from that entry. If the entry does not specify all of the settings, the missing setting values are taken from the <defaultEntry>, if present. If those setting values are not specified in a <defaultEntry>, the resource uses the setting values it had at check-in time.

If no <entry> element is specified for a resource, the resource uses the settings specified in <defaultEntry>, if present. If no <defaultEntry> is present, the resource uses the settings it had at check-in time.

Use the :NONE: value to tell N1 SPS to use the default settings from the file system on which the component will be deployed. You can specify the :NONE: value for any setting specified in a <defaultEntry> block or in an <entry> for a resource.

A resource descriptor file is only used when deploying a component to a UNIX system. If a component is deployed to a Windows system, the resource descriptor file is ignored. So, if your component only applies to Windows systems, do not create a resource descriptor file.

A resource descriptor file can be used by simple components that extend the system#file and system#directory component types. A resource descriptor file can also be used by a component that extends the com.sun.linux#rpm component type, which is part of the Linux plug-in.

You check in the resource descriptor file at the same time that you check in your component. When you attempt a checkin-current for a component that used a resource descriptor file for its last checkin, N1 SPS expects to find the resource descriptor in the original check-in location. Thus, if you move the file to a different location and attempt a checkin-current for the component, the check-in operation fails.

You can download the resource descriptor for a simple component that has been checked in to see the settings for every file that is part of the component's resource.

You might use this download feature to update the file and check in an updated version of the component. First, you download the resource descriptor file and then check out the associated component's resource. Then, you modify the resource descriptor file and use it to check in a new version of the component.

The resource descriptor you download might differ from the resource descriptor you used to check in the component. Differences might appear because the descriptor you use to check in a component is not required to have information about every file in the resource, or to have full information for every entry. Notice that no <defaultEntry> block appears in the downloaded resource descriptor file. Instead, every file is described in its own <entry>.

<resourceDescriptor> Element Overview

An entire resource descriptor is enclosed by the <resourceDescriptor> element.

The resource descriptor file is encoded in UTF-8 format unless a byte order mark (BOM) is present. If present, the BOM is used to determine the encoding of the file.

Attributes for the <resourceDescriptor> Element

The <resourceDescriptor> element has the following attributes:

• xmlns – A required string that has the following value:

  http://www.sun.com/schema/SPS

• xmlns:xsi – A required string that has the following value:

  http://www.w3.org/2001/XMLSchema-instance

• xsi:schemaLocation – An optional string that has the following recommended value:

  http://www.sun.com/schema/SPS resourceDescriptor.xsd

• schemaVersion – A required attribute of type schemaVersion, which is the version of the resource descriptor schema that is being used. The only permitted values are 5.0 and 5.1.

Child Elements of the <resourceDescriptor> Element

The <resourceDescriptor> element has one required child element, <entryList>, which is the list of files and directories contained by this resource. The entry for each file or directory includes the associated owner, group, and permission settings.

<entryList> Element

The <entryList> element is a required child of the <resourceDescriptor> element. This element is used to list the files and directories included in this resource and describes the settings that are associated with the files and directories.

The <entryList> element has two optional child elements that, if present, must appear in this order:

• <defaultEntry>

• <entry>

If specified, the <defaultEntry> element can only appear one time. The <entry> element describes the settings for a single file or directory. Thus, you can specify more than one <entry> element in the resource descriptor file.

<defaultEntry> Element

The <defaultEntry> element is an optional child of the <entryList> element. This element specifies the default owner, group, and permission settings for resource files that are not listed in <entry> elements in the resource descriptor file.

If this element is omitted, the file and directories listed in this <entryList> block use the setting values determined at check-in time. If specified, this element can only appear one time.

<settings> Element

The <settings> element is a required child element of the <defaultEntry> element and of the <entry> element.

The <settings> element behaves differently when used as a child of these elements:

• <defaultEntry> element – Specifies the setting values to be used as defaults for any file that is not associated with its own <entry> element

• <entry> element – Specifies the setting values to be used by the file associated with this <entry> element

  If any attributes are omitted, the corresponding attribute value in the <defaultEntry> element for this <entryList> is used. If no <defaultEntry> element is specified, the check-in time settings are used.

Attributes for the <settings> Element

The <settings> element has these optional attributes:

• group – An optional string that is the group of this entry. The group must be a group name, not a group ID.

• owner – An optional string that is the owner of this entry. The owner must be a user name, not a user ID.

• permissions – An optional string that is the permissions settings for a file or directory. The string is in the format of an octal triplet, as defined by the UNIX chmod command. See the chmod(1M) man page.

You can specify a value of :NONE: for any of these attributes. Use the :NONE: value to tell N1 SPS to use the default settings from the file system on which the component will be deployed.

<entry> Element

The <entry> element is an optional child element of the <entryList> element. This element specifies the owner, group, and permission settings for one entry in the resource. The <entry> element has one required element, <settings>. See <settings> Element.

Files and directories that do not appear as <entry> elements in the <entryList> block use the following:

• Setting values specified in the <defaultEntry> block

• Setting values determined at check-in time

Attributes for the <entry> Element

The <entry> element has one required attribute, name. The name value is a string that defines the name of this entry, relative to the root of the resource. The name of the top-level resource should always be root.

For example, if the resource created a directory hierarchy starting with topDir, the name attribute for the top level directory is root. The name attribute for a nested directory subDir would be root/subDir. For a file resource named file.txt, the name attribute would be root.

Trailing slash (/) characters are not permitted.

See Sample XML for the <resourceDescriptor> Element.

Sample XML for the <resourceDescriptor> Element

The following example shows an <resourceDescriptor> element for a directory resource.

<?xml version ="1.0" encoding="UTF-8"?>
<resourceDescriptor
      xmlns="http://www.sun.com/schema/SPS"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.sun.com/schema/SPS 	           
 	                    resourceDescriptor.xsd"
      schemaVersion="5.1">
  <entryList>
    <defaultEntry>
      <settings
        owner="root"
        group="wheel"
        permissions="664"/>
    </defaultEntry>

    <!-- This directory overrides all of the default settings -->
    <entry
         name="root">
      <settings
        owner="gprabhu"
        group="bin"
        permissions="777"/>
    </entry>

   <!-- This directory overrides the owner and group, but will have   
	   perms of "664" from the defaultEntry -->
    <entry
        name="root/nestedDirectory" >
      <settings
        owner="gprabhu"
        group="wheel"/>
    </entry>

    <!-- This file overrides the group and perms, but will have owner 
     of "root" from the defaultEntry -->
    <entry
         name="root/nestedDirectory/fileThatWillUseSomeDefaults.txt" >
      <settings
        group="bin"
        permissions="777"/>
    </entry>

    <!-- This file overrides none of the settings in the defaultEntry,
 	   so it will inherit all of them.
         In practice, this entry would probably be omitted entirely. -->
    <entry
         name="root/nesteddirectory/fileThatWillUseAllDefaults.txt" >
      <settings/>
    </entry>
  </entryList>
</resourceDescriptor>

The following example shows an <resourceDescriptor> element for a file resource.

<?xml version ="1.0" encoding="UTF-8"?>
<resourceDescriptor xmlns="http://www.sun.com/schema/SPS"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.sun.com/schema/SPS resourceDescriptor.xsd"
 schemaVersion="5.1">
  <entryList>
    <!-- There is no <defaultEntry> in this <entryList>, so anything not
         specified in the <settings> element for this entry uses the
         settings determined at check-in time. -->
    <entry name="root">
      <settings owner="terry" group="bin" permissions="777"/>
    </entry>
  </entryList>
</resourceDescriptor>