org.apache.jackrabbit.webdav.version.VersionControlledResource Maven / Gradle / Ivy

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.jackrabbit.webdav.version;

import org.apache.jackrabbit.webdav.DavException;
import org.apache.jackrabbit.webdav.MultiStatus;
import org.apache.jackrabbit.webdav.property.DavPropertyName;

/**
 * The VersionControlledResource represents in contrast to the
 * VersionableResource a resource, that has already been put
 * under version-control. This resource can be checked-in, checked-out and
 * has its own {@link VersionHistoryResource version history}.
 * 
 * RFC 3253 defines the following required properties for a
 * version-controlled resource (vc-resource):
 * 

 * DAV:auto-version
 * DAV:version-history (version-history)
 * DAV:workspace (workspace)
 * DAV:version-controlled-configuration (baseline)
 * all DeltaV-compliant resource properties.
 * 
 *
 * checked-in vc-resource:
 * 
 * DAV:checked-in
 * 
 *
 * checked-out vc-resource:
 * 
 * DAV:checked-out
 * DAV:predecessor-set
 * DAV:checkout-fork (in-place-checkout or working resource)
 * DAV:checkin-fork (in-place-checkout or working resource)
 * DAV:merge-set (merge)
 * DAV:auto-merge-set (merge)
 * DAV:unreserved (activity)
 * DAV:activity-set (activity)
 * 
 *
 * If the Version-Controlled-Collection feature is supported (see section 14
 * of RFC 3253) the following computed property is required:
 * 
 * DAV:eclipsed-set
 * 
 *
 * If the Baseline feature is supported (see section 12 of RFC 3253), a version-
 * controlled resource may represent a 'configuration' rather than a single
 * resource. In this case the RFC defines the following required properties:
 * 
 * DAV:baseline-controlled-collection
 * DAV:subbaseline-set (if the configuration resource is checked-out)
 * 
 *
 * 
 * In addition a version-controlled resource must support the following METHODS:
 * 

 * VERSION-CONTROL
 * MERGE (merge)
 * all DeltaV-compliant resource METHODS.
 * 
 *
 * checked-in vc-resource:
 * 
 * CHECKOUT (checkout-in-place)
 * UPDATE (update)
 * all version-controlled resource METHODS.
 * 
 *
 * checked-out vc-resource:
 * 
 * CHECKIN (checkout-in-place or working-resource)
 * UNCHECKOUT (checkout-in-place)
 * all DeltaV-compliant resource METHODS.
 * 
 *
 * @see DeltaVResource
 * @see VersionableResource
 */
public interface VersionControlledResource extends VersionableResource {

    /**
     * Methods defined for a checked-in version-controlled resource: CHECKOUT, UPDATE, MERGE, LABEL
     */
    public String methods_checkedIn = "CHECKOUT, UPDATE, MERGE, LABEL";
    /**
     * Methods defined for a checked-out version-controlled resource: CHECKIN, MERGE
     */
    public String methods_checkedOut = "CHECKIN, MERGE";

    /**
     * The DAV:auto-version property determines how it responds to a method that
     * attempts to modify its content or dead properties. Possible responses
     * include various combinations of automated checkout, write lock and checkin
     * as well as failure until the resource is explicitly checked-out.

     * See RFC 3253 for a detailed
     * description.
     */
    public static final DavPropertyName AUTO_VERSION = DavPropertyName.create("auto-version", DeltaVConstants.NAMESPACE);

    /**
     * The computed property DAV:version-history identifies the version history
     * resource for the DAV:checked-in or DAV:checked-out version of this
     * version-controlled resource.

     * The property is defined to have the following format:
     *      * <!ELEMENT version-history (href)>
     * 
     */
    public static final DavPropertyName VERSION_HISTORY = DavPropertyName.create("version-history", DeltaVConstants.NAMESPACE);

    /**
     * The DAV:checked-in property appears on a checked-in version-controlled
     * resource, and identifies the base version of this version-controlled
     * resource. This property is removed when the resource is checked out, and
     * then added back (identifying a new version) when the resource is checked
     * back in.

     * This property is defined to have the following format:
     *      * <!ELEMENT checked-in (href)>
     * 
     */
    public static final DavPropertyName CHECKED_IN = DavPropertyName.create("checked-in", DeltaVConstants.NAMESPACE);

    /**
     * The DAV:checked-out property identifies the base version of this resource.
     * It is the same that was identified by the DAV:checked-in property at the
     * time the resource was checked out. This property is removed when the
     * resource is checked in.

     * This property is defined to have the following format:
     *      * <!ELEMENT checked-out (href)>
     * 
     *
     * @see #CHECKED_IN
     */
    public static final DavPropertyName CHECKED_OUT = DavPropertyName.create("checked-out", DeltaVConstants.NAMESPACE);

    /**
     * The DAV:predecessor-set property of a version-controlled resource points
     * to those version resources, that are scheduled to become the predecessors
     * of this resource when it is back checked-in. This property is not
     * protected, however a server may reject attempts to modify the
     * DAV:predecessor-set of a version-controlled resource.

     * This property is defined to have the following format:
     *      * <!ELEMENT predecessor-set (href+)>
     * 
     *
     * @see #checkin()
     * @see VersionResource#PREDECESSOR_SET
     */
    public static final DavPropertyName PREDECESSOR_SET = DavPropertyName.create("predecessor-set", DeltaVConstants.NAMESPACE);

    /**
     *  This property determines the DAV:checkin-fork property of the version
     * that results from checking in this resource.
     */
    public static final DavPropertyName CHECKIN_FORK = DavPropertyName.create("checkin-fork", DeltaVConstants.NAMESPACE);

    /**
     * This property determines the DAV:checkout-fork property of the version
     * that results from checking in this resource.
     */
    public static final DavPropertyName CHECKOUT_FORK = DavPropertyName.create("checkout-fork", DeltaVConstants.NAMESPACE);

    /**
     * This property identifies each version that is to be merged into this
     * checked-out resource. This property is set, whenever a MERGE request
     * with the DAV:no-auto-merge flag succeeded. The client then must confirm
     * each single merge by removing the version from the DAV:merge-set or
     * moving it the the versions DAV:predecessor-set.

     * This property is defined to have the following format:
     *      * <!ELEMENT merge-set (href*)>
     * 
     *
     * @see #merge(MergeInfo)
     */
    public static final DavPropertyName MERGE_SET = DavPropertyName.create("merge-set", DeltaVConstants.NAMESPACE);

    /**
     * The DAV:auto-merge-set property identifies each version that the server
     * has merged into this checked-out resource. The client should confirm that
     * the merge has been performed correctly before moving a URL from the
     * DAV:auto-merge-set to the DAV:predecessor-set of a checked-out resource.

     * This property is defined to have the following format:
     *      * <!ELEMENT auto-merge-set (href*)>
     * 
     *
     * @see #merge(MergeInfo)
     */
    public static final DavPropertyName AUTO_MERGE_SET = DavPropertyName.create("auto-merge-set", DeltaVConstants.NAMESPACE);

    /**
     * DAV:unreserved is a property for a checked-out resource, if the server
     * supports the activity feature.

     * It 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.
     * 
     * This property is defined to have the following format:
     * 
     * <!ELEMENT unreserved (#PCDATA)>
     * PCDATA value: boolean
     * 
     * @see VersionResource#ACTIVITY_SET
     */
    public static final DavPropertyName UNRESERVED = DavPropertyName.create("activity-set", DeltaVConstants.NAMESPACE);

    /**
     * DAV:activity-set is a property for a checked-out resource, if the
     * server supports the activity feature.

     * This property determines the DAV:activity-set property of the version that
     * results from checking in this resource.
     *
     * @see VersionResource#ACTIVITY_SET
     */
    public static final DavPropertyName ACTIVITY_SET = DavPropertyName.create("activity-set", DeltaVConstants.NAMESPACE);

    /**
     * If the 'Version-Controlled-Collection Feature' is supported the
     * DAV:eclipsed-set property present on a collection identifies all
     * internal members that are not version-controlled and hide a vc internal
     * member with the same name.
     * 
     * This property is defined to have the following format:
     * 
     * <!ELEMENT eclipsed-set (binding-name*)>
     * <!ELEMENT binding-name (#PCDATA)>
     * PCDATA value: URL segment
     * 
     *
     * @see VersionResource#VERSION_CONTROLLED_BINDING_SET
     */
    public static final DavPropertyName ECLIPSED_SET = DavPropertyName.create("eclipsed-set", DeltaVConstants.NAMESPACE);

    /**
     * If the 'Baseline' feature is supported, DAV:baseline-controlled-collection
     * is a required property of any version-controlled resource, that represents
     * a 'configuration'. It identifies the collection that contains the
     * version-controlled resources whose versions are tracked by this
     * configuration.
     * 
     * This property is defined to have the following format:
     * 
     * <!ELEMENT baseline-controlled-collection (href)>
     * 
     * Note that the DAV:baseline-controlled-collection represents a
     * {@link org.apache.jackrabbit.webdav.property.HrefProperty HrefProperty}
     *
     * @see DeltaVConstants#VERSION_CONTROLLED_CONFIGURATION for the corresponding
     * property, that is required for all resources that are contained in this
     * version-controlled-configuration.
     */
    public static final DavPropertyName BASELINE_CONTROLLED_COLLECTION = DavPropertyName.create("baseline-controlled-collection", DeltaVConstants.NAMESPACE);

    /**
     * This property is mandatory for all checked-out version-controlled-configuration
     * resources. It determines the DAV:subbaseline-set property of the baseline
     * that results from checking in this resource.
     * 
     * This property is defined to have the following format:
     * 
     * <!ELEMENT subbaseline-set (href*)>
     * 
     * Note that the DAV:baseline-controlled-collection represents a
     * {@link org.apache.jackrabbit.webdav.property.HrefProperty HrefProperty}
     * @see BaselineResource#SUBBASELINE_SET
     */
    public static final DavPropertyName SUBBASELINE_SET = DavPropertyName.create("subbaseline-set", DeltaVConstants.NAMESPACE);

    /**
     * Perform a checkin on the version controlled resource.
     *
     * @return String representing the location of the version created by the
     * checkin.
     * @throws DavException if an error occurs.
     */
    public String checkin() throws DavException;

    /**
     * Perform a checkout on the version controlled resource.
     *
     * @throws DavException
     */
    public void checkout() throws DavException;

    /**
     * Perform an uncheckout on the version controlled resource.
     *
     * @throws DavException
     */
    public void uncheckout() throws DavException;

    /**
     * Perform an update on this resource using the specified {@link UpdateInfo}.
     *
     * @param updateInfo
     * @return MultiStatus containing the list of resources that
     * have been modified by this update call.
     * @throws DavException
     */
    public MultiStatus update(UpdateInfo updateInfo) throws DavException;

    /**
     * Perform a merge on this resource using the specified {@link MergeInfo}.
     *
     * @param mergeInfo
     * @return MultiStatus containing the list of resources that
     * have been modified.
     * @throws DavException
     */
    public MultiStatus merge(MergeInfo mergeInfo) throws DavException;

    /**
     * Modify the labels of the version referenced by the DAV:checked-in property
     * of this checked-in version-controlled resource. If the resource is not
     * checked-in the request must fail.
     *
     * @param labelInfo
     * @throws org.apache.jackrabbit.webdav.DavException
     * @see LabelInfo
     * @see VersionResource#label(LabelInfo) for the pre- and postcondition of
     * a successful LABEL request.
     */
    public void label(LabelInfo labelInfo) throws DavException;

    /**
     * Returns the VersionHistoryResource, that is referenced in the
     * '{@link #VERSION_HISTORY version-history}' property.
     *
     * @return
     * @throws DavException
     */
    public VersionHistoryResource getVersionHistory() throws DavException;
}