(DAV:delete-version-reference): If a version is deleted, any
reference to that version in a DAV:merge-set or DAV:auto-merge-set
property MUST be removed.
11.6 Additional CHECKIN Semantics
Additional Preconditions:
(DAV:merge-must-be-complete): The DAV:merge-set and DAV:auto-
merge-set of the checked-out resource MUST be empty or not exist.
12 Baseline Feature
A configuration is a set of resources that consists of a root
collection and all members of that root collection except those
resources that are members of another configuration. A configuration
that contains a large number of resources can consume a large amount
of space on a server. This can make it prohibitively expensive to
remember the state of an existing configuration by creating a
Depth:infinity copy of its root collection.
A baseline is a version resource that captures the state of each
version-controlled member of a configuration. A baseline history is
a version history whose versions are baselines. New baselines are
created by checking out and then checking in a special kind of
version-controlled resource called a version-controlled
configuration.
A collection that is under baseline control is called a baseline-
controlled collection. In order to allow efficient baseline
implementation, the state of a baseline of a collection is limited to
be a set of versions and their names relative to the collection, and
the operations on a baseline are limited to the creation of a
baseline from a collection, and restoring or merging the baseline
back into a collection. A server MAY automatically put a collection
under baseline control when it is created, or a client can use the
BASELINE-CONTROL method to put a specified collection under baseline
control.
As a configuration gets large, it is often useful to break it up into
a set of smaller configurations that form the logical "components" of
that configuration. In order to capture the fact that a baseline of
a configuration is logically extended by a component configuration
baseline, the component configuration baseline is captured as a
"subbaseline" of the baseline.
The root collection of a configuration is unconstrained with respect
to its relationship to the root collection of any of its components.
In particular, the root collection of a configuration can have a
member that is the root collection of one of its components (e.g.,
configuration /sys/x can have a component /sys/x/foo), can be a
member of the root collection of one of its components (e.g.,
configuration /sys/y/z can have a component /sys/y), or neither
(e.g., configuration /sys/x can have a component /comp/bar).
12.1 Version-Controlled Configuration Properties
Since a version-controlled configuration is a version-controlled
resource, it has all the properties of a version-controlled resource.
In addition, the baseline feature introduces the following REQUIRED
property for a version-controlled configuration.
12.1.1 DAV:baseline-controlled-collection (protected)
This property identifies the collection that contains the version-
controlled resources whose DAV:checked-in versions are being tracked
by this version-controlled configuration. The DAV:version-
controlled-configuration of the DAV:baseline-controlled-collection of
a version-controlled configuration MUST identify that version-
controlled configuration.
<!ELEMENT baseline-controlled-collection (href)>
12.2 Checked-Out Configuration Properties
Since a checked-out configuration is a checked-out resource, it has
all the properties of a checked-out resource. In addition, the
baseline feature introduces the following REQUIRED property for a
checked-out configuration.
12.2.1 DAV:subbaseline-set
This property determines the DAV:subbaseline-set property of the
baseline that results from checking in this resource.
A server MAY reject attempts to modify the DAV:subbaseline-set of a
checked-out configuration.
<!ELEMENT subbaseline-set (href*)>
12.3 Baseline Properties
The DAV:resourcetype of a baseline MUST be DAV:baseline. Since a
baseline is a version resource, it has all the properties of a
version resource. In addition, the baseline feature introduces the
following REQUIRED properties for a baseline.
12.3.1 DAV:baseline-collection (protected)
This property contains a server-defined URL for a collection, where
each member of this collection MUST either be a version-controlled
resource with the same DAV:checked-in version and relative name as a
version-controlled member of the baseline-controlled collection at
the time the baseline was created, or be a collection needed to
provide the relative name for a version-controlled resource.
<!ELEMENT baseline-collection (href)>
12.3.2 DAV:subbaseline-set (protected)
The URLs in the DAV:subbaseline-set property MUST identify a set of
other baselines. The subbaselines of a baseline are the baselines
identified by its DAV:subbaseline-set and all subbaselines of the
baselines identified by its DAV:subbaseline-set.
<!ELEMENT subbaseline-set (href*)>
12.4 Additional Resource Properties
The baseline feature introduces the following REQUIRED property for a
resource.
12.4.1 DAV:version-controlled-configuration (computed)
If the resource is a member of a version-controlled configuration
(i.e. the resource is a collection under baseline control or is a
member of a collection under baseline control), this property
identifies that version-controlled configuration.
<!ELEMENT version-controlled-configuration (href)>
12.5 Additional Workspace Properties
The baseline feature introduces the following REQUIRED property for a
workspace.
12.5.1 DAV:baseline-controlled-collection-set (computed)
This property identifies each member of the workspace that is a
collection under baseline control (as well as the workspace itself,
if it is under baseline control).
<!ELEMENT baseline-controlled-collection-set (href*)>
12.6 BASELINE-CONTROL Method
A collection can be placed under baseline control with a
BASELINE-CONTROL request. When a collection is placed under baseline
control, the DAV:version-controlled-configuration property of the
collection is set to identify a new version-controlled configuration.
This version-controlled configuration can be checked out and then
checked in to create a new baseline for that collection.
If a baseline is specified in the request body, the DAV:checked-in
version of the new version-controlled configuration will be that
baseline, and the collection is initialized to contain version-
controlled members whose DAV:checked-in versions and relative names
are determined by the specified baseline.
If no baseline is specified, a new baseline history is created
containing a baseline that captures the state of the version-
controlled members of the collection, and the DAV:checked-in version
of the version-controlled configuration will be that baseline.
Marshalling:
If a request body is included, it MUST be a DAV:baseline-control
XML element.
<!ELEMENT baseline-control ANY>
ANY value: A sequence of elements with at most one DAV:baseline
element.
<!ELEMENT baseline (href)>
If a response body for a successful request is included, it MUST
be a DAV:baseline-control-response XML element.
<!ELEMENT baseline-control-response ANY>
The response MUST include a Cache-Control:no-cache header.
Preconditions:
(DAV:version-controlled-configuration-must-not-exist): The
DAV:version-controlled-configuration property of the collection
identified by the request-URL MUST not exist.
(DAV:must-be-baseline): The DAV:href of the DAV:baseline element
in the request body MUST identify a baseline.
(DAV:must-have-no-version-controlled-members): If a DAV:baseline
element is specified in the request body, the collection
identified by the request-URL MUST have no version-controlled
members.
(DAV:one-baseline-controlled-collection-per-history-per-
workspace): If the request-URL identifies a workspace or a member
of a workspace, and if a baseline is specified in a DAV:baseline
element in the request body, then there MUST NOT be another
collection in that workspace whose DAV:version-controlled-
configuration property identifies a version-controlled
configuration for the baseline history of that baseline.
Postconditions:
(DAV:create-version-controlled-configuration): A new version-
controlled configuration is created, whose DAV:baseline-
controlled-collection property identifies the collection.
(DAV:reference-version-controlled-configuration): The
DAV:version-controlled-configuration of the collection identifies
the new version-controlled configuration.
(DAV:select-existing-baseline): If the request body specifies a
baseline, the DAV:checked-in property of the new version-
controlled configuration MUST have been set to identify this
baseline. A version-controlled member of the collection will be
created for each version in the baseline, where the version-
controlled member will have the content and dead properties of
that version, and will have the same name relative to the
collection as the corresponding version-controlled resource had
when the baseline was created. Any nested collections that are
needed to provide the appropriate name for a version-controlled
member will be created.
(DAV:create-new-baseline): If no baseline is specified in the
request body, the request MUST have created a new baseline history
at a server-defined URL, and MUST have created a new baseline in
that baseline history. The DAV:baseline-collection of the new
baseline MUST identify a collection whose members have the same
relative name and DAV:checked-in version as the version-controlled
members of the request collection. The DAV:checked-in property of
the new version-controlled configuration MUST identify the new
baseline.
12.6.1 Example - BASELINE-CONTROL
>>REQUEST
BASELINE-CONTROL /src HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:baseline-control xmlns:D="DAV:">
<D:href>http://www.webdav.org/repo/blh/13/ver/8</D:href>
</D:baseline-control>
>>RESPONSE
HTTP/1.1 200 OK
Cache-Control: no-cache
Content-Length: 0
In this example, the collection /src is placed under baseline
control, and is populated with members from an existing baseline. A
new version-controlled configuration (/repo/vcc/128) is created and
associated with /src, and /src is initialized with version-controlled
members whose DAV:checked-in versions are those selected by the
DAV:baseline-collection (/repo/bc/15) of the specified baseline
(/repo/blh/13/ver/8). The following diagram illustrates the
resulting state on the server.
+-------------------------------------+
|Baseline-Controlled Collection |<------+
|/src | |
|-------------------------------------| |
|DAV:version-controlled-configuration +---+ |
+-------------------------------------+ | |
| |
| |
+-------------------------------------+ | |
|Version-Controlled Configuration |<--+ |
|/repo/vcc/128 | |
|-------------------------------------| |
|DAV:baseline-controlled-collection +-------+
|-------------------------------------|
|DAV:checked-in +-------+
+-------------------------------------+ |
|DAV:version-history +---+ |
+-------------------------------------+ | |
| |
| |
+------------------------+ | |
|Baseline History |<---------------+ |
|/repo/blh/13 | |
|------------------------+ |
|DAV:version-set +----------------+ |
+------------------------+ | | | | |
v | v v |
| |
+------------------------+ | |
|Baseline |<-------+-----------+
|/repo/blh/13/ver/8 |
|------------------------+ +--------------+
|DAV:baseline-collection +---->|Collection |
+------------------------+ |/repo/bc/15 |
+--------------+
In order to create new baselines of /src, /repo/vcc/128 can be
checked out, new versions can be created or selected by the version-
controlled members of /src, and then /repo/vcc/128 can be checked in
to capture the current state of those version-controlled members.
12.7 DAV:compare-baseline Report
A DAV:compare-baseline report contains the differences between the
baseline identified by the request-URL (the "request baseline") and
the baseline specified in the request body (the "compare baseline").
Marshalling:
The request body MUST be a DAV:compare-baseline XML element.
<!ELEMENT compare-baseline (href)>
The response body for a successful request MUST be a DAV:compare-
baseline-report XML element.
<!ELEMENT compare-baseline-report
(added-version | deleted-version | changed-version)*>
A DAV:added-version element identifies a version that is the
DAV:checked-in version of a member of the DAV:baseline-collection
of the compare baseline, but no version in the version history of
that version is the DAV:checked-in version of a member of the
DAV:baseline-collection of the request baseline.
<!ELEMENT added-version (href)>
A DAV:deleted-version element identifies a version that is the
DAV:checked-in version of a member of the DAV:baseline-collection
of the request baseline, but no version in the version history of
that version is the DAV:checked-in version of a member of the
DAV:baseline-collection of the compare baseline.
<!ELEMENT deleted-version (href)>
A DAV:changed-version element identifies two different versions
from the same version history that are the DAV:checked-in version
of the DAV:baseline-collection of the request baseline and the
compare baseline, respectively.
<!ELEMENT changed-version (href, href)>
Preconditions:
(DAV:must-be-baseline): The DAV:href in the request body MUST
identify a baseline.
(DAV:baselines-from-same-history): A server MAY require that the
baselines being compared be from the same baseline history.
12.7.1 Example - DAV:compare-baseline Report
>>REQUEST
REPORT /bl-his/12/bl/14 HTTP/1.1
Host: repo.webdav.com
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:compare-baseline xmlns:D="DAV:">
<D:href>http://repo.webdav.org/bl-his/12/bl/15</D:href>
</D:compare-baseline>
>>RESPONSE
HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:compare-baseline-report xmlns:D="DAV:">
<D:added-version>
<D:href>http://repo.webdav.org/his/23/ver/8</D:href>
</D:added-version>
<D:changed-version>
<D:href>http://repo.webdav.org/his/29/ver/12</D:href>
<D:href>http://repo.webdav.org/his/29/ver/19</D:href>
</D:changed-version>
<D:deleted-version>
<D:href>http://repo.webdav.org/his/12/ver/4</D:href>
</D:deleted-version>
</D:compare-baseline-report>
In this example, the differences between baseline 14 and baseline 15
of http://repo.webdav.org/bl-his/12 are identified.
12.8 Additional OPTIONS Semantics
If a server supports the baseline feature, it MUST include "baseline"
as a field in the DAV response header from an OPTIONS request on any
resource that supports any versioning properties, reports, or
methods.
12.9 Additional MKCOL Semantics
Additional Postconditions:
If a server automatically puts a newly created collection under
baseline control, all postconditions for BASELINE-CONTROL apply to
the MKCOL.
12.10 Additional COPY Semantics
Additional Postconditions:
If the request creates a new collection at the Destination, and a
server automatically puts a newly created collection under
baseline control, all postconditions for BASELINE-CONTROL apply to
the COPY.
12.11 Additional CHECKOUT Semantics
Additional Preconditions:
(DAV:must-not-update-baseline-collection): If the request-URL
identifies a member of the configuration rooted at the
DAV:baseline-collection of a baseline, the request MUST fail.
12.12 Additional CHECKIN Semantics
Additional Preconditions:
(DAV:no-checked-out-baseline-controlled-collection-members): If
the request-URL identifies a version-controlled configuration, all
version-controlled members of the DAV:baseline-controlled-
collection of the version-controlled configuration MUST be
checked-in.
(DAV:one-version-per-history-per-baseline): If the request-URL
identifies a version-controlled configuration, the set of versions
selected by that version-controlled configuration MUST contain at
most one version from any version history, where a version is
selected by a version-controlled configuration if the version is
identified by the DAV:checked-in property of any member of the
configuration rooted at the DAV:baseline-controlled collection of
that version-controlled configuration, or is identified by the
DAV:checked-in property of any member of the configuration rooted
at the DAV:baseline-collection of any subbaseline of that
version-controlled configuration.
(DAV:cannot-modify-version-controlled-configuration): If the
request-URL identifies a version-controlled member of a baseline-
controlled collection whose version-controlled configuration is
checked-in, the request MUST fail unless the DAV:auto-version
property of the version-controlled configuration will
automatically check out that version-controlled configuration when
it is modified.
Additional Postconditions:
(DAV:create-baseline-collection): If the request-URL identifies a
version-controlled configuration, the DAV:baseline-collection of
the new baseline identifies a collection whose members have the
same relative name and DAV:checked-in version as the members of
the DAV:baseline-controlled-collection of the version-controlled
configuration at the time of the request.
(DAV:modify-configuration): If the request-URL identifies a
version-controlled member of a baseline-controlled collection,
this is a modification to the version-controlled configuration of
that baseline-controlled collection, and standard auto-versioning
semantics apply.
12.13 Additional UPDATE Semantics
Additional Preconditions:
(DAV:baseline-controlled-members-must-be-checked-in): If the
request-URL identifies a version-controlled configuration, then
all version-controlled members of the DAV:baseline-controlled-
collection of that version-controlled configuration MUST be
checked-in.
(DAV:must-not-update-baseline-collection): If the request-URL
identifies a member of the configuration rooted at the
DAV:baseline-collection of a baseline, the request MUST fail.
(DAV:cannot-modify-version-controlled-configuration): If the
request updates the DAV:checked-in property of any version-
controlled member of a baseline-controlled collection whose
version-controlled configuration is checked-in, the request MUST
fail unless the DAV:auto-version property of the version-
controlled configuration will automatically check out that
version-controlled configuration when it is modified.
Additional Postconditions:
(DAV:set-baseline-controlled-collection-members): If the request
updated the DAV:checked-in property of a version-controlled
configuration, then the version-controlled members of the
DAV:baseline-controlled-collection of that version-controlled
configuration MUST have been updated so that they have the same
relative name, content, and dead properties as the members of the
DAV:baseline-collection of the baseline. In particular:
- A version-controlled member for a given version history MUST
have been deleted if there is no version-controlled member for
that version history in the DAV:baseline-collection of the
baseline.
- A version-controlled member for a given version history MUST
have been renamed if its name relative to the baseline-
controlled collection is different from that of the version-
controlled member for that version history in the
DAV:baseline-collection of the baseline.
- A new version-controlled member MUST have been created for each
member of the DAV:baseline-collection of the baseline for which
there is no corresponding version-controlled member in the
baseline-controlled collection.
- An UPDATE request MUST have been applied to each version-
controlled member for a given version history whose
DAV:checked-in version is not the same as that of the version-
controlled member for that version history in the
DAV:baseline-collection of the baseline.
(DAV:update-subbaselines): If the request updated a version-
controlled configuration whose DAV:baseline-controlled-collection
contains a baseline-controlled member for one of the subbaselines
of the request baseline, then the DAV:checked-in property of the
version-controlled configuration of that baseline-controlled
member MUST have been updated to be that subbaseline. If the
request updated a version-controlled configuration whose
DAV:baseline-controlled-collection is a member of a workspace that
contains a baseline-controlled member for one of the subbaselines
of the request baseline, then the DAV:checked-in property of the
version-controlled configuration of that baseline-controlled
member MUST have been updated to be that subbaseline.
(DAV:modify-configuration): If the request updated the
DAV:checked-in property of any version-controlled member of a
baseline-controlled collection, and if this DAV:checked-in
property differs from the DAV:checked-in property of the
corresponding version-controlled member of the DAV:baseline-
collection of the DAV:checked-in baseline of the DAV:version-
controlled-configuration of the baseline-controlled collection,
then this is a modification to that version-controlled
configuration, and standard auto-versioning semantics apply.
12.14 Additional MERGE Semantics
If the merge source is a baseline, the merge target is a version-
controlled configuration for the baseline history of that baseline,
where the baseline-controlled collection of that version-controlled
configuration is a member of the collection identified by the
request-URL.
Additional Preconditions:
(DAV:must-not-update-baseline-collection): Same semantics as
UPDATE (see Section 12.13).
(DAV:cannot-modify-version-controlled-configuration): Same
semantics as UPDATE (see Section 12.13).
Additional Postconditions:
(DAV:merge-baseline): If the merge target is a version-controlled
configuration whose DAV:checked-out baseline is not a descendant
of the merge baseline, then the merge baseline MUST have been
added to the DAV:auto-merge-set of a version-controlled
configuration. The DAV:checked-in version of each member of the
DAV:baseline-collection of that baseline MUST have been merged
into the DAV:baseline-controlled-collection of that version-
controlled configuration.
(DAV:merge-subbaselines): If the merge target is a version-
controlled configuration whose DAV:baseline-controlled-collection
contains a baseline-controlled member for one of the subbaselines
of the merge baseline, then that subbaseline MUST have been merged
into the version-controlled configuration of that baseline-
controlled member. If the merge target is a version-controlled
configuration whose DAV:baseline-controlled-collection is a member
of a workspace that contains a baseline-controlled member for one
of the subbaselines of the merge baseline, then that subbaseline
MUST have been merged into the version-controlled configuration of
that baseline-controlled member.
(DAV:set-baseline-controlled-collection-members): Same semantics
as UPDATE (see Section 12.13).
(DAV:modify-configuration): Same semantics as UPDATE (see Section
12.13).
13 Activity Feature
An activity is a resource that selects a set of versions that are on
a single "line of descent", where a line of descent is a sequence of
versions connected by successor relationships. If an activity
selects versions from multiple version histories, the versions
selected in each version history must be on a single line of descent.
A common problem that motivates the use of activities is that it is
often desirable to perform several different logical changes in a
single workspace, and then selectively merge a subset of those
logical changes to other workspaces. An activity can be used to
represent a single logical change, where an activity tracks all the
resources that were modified to effect that single logical change.
When a version-controlled resource is checked out, the user specifies
which activity should be associated with a new version that will be
created when that version-controlled resource is checked in. It is
then possible to select a particular logical change for merging into
another workspace, by specifying the appropriate activity in a MERGE
request.
Another common problem is that although a version-controlled resource
may need to have multiple lines of descent, all work done by members
of a given team must be on a single line of descent (to avoid merging
between team members). An activity resource provides the mechanism
for addressing this problem. When a version-controlled resource is
checked out, a client can request that an existing activity be used
or that a new activity be created. Activity semantics then ensure
that all versions in a given version history that are associated with
an activity are on a single line of descent. If all members of a
team share a common activity (or sub-activities of a common
activity), then all changes made by members of that team will be on a
single line of descent.
The following diagram illustrates activities. Version V5 is the
latest version of foo.html selected by activity Act-2, and version V8
is the latest version of bar.html selected by activity Act-2.
foo.html History bar.html History
+---+ +---+
Act-1| |V1 Act-1| |V6
+---+ +---+
| |
| |
+---+ +---+
Act-1| |V2 Act-2| |V7
+---+ +---+
/ \ |
/ \ |
+---+ +---+ +---+
Act-1| |V3 Act-2| |V4 Act-2| |V8
+---+ +---+ +---+
| |
| |
+---+ +---+
Act-2| |V5 Act-3| |V9
+---+ +---+
Activities appear under a variety of names in existing versioning
systems. When an activity is used to capture a logical change, it is
commonly called a "change set". When an activity is used to capture
a line of descent, it is commonly called a "branch". When a system
supports both branches and change sets, it is often useful to require
that a particular change set occur on a particular branch. This
relationship can be captured by making the change set activity be a
"subactivity" of the branch activity.
13.1 Activity Properties
The DAV:resourcetype of an activity MUST be DAV:activity.
The activity feature introduces the following REQUIRED properties for
an activity.
13.1.1 DAV:activity-version-set (computed)
This property identifies each version whose DAV:activity-set property
identifies this activity. Multiple versions of a single version
history can be selected by an activity's DAV:activity-version-set
property, but all DAV:activity-version-set versions from a given
version history must be on a single line of descent from the root
version of that version history.
<!ELEMENT activity-version-set (href*)>
13.1.2 DAV:activity-checkout-set (computed)
This property identifies each checked-out resource whose
DAV:activity-set identifies this activity.
<!ELEMENT activity-checkout-set (href*)>
13.1.3 DAV:subactivity-set
This property identifies each activity that forms a part of the
logical change being captured by this activity. An activity behaves
as if its DAV:activity-version-set is extended by the DAV:activity-
version-set of each activity identified in the DAV:subactivity-set.
In particular, the versions in this extended set MUST be on a single
line of descent, and when an activity selects a version for merging,
the latest version in this extended set is the one that will be
merged.
A server MAY reject attempts to modify the DAV:subactivity-set of an
activity.
<!ELEMENT subactivity-set (href*)>
13.1.4 DAV:current-workspace-set (computed)
This property identifies each workspace whose DAV:current-activity-
set identifies this activity.
<!ELEMENT current-workspace-set (href*)>
13.2 Additional Version Properties
The activity feature introduces the following REQUIRED property for a
version.
13.2.1 DAV:activity-set
This property identifies the activities that determine to which
logical changes this version contributes, and on which lines of
descent this version appears. A server MAY restrict the
DAV:activity-set to identify a single activity. A server MAY refuse
to allow the value of the DAV:activity-set property of a version to
be modified.
<!ELEMENT activity-set (href*)>
13.3 Additional Checked-Out Resource Properties
The activity feature introduces the following REQUIRED properties for
a checked-out resource.
13.3.1 DAV:unreserved
This property of a checked-out resource indicates whether the
DAV:activity-set of another checked-out resource associated with the
version history of this version-controlled resource can have an
activity that is in the DAV:activity-set property of this checked-out
resource.
A result of the requirement that an activity must form a single line
of descent through a given version history is that if multiple
checked-out resources for a given version history are checked out
unreserved into a single activity, only the first CHECKIN will
succeed. Before another of these checked-out resources can be
checked in, the user will first have to merge into that checked-out
resource the latest version selected by that activity from that
version history, and then modify the DAV:predecessor-set of that
checked-out resource to identify that version.
<!ELEMENT unreserved (#PCDATA)>
PCDATA value: boolean
13.3.2 DAV:activity-set
This property of a checked-out resource determines the DAV:activity-
set property of the version that results from checking in this
resource.
13.4 Additional Workspace Properties
The activity feature introduces the following REQUIRED property for a
workspace.
13.4.1 DAV:current-activity-set
This property identifies the activities that currently are being
performed in this workspace. When a member of this workspace is
checked out, if no activity is specified in the checkout request, the
DAV:current-activity-set will be used. This allows an activity-
unaware client to update a workspace in which activity tracking is
required. The DAV:current-activity-set MAY be restricted to identify
at most one activity.
<!ELEMENT current-activity-set (href*)>
13.5 MKACTIVITY Method
A MKACTIVITY request creates a new activity resource. A server MAY
restrict activity creation to particular collections, but a client
can determine the location of these collections from a DAV:activity-
collection-set OPTIONS request.
Marshalling:
If a request body is included, it MUST be a DAV:mkactivity XML
element.
<!ELEMENT mkactivity ANY>
If a response body for a successful request is included, it MUST
be a DAV:mkactivity-response XML element.
<!ELEMENT mkactivity-response ANY>
The response MUST include a Cache-Control:no-cache header.
Preconditions:
(DAV:resource-must-be-null): A resource MUST NOT exist at the
request-URL.
(DAV:activity-location-ok): The request-URL MUST identify a
location where an activity can be created.
Postconditions:
(DAV:initialize-activity): A new activity exists at the request-
URL. The DAV:resourcetype of the activity MUST be DAV:activity.
13.5.1 Example - MKACTIVITY
>>REQUEST
MKACTIVITY /act/test-23 HTTP/1.1
Host: repo.webdav.org
Content-Length: 0
>>RESPONSE
HTTP/1.1 201 Created
Cache-Control: no-cache
In this example, a new activity is created at
http://repo.webdav.org/act/test-23.
13.6 DAV:latest-activity-version Report
The DAV:latest-activity-version report can be applied to a version
history to identify the latest version that is selected from that
version history by a given activity.
Marshalling:
The request body MUST be a DAV:latest-activity-version XML
element.
<!ELEMENT latest-activity-version (href)>
The response body for a successful request MUST be a DAV:latest-
activity-version-report XML element.
<!ELEMENT latest-activity-version-report (href)>
The DAV:href of the response body MUST identify the version of the
given version history that is a member of the DAV:activity-
version-set of the given activity and has no descendant that is a
member of the DAV:activity-version-set of that activity.
Preconditions:
(DAV:must-be-activity): The DAV:href in the request body MUST
identify an activity.
13.7 Additional OPTIONS Semantics
If the server supports the activity feature, it MUST include
"activity" as a field in the DAV response header from an OPTIONS
request on any resource that supports any versioning properties,
reports, or methods.
A DAV:activity-collection-set element MAY be included in the request
body to identify collections that may contain activity resources.
Additional Marshalling:
If an XML request body is included, it MUST be a DAV:options XML
element.
<!ELEMENT options ANY>
ANY value: A sequence of elements with at most one
DAV:activity-collection-set element.
If an XML response body for a successful request is included, it
MUST be a DAV:options-response XML element.
<!ELEMENT options-response ANY>
ANY value: A sequence of elements with at most one
DAV:activity-collection-set element.
<!ELEMENT activity-collection-set (href*)>
If DAV:activity-collection-set is included in the request body,
the response body for a successful request MUST contain a
DAV:activity-collection-set element identifying collections that
may contain activities. An identified collection MAY be the root
collection of a tree of collections, all of which may contain
activities. Since different servers can control different parts
of the URL namespace, different resources on the same host MAY
have different DAV:activity-collection-set values. The identified
collections MAY be located on different hosts from the resource.
13.8 Additional DELETE Semantics
Additional Postconditions:
(DAV:delete-activity-reference): If an activity is deleted, any
reference to that activity in a DAV:activity-set,
DAV:subactivity-set, or DAV:current-activity-set MUST be removed.
13.9 Additional MOVE Semantics
Additional Postconditions:
(DAV:update-checked-out-reference): If a checked-out resource is
moved, any reference to that resource in a DAV:activity-checkout-
set property MUST be updated to refer to the new location of that
resource.
(DAV:update-activity-reference): If the request-URL identifies an
activity, any reference to that activity in a DAV:activity-set,
DAV:subactivity-set, or DAV:current-activity-set MUST be updated
to refer to the new location of that activity.
(DAV:update-workspace-reference): If the request-URL identifies a
workspace, any reference to that workspace in a DAV:current-
workspace-set property MUST be updated to refer to the new
location of that workspace.
13.10 Additional CHECKOUT Semantics
A CHECKOUT request MAY specify the DAV:activity-set for the checked-
out resource.
Additional Marshalling:
<!ELEMENT checkout ANY> ANY value: A sequence of elements with at
most one DAV:activity-set and at most one DAV:unreserved.
<!ELEMENT activity-set (href+ | new)>
<!ELEMENT new EMPTY>
<!ELEMENT unreserved EMPTY>
Additional Preconditions:
(DAV:one-checkout-per-activity-per-history): If there is a request
activity set, unless DAV:unreserved is specified, another checkout
from a version of that version history MUST NOT select an activity
in that activity set.
(DAV:linear-activity): If there is a request activity set, unless
DAV:unreserved is specified, the selected version MUST be a
descendant of all other versions of that version history that
select that activity.
Additional Postconditions:
(DAV:initialize-activity-set): The DAV:activity-set of the
checked-out resource is set as follows:
- If DAV:new is specified as the DAV:activity-set in the request
body, then a new activity created by the server is used.
- Otherwise, if activities are specified in the request body,
then those activities are used.
- Otherwise, if the version-controlled resource is a member of a
workspace and the DAV:current-activity-set of the workspace is
set, then those activities are used.
- Otherwise, the DAV:activity-set of the DAV:checked-out version
is used.
(DAV:initialize-unreserved): If DAV:unreserved was specified in
the request body, then the DAV:unreserved property of the
checked-out resource MUST be "true".
13.10.1 Example - CHECKOUT with an activity
>>REQUEST
CHECKOUT /ws/public/foo.html HTTP/1.1
Host: www.webdav.org
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:checkout xmlns:D="DAV:">
<D:activity-set>
<D:href>http://repo.webdav.org/act/fix-bug-23</D:href>
</D:activity-set>
</D:checkout>
>>RESPONSE
HTTP/1.1 200 OK
Cache-Control: no-cache
In this example, the CHECKOUT is being performed in the
http://repo.webdav.org/act/fix-bug-23 activity.
13.11 Additional CHECKIN Semantics
Additional Preconditions:
(DAV:linear-activity): Any version which is in the version history
of the checked-out resource and whose DAV:activity-set identifies
an activity from the DAV:activity-set of the checked-out resource
MUST be an ancestor of the checked-out resource.
(DAV:atomic-activity-checkin): If the request-URL identifies an
activity, the server MAY fail the request if any of the checked-
out resources in the DAV:activity-checkout-set of either that
activity or any subactivity of that activity cannot be checked in.
Additional Postconditions:
(DAV:initialize-activity-set): The DAV:activity-set of the new
version MUST have been initialized to be the same as the
DAV:activity-set of the checked-out resource.
(DAV:activity-checkin): If the request-URL identified an activity,
the server MUST have successfully applied the CHECKIN request to
each checked-out resource in the DAV:activity-checkout-set of both
that activity and any subactivity of that activity.
13.12 Additional MERGE Semantics
If the DAV:source element of the request body identifies an activity,
then for each version history containing a version selected by that
activity, the latest version selected by that activity is a merge
source. Note that the versions selected by an activity are the
versions in its DAV:activity-version-set unioned with the versions
selected by the activities in its DAV:subactivity-set.
Additional Marshalling:
<!ELEMENT checkin-activity EMPTY>
Additional Postconditions:
(DAV:checkin-activity): If DAV:checkin-activity is specified in
the request body, and if the DAV:source element in the request
body identifies an activity, a CHECKIN request MUST have been
successfully applied to that activity before the merge sources
were determined.
14 Version-Controlled-Collection Feature
As with any versionable resource, when a collection is put under
version control, a version history resource is created to contain
versions for that version-controlled collection. In order to
preserve standard versioning semantics (a version of a collection
should not be modifiable), a collection version only records
information about the version-controlled bindings of that collection.
In order to cleanly separate a modification to the namespace from a
modification to content or dead properties, a version of a collection
has no members, but instead records in its DAV:version-controlled-
binding-set property the binding name and version history resource of
each version-controlled internal member of that collection. If,
instead, a collection version contained bindings to other versions,
creating a new version of a resource would require creating a new
version of all the collection versions that contain that resource,
which would cause activities to become entangled. For example,
suppose a "feature-12" activity created a new version of /x/y/a.html.
If a collection version contained bindings to versions of its
members, a new version of /x/y would have to be created to contain
the new version of /x/y/a.html, and a new version of /x would have to
be created to contain the new version of /x/y. Now suppose a
"bugfix-47" activity created a new version of /x/z/b.html. Again, a
new version of /x/z and a new version of /x would have to be created
to contain the new version of /x/y/b.html. But now it is impossible
to merge just "bugfix-47" into another workspace without "feature-
12", because the version of /x that contains the desired version of
/x/z/b.html also contains version of /x/y/a.html created for
"feature-12". If, instead, a collection version just records the
binding name and version history resource of each version-controlled
internal member, changing the version selected by a member of that
collection would not require a new version of the collection. The
new version is still in the same version history so no new collection
version is required, and "feature-12" and "bugfix-47" would not
become entangled.
In the following example, there are three version histories, named
VH14, VH19, and VH24, where VH14 contains versions of a collection.
The version-controlled collection /x has version V2 of version
history VH14 as its DAV:checked-in version. Since V2 has recorded
two version controlled bindings, one with binding name "a" to version
history VH19, and the other with binding name "b" to version history
VH24, /x MUST have two version-controlled bindings, one named "a" to
a version-controlled resource for history VH19, and the other named
"b" to a version-controlled resource for history VH24. The version-
controlled resource /x/a currently has V4 of VH19 as its
DAV:checked-in version, while /x/b has V8 of VH24 as its
DAV:checked-in version.
VH19
+---------+
| +---+ |
| | |V4 |
| +---+ |
| | |
| | |
| +---+ |
| | |V5 |
VH14 | +---+ |
+---------+ | | |
| +---+ | | | |
a +---+ | | |V1 | | +---+ |
---->| |checked-in=V4 | +---+ | a | | |V6 |
/ +---+ | | ------>| +---+ |
/ | | / | +---------+
+---+ | +---+ |
/x | |checked-in=V2 | | |V2 |
+---+ | +---+ | VH24
\ | | \ | b +---------+
\ b +---+ | | ------>| +---+ |
---->| |checked-in=V8 | +---+ | | | |V7 |
+---+ | | |V3 | | +---+ |
| +---+ | | | |
+---------+ | | |
| +---+ |
| | |V8 |
| +---+ |
| | |
| | |
| +---+ |
| | |V9 |
| +---+ |
+---------+
For any request (e.g., DELETE, MOVE, COPY) that modifies a version-
controlled binding of a checked-in version-controlled collection, the
request MUST fail unless the version-controlled collection has a
DAV:auto-version property that will automatically check out the
version-controlled collection when it is modified.
Although a collection version only records the version-controlled
bindings of a collection, a version-controlled collection MAY contain
both version-controlled and non-version-controlled bindings. Non-
version-controlled bindings are not under version control, and
therefore can be added or deleted without checking out the version-
controlled collection.
Note that a collection version captures only a defined subset of the
state of a collection. In particular, a version of a collection
captures its dead properties and its bindings to version-controlled
resources, but not its live properties or bindings to non-version-
controlled resources.
When a server supports the working-resource feature, a client can
check out a collection version to create a working collection.
Unlike a version-controlled collection, which contains bindings to
version-controlled resources and non-version-controlled resources, a
working collection contains bindings to version history resources and
non-version-controlled resources. In particular, a working
collection is initialized to contain bindings to the version history
resources specified by the DAV:version-controlled-binding-set of the
checked out collection version. The members of a working collection
can then be deleted or moved to another working collection. Non-
version-controlled resources can be added to a working collection
with methods such as PUT, COPY, and MKCOL. When a working collection
is checked in, a VERSION-CONTROL request is automatically applied to
every non-version-controlled member of the working collection, and
each non-version-controlled member is replaced by its newly created
version history. The DAV:version-controlled-binding-set of the new
version resulting from checking in a working collection contains the
binding name and version history URL for each member of the working
collection.
14.1 Version-Controlled Collection Properties
A version-controlled collection has all the properties of a
collection and of a version-controlled resource. In addition, the
version-controlled-collection feature introduces the following
REQUIRED property for a version-controlled collection.
14.1.1 DAV:eclipsed-set (computed)
This property identifies the non-version-controlled internal members
of the collection that currently are eclipsing a version-controlled
internal member of the collection.
!ELEMENT eclipsed-set (binding-name*)>
<!ELEMENT binding-name (#PCDATA)>
PCDATA value: URL segment
An UPDATE or MERGE request can give a version-controlled collection a
version-controlled internal member that has the same name as an
existing non-version-controlled internal member. In this case, the
non-version-controlled internal member takes precedence and is said
to "eclipse" the new versioned-controlled internal member. If the
non-version-controlled internal member is removed (e.g., by a DELETE
or MOVE), the version-controlled internal member is exposed.
14.2 Collection Version Properties
A collection version has all the properties of a version. In
addition, the version-controlled-collection feature introduces the
following REQUIRED property for a collection version.
14.2.1 DAV:version-controlled-binding-set (protected)
This property captures the name and version-history of each version-
controlled internal member of a collection.
<!ELEMENT version-controlled-binding-set
(version-controlled-binding*)>
<!ELEMENT version-controlled-binding
(binding-name, version-history)>
<!ELEMENT binding-name (#PCDATA)>
PCDATA value: URL segment
<!ELEMENT version-history (href)>
14.3 Additional OPTIONS Semantics
If the server supports the version-controlled-collection feature, it
MUST include "version-controlled-collection" as a field in the DAV
response header from an OPTIONS request on any resource that supports
any versioning properties, reports, or methods.