001/*
002 * file Activity.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM
006 * 
007 * (c) Copyright IBM Corporation 2004, 2008.  All Rights Reserved. 
008 * Note to U.S. Government Users Restricted Rights:  Use, duplication or  
009 * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp. 
010 */
011package javax.wvcm;
012
013import javax.wvcm.PropertyNameList.PropertyName;
014import javax.wvcm.WvcmException.ReasonCode;
015
016/**
017 * A proxy for an activity resource.
018 *
019 * An activity resource selects a set of versions that are on a single
020 * "line of descent", where a line of descent is a sequence of versions
021 * connected by successor relationships.
022 * Activities appear under a variety of names in existing versioning systems.
023 * When an activity is used to capture a logical change, it is commonly called
024 * a "change set".  When an activity is used to capture a line of descent,
025 * it is commonly called a "branch".
026 * 
027 * @since 1.0
028 */
029public interface Activity extends Resource {
030
031    /**
032     * Get the workspace provider of this resource.
033     * 
034     * @return the {@link WorkspaceProvider} for this Resource.
035     */
036    public WorkspaceProvider workspaceProvider();
037
038    /**
039     * Create a new persistent activity.
040     * <p>
041     * Postconditions:
042     * <li>(initialize-resource): A new activity exists at the location of this Resource.
043     * 
044     * @param feedback Specifies optional feedback to the caller.
045     * @return A proxy for this new resource, whose properties are specified by feedback.
046     * @throws WvcmException ReasonCode:
047     * <li>{@link ReasonCode#RESOURCE_ALREADY_EXISTS_AT_LOCATION}:
048     *  If a resource already 
049     *  exists at the location of this Resource, the request MUST fail.
050     * <li>{@link ReasonCode#CANNOT_CREATE_AT_THIS_LOCATION}:
051     *  If the location of this Activity
052     *  does not identify a valid location to create an activity, the request MUST fail.
053     *  A client can use {@link #doCreateGeneratedResource} if it does not know a valid
054     *  location for creating an activity.
055     */
056    public Activity doCreateResource(Feedback feedback) throws WvcmException;
057
058    /**
059     * Create a new persistent activity, where the provider can allocate the location for the
060     * new activity.
061     * The provider should use the client-specified location if it is valid,
062     * but can select a different location if the location is not valid
063     * or already identifies an activity.
064     * <p>
065     * Postconditions:
066     * <li>(initialize-resource): A new activity resource exists at the location of this Resource.
067     * 
068     * @param feedback Specifies optional feedback to the caller.
069     * @return A proxy for this new resource, whose properties are specified by feedback.
070     * @throws WvcmException ReasonCode:
071     * <li>{@link ReasonCode#METHOD_NOT_SUPPORTED}:
072     *  If the provider does not support the creation of activities, this request MUST fail.
073     *  A client can determine a valid location for this method
074     *  with a {@link Provider#rootLocation()} request.
075     */
076    public Activity doCreateGeneratedResource(Feedback feedback) throws WvcmException;
077
078    /**
079     * The computed inverse of the {@link ControllableResource#ACTIVITY} property.
080     */
081    public static final PropertyName<ResourceList<ControllableResource>> ACTIVITY_CHECKOUT_LIST =
082        new PropertyName<ResourceList<ControllableResource>>("activity-checkout-list"); //$NON-NLS-1$
083
084    /**
085     * Get the {@link #ACTIVITY_CHECKOUT_LIST} property.
086     * 
087     * @return the {@link #ACTIVITY_CHECKOUT_LIST} property.
088     * @throws WvcmException if this Activity was not created with 
089     * {@link #ACTIVITY_CHECKOUT_LIST} as a wanted property.
090     */
091    public ResourceList<ControllableResource> getActivityCheckoutList()
092        throws WvcmException;
093
094    /**
095     * The computed inverse of the {@link Version#ACTIVITY} property.
096     * Multiple versions of a single version history can be selected by an activity's
097     * {@link #ACTIVITY_VERSION_LIST} property, but all {@link #ACTIVITY_VERSION_LIST} versions
098     * from a given version history must be on a single line of descent from 
099     * the root version of that version history. 
100     */
101    public static final PropertyName<ResourceList<Version>> ACTIVITY_VERSION_LIST =
102        new PropertyName<ResourceList<Version>>("activity-version-list"); //$NON-NLS-1$
103
104    /**
105     * Get the {@link #ACTIVITY_VERSION_LIST} property.
106     * 
107     * @return the {@link #ACTIVITY_VERSION_LIST} property.
108     * @throws WvcmException if this Activity was not created with
109     * {@link #ACTIVITY_VERSION_LIST} as a wanted property.
110     */
111    public ResourceList<Version> getActivityVersionList() throws WvcmException;
112
113    /**
114     * The computed inverse of the {@link Workspace#CURRENT_ACTIVITY} and {@link Workspace#STREAM} properties
115     * (i.e., a workspace is in the {#CURRENT_WORKSPACE_LIST} if it is identified in the
116     * {@link Workspace#CURRENT_ACTIVITY} or {@link Workspace#STREAM} of that workspace.
117     */
118    public static final PropertyName<ResourceList<Workspace>> CURRENT_WORKSPACE_LIST =
119        new PropertyName<ResourceList<Workspace>>("current-workspace-list"); //$NON-NLS-1$
120
121    /**
122     * Get the {@link #CURRENT_WORKSPACE_LIST} property.
123     * 
124     * @return the {@link #CURRENT_WORKSPACE_LIST} property.
125     * @throws WvcmException if this Activity was not created with
126     * {@link #CURRENT_WORKSPACE_LIST} as a wanted property.
127     */
128    public ResourceList<Workspace> getCurrentWorkspaceList()
129        throws WvcmException;
130
131    /**
132     * The result of {@link VersionHistory#doLatestActivityVersionReport}
133     * on each VersionHistory with a version in {@link #ACTIVITY_VERSION_LIST}.
134     */
135    public static final PropertyName<ResourceList<Version>> LATEST_VERSION_LIST =
136        new PropertyName<ResourceList<Version>>("latest-version-list"); //$NON-NLS-1$
137
138    /**
139     * Get the {@link #LATEST_VERSION_LIST} property.
140     * 
141     * @return the {@link #LATEST_VERSION_LIST} property.
142     * @throws WvcmException if this Activity was not created with
143     * {@link #LATEST_VERSION_LIST} as a wanted property.
144     */
145    public ResourceList<Version> getLatestVersionList() throws WvcmException;
146
147    /**
148     * The tasks that this activity is performing.
149     */
150    public static final PropertyName<ResourceList<Task>> TASK_LIST =
151        new PropertyName<ResourceList<Task>>("task-list"); //$NON-NLS-1$
152
153    /**
154     * Get the {@link #TASK_LIST} property.
155     * 
156     * @return the {@link #TASK_LIST} property.
157     * @throws WvcmException if this Activity was not created with
158     * {@link #TASK_LIST} as a wanted property.
159     */
160    public ResourceList<Task> getTaskList() throws WvcmException;
161
162    /**
163     * Set the {@link #TASK_LIST} property.
164     * 
165     * @param taskList The list of tasks that are being performed by this activity.
166     * @see #getTaskList
167     */
168    public void setTaskList(ResourceList<Task> taskList);
169}
170