<id>http://www.phpbb.com/</id>

URI-formed unique application identifier. This string should be used as a application identifier - it MUST NOT be changed in consequent versions of packages, otherwise package upgrade and patch from older versions will be not feasible. This URI may or may not lead to any valid page.

<name>phpbb</name>

Free-formed string specifies user-visible name of application in a package. Package name may be changed during upgrade and should reflect packaged software name.

<version>2.0.22</version>
<release>6</release>

Package version consists of two parts: application version and package release, the former corresponds to the version of application packaged, and the later to the release of the package containing the same version of application (packages may be released many times, e.g., for fixing bugs in packaging or adding localizations).

Version format and the algorithm for determining the chronological relationship between different package versions are specified by the Debian Policy: Version Format in Debian Policy.

Unlike the Debian version-release approach, application version and package release are separated to ease parsing.

<homepage>http://phpbb.com/</homepage>

URL of the application official site.

<master-package>
  <package id="http://www.phpbb.com" match="version = 1.1"/>
</master-package>

If a package is an add-on package for another APS application this definition provides a reference to master package by ID and version/release conditions. Optional condition is provided by match XPath expression. Virtual nodes version and release in the context of expression represent version and release of master package.

Before installation controller MUST check availability of referrenced APS package in given context. Add-on packages will get an access to global settings of master package with value-of-setting attribute.

Add-on package services may inherit master package serviceses hierarchy by defining services structure with same IDs. Add-on package may not change master package services, but may define sub-services of master package services. In this case add-on packages man refer master package service settings with value-of-setting.

Add-on package may request environment variables provided by master package requirements by defining requirement with same ID as a requirement of master package in context of service.

Add-on package may request environment variables provided by master package URL mappings by defining same URL mappings as in master package. Add-on package may define its own URL mappings as usual.

<vendor>
  <name>Broombla Corporation</name>
  <homepage>http://broombla.com</homepage>
  <homepage xml:lang="ja-JA">http://broombla.com/ja</homepage>
  <icon path="icons/broombla-corp-logo.gif"/>
</vendor>

Characteristics of software vendor whose application is packaged. Both the name and homepage allow localization. The icon/@path attribute MUST contain a full path in archive to the icon file. The icon SHOULD be a 64x64 pixel image in PNG format using alpha transparency. JPEG and GIF formats MAY be used as well, but their use is discouraged.

<packager>
  <name>Parallels</name>
  <homepage>http://parallels.com</homepage>
  <icon path="icons/parallels-package-logo.gif"/>
  <uri>uuid:15d041e8-34c6-409a-b165-3290d2c9d599</uri>
</packager>

Characteristics of package manufacturer. Both the name and the homepage elements allow localization. The icon/@path attribute MUST contain a full path in archive to the icon file. The icon must be a 64x64 pixels image in JPEG, PNG or GIF format.

The uri element is an arbitrary URI unique for each packager (it is RECOMMENDED to use uuid: URI scheme to minimize the possibility of clash). This URI is needed to distinguish packages with the same name but created by different packagers. Note that consequent versions of the same package MUST have the same URI, as otherwise package Controllers MAY refuse to update package from one version to another.

Controllers SHOULD allow to upgrade and patch package from the version which does not specify uri to the one which specifies in order to support smooth upgrade path for the packages which did not use uri from the beginning.

<presentation>
  <summary>
    High powered, fully scalable, and highly customizable Open Source bulletin
    board package.
  </summary>
  <summary xml:lang="es-ES">...</summary>
  ...
</presentation>

Single-sentence summary of the package for end users.

<description>
  phpBB is a high powered, fully scalable, and highly customizable
  Open Source bulletin board package. phpBB has a user-friendly
  interface, simple and straightforward administration panel, and
  helpful FAQ. phpBB is the ideal free community solution for all web
  sites.
</description>
<description xml:lang="it-IT">...</description>

One-paragraph description of the package for end users.

<icon path="images/phpbb.png" />

Icon may be provided to be displayed in GUI for the application. The path attribute MUST contain a full path in archive to the icon file. The icon SHOULD be a 64x64 pixel image in PNG format using alpha transparency. JPEG and GIF formats MAY be used as well, but their use is discouraged.

<screenshot path="images/admin.png">
  <description>Administrative interface</description>
  <description xml:lang="he-IL">...</description>
</screenshot>
<screenshot path="images/main.png">
  <description>Main page</description>
  <description xml:lang="ja-JA">...</description>
</screenshot>

Several screenshots with descriptions may be provided. The path attribute MUST contain a full path in archive to the screenshot file. It must be JPEG, PNG or GIF image.

<changelog>
  <version version="2.1.22" release="1">
    <entry>New upstream version</entry>
    <entry xml:lang="de-DE">...</entry>
  </version>
  <version version="2.1.21" release="5">
    ...
  </version>
  ...
</changelog>

Changelog contains the human-readable list of changes between consecutive package versions. Order of entries in changelog is not specified, Controller should sort them.

<categories>
  <category>Collaboration/Portals</category>
  <category>Web/Content management</category>
</categories>

Package may include a set of categories. Category is a Unicode string without attached semantics. The first category should be "primary category" in the sense the first category should be adequate for sorting packages in the user interface.

A list of predefined categories is available at [APS Categories]. The specified categories names SHOULD be used. Other categories names MAY be used, but handling them in Controller is OPTIONAL.

<languages>
  <language>en</language>
  <language>de</language>
  <language>ru</language>
</languages>

Package may declare a set of languages for the presentation purposes. The first language is the "default language" of the application. Languages are identifiers from ISO 639.

Application may declare versions of packages which can be updated to the current package. Two update strategies are supported:

A Package may specify which versions it can update with help of match attribute. This attribute contains XPath expression that will be evaluated against metadata of the installed packages with the same id (or name/packager pair for older packages) and lower version/release numbers. If specified XPath expression results in non-empty nodeset on some examined application metadata - the package is considered to be an update for the examined application.

The XPath expression must assume http://apstandard.com/ns/1 to be the default namespace.

Attribute mode defines how upgrade procedure will proceed. Following options are possible:

If the update specification is absent, it is supposed that updates are not supported by the package at all.

For exact version comparison a Controller MUST be able to compare packages versions as specified in Package Version section of specification with help of < > <= >= and = XPath operator. XPath extensions function should be available to compare complex versions vercmp(a,b). Binary "vercmp" returns -1, 0, or 1 depending on whether the left argument is version-wise less than, equal to, or greater than the right argument using RPM version compare rules.

<patch match="(/application/version = '2.0' and /application/release='1')
           or (/application/version = '2.0' and /application/release='2')" recommended="true" />
<upgrade match="/application/version = '1.0' and /application/release='1'" />

Such specification means that package can patch the installed version 2.0.1 or 2.0.2 and upgrade version 1.0.1.

<patch match="/application/version > '2.0'" recommended="true" />
<upgrade match="/application/version > '1.0'" />

Such specification means the following:

<upgrade mode="managed"/>

Upgrade in managed mode, no version restrictions.

<patch match="vercmp(/application/version,'2.1.0a') = 1"/>

Controller will select all versions greater then 2.1.0a.

<content xmlns:dll="http://apstandard.com/ns/1/dll">
  <dll:register path="win/some.dll"/>
</content>

Application may require a special processing of application's archive content prior to actual usage. Allowed content processing options are defined in aspects. See DLL Content Processing Method for more details.

<global-settings>
  <setting id="host">
    ...
  </setting>
</global-settings>

Package may have global settings that are visible and affect all instances of application services. Global settings SHOULD be set prior to any service provision. Such settings are declared by the global-settings element within the application description. When a global setting is changed, all instances of the application services need to be reconfigured immediately. Global settings MUST NOT use the value-of-setting attribute.

Service SHOULD be described with a brief summary information.

<service id="email">
  <presentation>
    <name>Email</name>
    <name xml:lang="de"> ... </name>
    <summary>Electronic mail address with mailbox</summary>
    <icon path="images/email.gif"/>
    ...
  </presentation>
  ...
</service>

<license must-accept="true">
  <free/>
  <text>
    <name>GPLv2</name>
    <file>licenses/gplv2.txt</file>
  </text>
  <text xml:lang="de-DE">
    <name>GPLv2</name>
    <file>licenses/gplv2-de_DE.txt</file>
  </text>
<license>
        

or

<license>
  <text>
    <name>Revised BSD</name>
    <url>http://opensource.org/licenses/bsd-license</url>
  </text>
</license>
        

A license declaration MAY include name of the license, whether the license must be accepted by a user, and either a full path to the license file in the package or a URL of the full text of the license. The file element MUST be a full path in the archive to the existing file. Application license may be characterized as free or commercial by using appropriate free or commercial element.

The packager may declare links to external web resources that a control panel should show for the given service. Text to be shown for the link is specified as the link element's value. A control panel SHOULD show only informational links relevant for current user's locale.

<presentation>
  <infolinks>
    <link xml:lang="en" class="official" href="http://example.com">
      Official site
    </link>
    <link xml:lang="de" class="official" href="http://example.com/de">
      Offizielle Website
    </link>
  </infolinks>
</presentation>

The class attribute MAY be used to inform a control panel about the destination web resource meaning. The following values of this attribute are predefined:

Controller MAY use this information when grouping the links or optionally displaying them. Controller SHOULD ignore unknown values of the class attribute and treat it as unspecified.

Packager may declare entry points to be used for a given service. When a Controller provisions a service with entry points, it MAY provide user with the choice of what entry points to show in control panel interface and where.

<entry-points>

  <entry dst="/info">
    <label>Information service</label>
  </entry>

  <entry dst="/guest">
    <label>Guest view</label>
    <label xml:lang="de-DE">...</label>
    <description>View the gallery as user not logged in</description>
    <icon path="images/icon-guest.png"/>
  </entry>

  <entry class="control-panel" dst="/admin" method="POST">
    <label>Administrative interface</label>
    <icon path="images/icon-admin.png"/>
    <variable name="username" class="login">admin</variable>
    <variable name="password" class="password"
              value-of-setting="admin_password"/>
  </entry>

  <entry dst="/stats{-prefix|/category/|default-category}" method="GET">
    <label>Statistics</label>
    <icon path="images/icon-stats.png"/>
    <variable name="default-category"
              value-of-setting="category_to_show_by_default"/>
  </entry>

  <entry dst="{isp}/account/{account}" method="GET">
    <label>My Account</label>
    <icon path="images/icon-money.png"/>
    <variable name="isp"
              value-of-setting="isp_url">http://example.com</variable>
    <variable name="account" class="login" value-of-setting="login_in_isp"/>
  </entry>

</entry-points>

The dst attribute of an entry point may contain absolute or relative URI of the entry point. Templates conforming to [URI Templates] are allowed. For relative URIs, absolute URL will be generated when entry point is being displayed, pointing to the base URL of application + URI of entry point. GET or POST HTTP request method MAY be declared to be used to access HTTP entry point. GET is assumed by default.

When displaying an entry point, Controller SHOULD use the provided label, description and icon. The icon/@path attribute MUST contain a full path in archive to the icon file. The icon SHOULD be a 64x64 pixel image in PNG format using alpha transparency. JPEG and GIF formats MAY be used as well, but their use is discouraged.

The entry/@class attribute MAY be used to inform Controller about the entry point designation. The following values of this attribute are predefined:

Controller MAY use this information for displaying the entry point. Controller MUST ignore unknown entry/@class and treat such entry point as being without explicit class specification. Application MAY declare several entry points with the same class attribute.

Entry point MAY declare request variables to be specified when user clicks entry point in control panel interface. Variables values may be taken from actual service settings using the value-of-setting attribute or explicitly specified as the variable element value. If the specified setting has empty value, the variable element value MUST be used. These variables are also used for URI Templates expansion. Variables with duplicate names are allowed and, if present, MUST be used for arrays representation as defined in [URI Templates] 'prefix' operator (4.4.4), 'suffix' operator (4.4.5) and 'list' operator.

If the POST request method is used, variables MUST be submitted using the application/x-www-form-urlencoded encoding. In case of the GET method, variables must be submitted as specified by URI template syntax. If URI template is not used, variables are submitted using the application/x-www-form-urlencoded encoding.

The variable/@class attribute MAY be used to inform a Controller about the request variable meaning. The following values of this attribute are predefined:

Controller MAY provide arbitrary values for such variables basing on its own considerations. Controller MUST ignore unknown variable/@class and treat such variable as variable without explicit class specification. Application MAY declare several variables with the same class attribute. Controller SHOULD provide equal values for variables with the same class.

Applications often need additional parameters for successful installation and configuration. While most of the questions asked during conventional application installation are related to various resources and answers may be provided by Controller without user intervention, some settings need to be entered by user. Controller MUST keep state of application settings values to pass them to the configuration/update scripts.

Settings are declared in the settings elements in services description. Each setting element represents a single setting to be asked from user.

To make user interface more convenient, the following information is supplied for each setting:

Settings may be declared as "installation only". Settings of this type need to be set up during service provisioning and should not be reconfigured later. This includes all settings which may be configured from the application, as any reconfiguration in the control panel will effectively reset user customizations done in application. Such settings are marked with the installation-only attribute.

If a setting has the track-old-value attribute and value of the setting is changed, Controller MUST provide old value together with new one when performing service instance reconfiguration.

If a setting has the optional attribute and value of the setting is not specified, Controller MUST NOT apply type validation rules for setting's value and SHOULD use usual algorithm for calculating of default value if applicable. If it is no optional attribute defined this setting is treated as mandatory and Controller SHOULD NOT allow entering empty value for the setting unless it is allowed by validation rules.

Regular settings are visible only to service that declares them. Settings with the same name/id are allowed in different services.

Setting that should have a unique value within some scope should have an uniq attribute. This attribute may have one of the following values:

Once setting defined as unique Controller MUST arrange setting value unicity in requested scope. And refuse non-unique user input or auto-configuration.

All settings identified by the same uuid attribute and have uniq attribute defined are validated for unicity between each other by Controller.

Setting may be hidden from application owner by providing visibility attribute with value hidden. If no this attribute specified setting threaded as visible.

Setting may be protected from editing by both application owner and provider by protected attribute with value true. If no this attribute specified setthing is threaded as available for editing.

Setting SHOULD be filled by (pre)controller automattically in case when generate attribute set to one of values:

Controller MUST satisfy any other requirements while generation of value if any exist for the setting.

Child services may reference values of parent services settings using the value-of-setting attribute. This attribute specifies ID of parent service setting whose value must be used for the given setting. The appropriate parent setting is searched in ascending order. If a parent service does not contain such setting, the next parent is examined upward. Thus, referencing through several levels of nesting is allowed. Referenced setting MUST be declared in the package. When the referenced setting value is changed, the affected service instances must be reconfigured. It is prohibited to reference to settings which, in turn, references another settings.

When application is upgraded, it is prohibited to transform settings with the same id from being installation-only and to replace setting value with reference to value of another setting (using the value-of-setting attribute). This restriction is introduced to protect application instance settings values.

For patches it is also prohibited to introduce new settings without default values, as this prevents unattended patch installation.

Settings may be grouped by the group element. Group MAY have a name declared by the name element. Groups without specified name are called anonymous . Group contains a list of settings and MAY contain anonymous groups. Settings and groups are listed in the order suggested to be used in interface.

<group class="authn">
  <setting id="user_account_name" type="string" class="login">
    <name>User login</name>
  </setting>
  <setting id="user_pwd" type="password" class="password">
    <name>Password</name>
  </setting>
</group>

<group class="presentation">
  <setting id="user_locale" type="enum" default-value="en-GB" class="locale">
    <name>Default locale</name>
    <choice id="en-GB">
      <name>English</name>
    </choice>
    <choice id="fr-FR">
      <name>French</name>
    </choice>
    <choice id="de-DE">
      <name>German</name>
    </choice>
  </setting>
</group>

<group class="web">
  <setting id="site_title" type="string" class="title"
           default-value="Homepage">
    <name>Site Title</name>
  </setting>

  <setting id="site_description" type="string" class="description"
           default-value="Personal Playground">
    <name>Site Description</name>
  </setting>
</group>

<group class="vcard">
  <group class="fn n">
    <setting id="user_first_name" class="given-name" ... />
    <setting id="user_last_name"  class="family-name" ... />
  </group>
  <group class="tel">
    <name class="type">work</name>
    <setting id="work_phone" class="value" .../>
  </group>
  <group class="tel">
    <name class="type">cell</name>
    <setting id="mobile_phone" class="value" .../>
  </group>
</group>

The Resources section of metadata describes what usage values are reported by application. This information may be used by controller for application monitoring and resource accounting.

<resources>
	<resource id="users" class="item" limiting-setting="users">
		<name>Number of users created in application</name>
		<description>Number of active users created within application</description>
	</resource>
	<resource id="folders" class="item" limiting-setting="folders">
		<name>Number of folders</download>
		<description>Total number of active directory folders used by application</description>
	</resource>
	<resource id="traffic.download" class="kb">
		<name>Download Traffic</download>
		<description>Total number of kbytes downloaded by application</description>
	</resource>
</resources>

Resource is identified by unique string in attribute id. Attribute class gives a hint to controller on this resource units of measure and what to display to an end-user. Some class values are defined by this specification: item, b, kb, mb, gb.

Application may give a hint to controller what settings limit this resource usage by limiting-setting attribute. So, control panel will be able to display both current resource usage and its actual limit to user.

Reporting of resource usage happens for all resources together with resource-script execution.

The Requirements section in metadata describes what conditions should be met to provision a service. Requirements usually request particular resource to be allocated, or specific configuration to be performed.

<requirements
       xmlns:php="http://apstandard.com/ns/1/php"
       xmlns:db="http://apstandard.com/ns/1/db">
  <php:version min="5.0.2"/>
  <choice>
    <requirements id="mysql">
      <php:extension>mysql</php:extension>
      <db:db>
        <db:id>main</db:id>
        <db:default-name>wiki</db:default-name>
        <db:can-use-tables-prefix>true</db:can-use-tables-prefix>
        <db:server-type>mysql</db:server-type>
        <db:server-min-version>4.0</db:server-min-version>
      </db:db>
    </requirements>
    <requirements id="postgresql">
     <php:extension>postgresql</php:extension>
     <db:db>
       <db:id>main</db:id>
       <db:default-name>wiki</db:default-name>
       <db:can-use-tables-prefix>false</db:can-use-tables-prefix>
       <db:server-type>postgresql</db:server-type>
       <db:server-min-version>7.4</db:server-min-version>
     </db:db>
    </requirements>
  </choice>
</requirements>

Requirements belong to the "requirement types". Requirement types are defined in aspects. Each requirement type has an associated unique XML QName (element name + namespace) and an element schema (preferably in RELAX NG). Every requirement should be described as an XML element according to its schema.

Every requirement type has associated rules (in natural language) of how to satisfy the requirement during the instantiation as the part of the requirement type definition in aspect.

Individual requirements form a complex requirement which needs to be satisfied by Controller. This is performed by logical 'AND' of requirements (when they are just placed in the requirements section side-by-side), and logical 'OR' of requirements when they are placed in the choice sub-element inside the requirements element. Controller has to ensure the logical truth of a complex requirement (this means not all individual requirements need to be satisfied).

Only one level of choices is allowed to simplify building the GUI.

For each choice element, the CHOICE_<id> environment variable must be passed to the configure script, with the value of the id attribute of the selected requirements element.

Every resource allocated for application instance as a result of satisfying requirements MUST be preserved during upgrade. Exact semantics of preservation is left to the requirement specification.

No changes in application instance resources are allowed during patches. Therefore, Controller MUST preserve all resources allocated for previous version of service and MUST NOT analyze requirements of new version.

Application service may be provisioned in a variety of ways depending on available environment or application nature. Provision methods are declared with the provision element.

Application may support different provision methods depending on which requirements were satisfied by Controller. This is performed by using the when-chosen element. It references selected requirements branch by specifying requirements-id attribute's value.

Controller MUST choose appropriate provision method according to the satisfied requirements branch. When there is no when-chosen element referencing the chosen requirements branch, or no requirements branches are defined, the default provision method specified without the when-chosen element MUST be used. If it is absent, provision process MUST be aborted.

<provision>

  <when-chosen requirements-id="arch-x86_64">
    <mapping url="/" path="cgi/x86_64"/>
  </when-chosen>

  <mapping url="/" path="cgi/i386"/>

</provision>

The snippet above demands creation of URL mapping pointing to the cgi/x86_64/ directory when the service is provisioned in x86_64 environment, and into cgi/i386/ for other architectures.

When application is updated, the following two types of provisioned services are distinguished:

This division depends on provision methods being used for the service. If at least one of used provision methods requires individual update, the update procedure MUST be performed for all the service's provision methods. If no provision methods require individual update, Controller MUST NOT perform update procedures for the service.

Web applications are designed to handle incoming requests. URL mapping describes how to map the requested URLs to the particular handlers or files.

<url-mapping>
  <default-prefix>forum</default-prefix>
  <installed-size>5242880</installed-size>

  <mapping url="/" path="htdocs"
      xmlns:php="http://apstandard.com/ns/1/php"
      xmlns:mod-python="http://apstandard.com/ns/1/mod-python">
    <php:handler>
      <php:extension>php</php:extension>
      <php:extension>pinc</php:extension>
    </php:handler>

    <mapping url="upload">
      <php:handler><php:disabled/></php:handler> <!-- Disabling PHP -->
      <php:permissions writable="true"/>
    </mapping>
    <mapping url="stat" virtual="virtual">
      <php:handler><php:disabled/></php:handler>
      <mod-python:handler>com.example.StatHandler</mod-python:handler>
    </mapping>
  </mapping>
</url-mapping>

The example mapping describes three contexts: URLs starting from the /, URLs starting from the /upload and URLs starting from the /stat. The two first are mapped to the file system, the third one is virtual (the mod_python aspect is not defined in this specification, so this is placed here just for illustrative purposes).

The default-prefix element defines a segment of URL path component which should precede the service instance root by default. Controller is allowed to change it. Controller MUST normalize leading and trailing slashes of default prefix when forming the final URL.

The site-root element defines requrement of URL mapping to be on root of web site. Controller MUST place that URL mapping as root mapping of site. This element MUST appear only in top level of URL mapping root service.

Package may include a declaration of approximate size of a single URL mapping instance, to help Controllers estimate the disk space resources needed for service provisioning. For this, the installed-size element should be specified with the declared size of URL mapping instance size in bytes.

Mappings may be nested, and there MUST NOT be two mappings with such URLs that the first URL is the prefix of the second URL. In other words, the construction

<mapping url="/">
  <mapping url="foo/bar"/>
  <mapping url="foo/bar/baz"/>
</mapping>

is prohibited, and MUST be rewritten as

<mapping url="/">
  <mapping url="foo/bar">
    <mapping url="baz"/>
  </mapping>
</mapping>

All url s in mappings are relative to the parent URL mapping. Absolute URLs are PROHIBITED in the url attributes except the root mapping where url value MUST be '/'.

The path attribute of mapping is always path from the root of archive to the directory inside the archive, it must not have the / character at the start.

If mapping has an explicit path attribute, then the mapping is associated with the directory specified by this attribute. The association means that any URL which is in the scope of the given mapping (URLs in scopes of inner mappings are not in the scope of outer mapping) and is not handled by the handlers declared in the mapping needs to be served as the file from the directory specified.

If a mapping has neither an explicit path attribute nor a virtual attribute, then the directory associated with the given mapping is calculated from the directory associated with the parent mapping appending the relative URL that the given mapping has. E.g., for the following declarations

<mapping url="/" path="htdocs">
  <mapping url="foo/bar">
    <mapping url="baz"/>
    <mapping url="quux" path="somedir"/>
  </mapping>
</mapping>

mapping '/' is associated with the htdocs/ directory, mapping '/foo/bar' is associated with the htdocs/foo/bar directory, mapping '/foo/bar/baz' is associated with the htdocs/foo/bar/baz directory, and mapping '/foo/bar/quux' is associated with the htdocs/foo/bar/somedir directory.

If mapping has an explicit virtual attribute equal to virtual, then the mapping is not associated with any directory, and requests to the URLs in the scope of this mapping must return 'Not found' error, if not handled by handlers declared in the given mapping.

If mapping has an explicit virtual attribute equal to redirect, then the controller SHOULD configure HTTP redirect to URL denoted by href mapping child.

If mapping has an explicit shared attribute equal to true, then the controller SHOULD share contents of directory referred by this mapping between all instances of the version of application.

If an outer mapping does not have an associated directory, then the inner mappings without explicit path element do not have an associated directory too.

If the whole application mapping is not virtual (meaning that there is at least one mapping without the virtual attribute), the root mapping MUST have the path attribute.

Controller MUST use mapping information for deployment and upgrade of application instance files. Files deployment MUST be driven by URL mapping rules.

Aspects declare types of URL handlers, rules of how to process them. Rules regulating propagation of specific URL handlers to inner mappings are also declared in aspects.

The handler defined latter overrides the former. In the following example, all *.php files will be processed by CGI handler.

<mapping url="users">
  <php:handler>
    <php:extension>php</php:extension>
  </php:handler>
  <cgi:handler>
    <cgi:extension h:handler-type="php">php</cgi:extension>
  </cgi:handler>
</mapping>

A service may be provisioned with the help of configuration script. This script will be invoked during application service provisioning, cancelling, updating and reconfiguration. Availability of the script is declared by the configuration-script element. Different configuration scripts for different services are allowed.

<configuration-script name="configure">
  <script-language>php</script-language>
</configuration-script>

Configuration scripts MUST reside in the scripts directory in the package root directory. Name of configuration script is specified with the name attribute.

Configuration script MUST declare programming language it is written in using the script-language element. Controller will use appropriate interpreter to run the configuration script. Valid interpreters are defined in aspects specification . This specification defines a set of php , perl , jscript and vbscript interpreters. Binary executable configuration scripts are allowed. In this case, the binary-executable element must be used.

Controller MUST run configuration script within environment where the application is being installed. Configuration script which requires high privileges in order to run MUST use the privileged attribute. Controller MUST run such script with superuser privileges. Controller MUST NOT run in privileged mode configuration script which does not declare this attribute.

During the configuration script execution, the working directory MUST be set to the actual location of the script. All content of the scripts directory MUST also reside in the script current working directory.

If any script invocation fails (script returns a non-zero exit code), it MUST be treated as fatal error and Controller MUST refuse to continue operation. Stdout and stderr I/O streams of the script should be captured to log error or treat output values, see configuration script output.

install

                upgrade <old version> <old release>
              

configure

remove

<configuration-script name="reseller">
  <script-language>php</script-language>
  <status-control/>
</configuration-script>

enable
disable

SERVICE_ID=gallery

BASE_URL_SCHEME=http
BASE_URL_HOST=example.com
BASE_URL_PORT not defined
BASE_URL_PATH=phpBB/

<mapping url="/" path="htdocs">
  <mapping url="foo/bar">
    <mapping url="baz"/>
    <mapping url="quux" path="somedir"/>
  </mapping>
</mapping>

WEB___DIR=/var/www/vhosts/domain.name/public_html/example/htdocs
WEB__foo_bar_DIR=/var/www/vhosts/domain.name/public_html/example/htdocs/foo/bar
WEB__foo_bar_baz_DIR=\
  /var/www/vhosts/domain.name/public_html/example/htdocs/foo/bar/baz
WEB__foo_bar_quux_DIR=/var/www/vhosts/domain.name/public_html/example/somedir

<output xmlns="http://apstandard.com/ns/1/configure-output">
	<errors>
		<error id="1093" setting-id="login">
			<message>Login name 'jsmith' already exists.</message>
			<system>login 'jsmith' is duplications with record id=12384</system>
		</error>
		<error id="1123" setting-id="password">
			<message>Password matches dictionary word</message>
			<system>login 'jsmith' password strength too low rate=0.02</system>
		</error>
	</errors>
</output>

<output xmlns="http://apstandard.com/ns/1/configure-output">
	<settings>
		<value setting-id="context-id">12365</value>
		<value setting-id="creation-date">2009-10-10</value>
	</settings>
</output>

Verification script is very similar to configuration script by semantic but designed for check service settings for consistency. It SHOULD never change state of application or application instances. Verification script presented by verify-script element node.

Calling conventions are the same as with configuration script. It supports following actions install, configure, upgrade.

Verification script can be defined and called in both global context and context of service instance. In case of global context no resources allocated and no environment variables related to service instance or resources provided. Call of verification script in global context required for verification of global settings. Also verification script MAY be called for settings verification before service provisioning.

Usage of element structured-output is allowed here. And should be processed by controller in same way as processed while execution of configuration script. In additional to possibility to verify settings values there is also a possibility to return list of choices for enum setting type. In that case controller SHOULD cache returned list choices and suggest it for settings editing in appropriate context until new list returned. List may be returned while both successful and not successful script execution.

Controller MAY execute this script while user press special control for verification (for example "Verify" button on settings edit screen). Or on just usual install/configure/upgrade operation. It should be safe to call this script in synchronous mode. To make results of execution visible for user just on submit.

Resource script reports current resource usage to controller. Script is periodically called by controller. Resource script presented by resource-script element node.

Resource script follows same calling conventions as configuration script. With only exception that output stream of the script should be always XML matching schema below.

Application may give a hint to controller how often it should poll application for resource usage value with poll-interval attribute. It MAY be specified either as number of minutes, like 5m or as number of hours like 2h or as number of days, like 1d. Controller MAY disregard poll-interval attribute and decide how often call resource script.

Some resources usage requires time period it was measured over to be reported (i.e. traffic). Application may report time in seconds as period attribute.

If some resource was not reported in output controller MUST assume that resource is not used.

RELAX NG schema of resource script output

<resources>
	<resource id="users" value="123"/>
	<resource id="folders" value="1340"/>
	<resource id="traffic.download" value="12388" period="300"/>
</resources>

Operations like backup, restoration or migration may be done with the help of backup script. This script will be invoked during application backup and restoration. Availability of the script is declared by the backup-script element. Different configuration scripts for different services are allowed.

<backup-script name="backup.php">
  <script-language>php</script-language>
</backup-script>

Backup/Restore script follows same calling conventions as configuration script.

If any script invocation fails (script returns a non-zero exit code), it MUST be treated as fatal error and Controller MUST refuse to continue operation. Stdout and stderr I/O streams of the script should be captured to log error in this case.

backup

restore

PHP aspect declares the following requirement types: PHP version requirement type, PHP extension requirement type, PHP function requirement type, and a set of PHP settings requirement types.

<php:version min="4.1" max-not-including="5.0"/>

Requirement of this type is satisfied if the version of PHP enabled on a site is in [min, max-not-including) interval taken from the requirement. Both limits are optional.

The PHP_VERSION environment variable MUST be passed on to the configuration script with the version of PHP (as a string value) installed on the Web site where the package is to be installed.

<php:extension>curl</php:extension>
<php:extension>Zend Optimizer</php:extension>
<php:extension>ionCube Loader</php:extension>

Requirement of this type is satisfied if the specified PHP extension is enabled for the web application.

The names of PHP extensions are specified in the zend_module_entry structure of extension code and may be obtained by the get_loaded_extensions PHP function.

<php:function>system</php:function>

Requirement of this type is satisfied when the specified PHP function is enabled in PHP.

<php:allow-url-fopen>true</php:allow-url-fopen>

If a web application needs one of allow_url_fopen, file_uploads, safe_mode, short_open_tag, register_globals or magic_quotes_gpc settings to be true or false, the appropriate requirement must be used. Requirements of those types are satisfied when the corresponding PHP setting has the specified value.

<php:memory-limit>16777216</php:memory-limit>

If a web application needs a particular value of memory_limit, max_execution_time or post_max_size settings, it should use these requirement types (defining values in bytes and seconds).

Requirements of those types are satisfied when the corresponding PHP setting has the value specified in the requirement or larger.

<php:handler>
  <php:extension>php</php:extension>
  <php:extension>pinc</php:extension>
</php:handler>

<php:handler><php:disabled/></php:handler>

Handlers of this type require that files with the specified extensions (if no extensions are specified, a single php extension is assumed) are handled by the PHP interpreter.

Inner mappings inherit handlers from the outer mappings, so the presence of php:disabled disables PHP in the given mapping.

<php:permissions writable="true">

<php:permissions readable="false">

The situation when a directory and files in the directory to which the given mapping maps should be writable by PHP interpreter is specified by using the writable attribute with the "true" value. The "false" value is default, so no explicit attribute for this is required.

The situation when files in the directory should be protected from reading by PHP interpreter is specified by the readable attribute with the "false" value. The "true" value is default, so no explicit attribute for this is required.

Inner mappings do not inherit permission handlers from the outer mappings.

This aspect defines the php identifier to be used by configuration scripts. When a configuration script uses the php language, it MUST be run by stand-alone PHP interpreter. All the requirements described in the application metadata apply to the interpreter running configuration scripts.

This aspect declares a single requirement type: ASP.NET version requirement. Requirement of this type is satisfied when the application is installed in virtual directory with the specified version of ASP.NET enabled.

<aspnet:handler/>
<aspnet:handler>
  <aspnet:disabled/>
</aspnet:handler>

Handler of this type requires that files with the specified extensions (if no extensions are specified, the default set of ASP.NET extensions is assumed) are handled by ASP.NET.

Inner mappings inherit handlers from the outer mappings, so the presence of aspnet:disabled disables ASP.NET in the given mapping.

<aspnet:permissions writable="true">

The situation when files in the directory to which the given mapping maps should be writable by the ASP.NET interpreter is specified by using the writable attribute with the "true" value. The "false" value is default, so no explicit attribute for this is required.

This aspect defines jscript and vbscript identifiers to be used by configuration scripts (written in JScript and VBscript correspondingly).

When a requirement is satisfied, the following environment variables must be passed to configuration scripts:

Environment variables DB_<identifier>_HOST and DB_<identifier>_PORT MUST NOT be specified if an application is to use local transport (UNIX sockets or named pipes) to connect to database.

The server-type element describes the name of database server. Currently defined names are:

Another names SHOULD be taken from the JDBC drivers registry [JDBCDRIVERS] . Official database server driver SHOULD be used if more than one drivers are available. JDBC driver name (and a sub-name if the name specifies the company, as with 'microsoft:sqlserver') is used.

If both old and new version of package require a database with the same id , then this database and its content need to be preserved. Controller MUST refuse to upgrade database to another database type.

All databases which are declared in old or new packages MUST be accessible during upgrade script invocation. Thus, application MAY perform database upgrades by issuing new database id in the package release which requires cross-database upgrade.

This specification defines requirements type for privileges of MySQL user on database being allocated.

<requirements>
  <db:db xmlns:db="http://apstandard.com/ns/1/db">
    <db:id>storage</db:id>
    <db:default-name>broombla</db:default-name>
    <db:can-use-tables-prefix>true</db:can-use-tables-prefix>
    <db:server-type>mysql</db:server-type>
    <db:server-min-version>4.1.0</db:server-min-version>

    <db:features xmlns:mysql="http://apstandard.com/ns/1/db/mysql">
      <mysql:privilege>Create_tmp_table_priv</mysql:privilege>
      <mysql:privilege disabled="true">Lock_tables_priv</mysql:privilege>
    </db:features>
  </db:db>
</requirements>

The names of MySQL privileges are specified in the db table of the mysql database. Controversial permissions MUST NOT be specified.

When a requirement is satisfied, the following environment variables must be passed to configuration scripts for 'mailbox' requirement:

When a requirement is satisfied, the following environment variables must be passed to configuration scripts for 'outgoing' requirement:

If both old and new versions of application require mailbox then the mailbox, its content and user access credentials MUST be preserved. If new version of application requires different set of mailbox access protocols, then mailbox MUST be accessible over new set of protocols during upgrade.

Perl aspect declares the following requirement types: perl version and perl module.

<perl:version match="version &gt;= 5.0"/>

Requirement of this type is satisfied if the version of Perl enabled on a site matches XPath expression in requirement. It processed against virtual XML document with only node version.

The PERL_VERSION environment variable MUST be passed to the configuration script with the version of Perl (as a string value) installed on the Web site where the package is to be installed.

<perl:module name ="CGI"/>
<perl:module name="DBI" match="version &gt; 1.21"/>

Requirement of this type is satisfied if the specified Perl extension is enabled for the web application.

Defined here perl modules should be available with perl 'use' instruction.

If application requires specific method of integration with web server it may specify it with mod_perl or active_perl tags.

  <perl:mod_perl match="version = 1.30"/>

  <perl:active_perl/>

<perl:handler>
  <perl:extension>pl</perl:extension>
  <perl:extension>perl</perl:extension>
</perl:handler>

<perl:handler><perl:disabled/></perl:handler>

Handlers of this type require that files with the specified extensions (if no extensions are specified, a single pl extension is assumed) are handled by the perl interpreter.

Inner mappings inherit handlers from the outer mappings, so the presence of perl:disabled disables Perl in the given mapping.

This aspect defines the perl identifier to be used by configuration scripts. When a configuration script uses the perl language, it MUST be run by stand-alone perl interpreter. All the requirements described in the application metadata apply to the interpreter running configuration scripts.