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