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 */
011 package javax.wvcm;
012
013 import javax.wvcm.PropertyNameList.PropertyName;
014 import 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 */
029 public 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