001 /* 002 * file Baseline.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.ResourceList.ResponseIterator; 015 import javax.wvcm.WvcmException.ReasonCode; 016 017 /** 018 * A proxy for a baseline resource. 019 * 020 * A baseline resource is a version resource that captures the state of each 021 * version-controlled member of a configuration. New baselines of a 022 * configuration are created by checking out and then checking in the 023 * configuration. 024 * 025 * @since 1.0 026 */ 027 public interface Baseline extends Version { 028 029 /** 030 * A description of the difference between two sets of versions. 031 * In the {@link Baseline#doCompareReport} method, the old set of versions is 032 * specified by the object for which the method was invoked, and the new set of versions 033 * is specified by the argument of the method. 034 */ 035 public interface CompareReport { } 036 037 /** 038 * A version from a given version history that is in the new set of versions 039 * but no version from the version history of that version is in the old set. 040 */ 041 public interface AddedVersion extends CompareReport { 042 043 /** 044 * Return the added version. 045 * 046 * @return the version of a resource added in the new set of versions. 047 */ 048 public Version getVersion(); 049 } 050 051 /** 052 * A version from a given version history that is in the old set of versions 053 * but no version from that version history is in the new set of versions. 054 */ 055 public interface DeletedVersion extends CompareReport { 056 057 /** 058 * Return the deleted version. 059 * 060 * @return the version of a resource removed from the new set of versions. 061 */ 062 public Version getVersion(); 063 } 064 065 /** 066 * A version from a given version history that is in the old set of versions 067 * where a different version from that version history is in the new set of versions. 068 * @see Baseline#doCompareReport doCompareReport 069 */ 070 public interface ChangedVersion extends CompareReport { 071 072 /** 073 * Return the version from the old baseline. 074 * 075 * @return the version of the resource in the old baseline. 076 */ 077 public Version getOldVersion(); 078 079 /** 080 * Return the version from the new baseline. 081 * 082 * @return the version of the resource in the new baseline. 083 */ 084 public Version getNewVersion(); 085 } 086 087 /** 088 * An activity whose versions were added by the new set of versions. 089 */ 090 public interface AddedActivity extends CompareReport { 091 092 /** 093 * Return the added activity. 094 * 095 * @return the activity all of whose versions were added by the new set of versions. 096 */ 097 public Activity getActivity(); 098 } 099 100 /** 101 * An activity some of whose versions were added by the new set of versions. 102 */ 103 public interface PartiallyAddedActivity extends CompareReport { 104 105 /** 106 * Return the partially added activity. 107 * 108 * @return the activity some of whose versions were added by the new set of versions. 109 */ 110 public Activity getActivity(); 111 } 112 113 /** 114 * An activity whose versions were deleted by the new baseline. 115 */ 116 public interface DeletedActivity extends CompareReport { 117 118 /** 119 * Return the deleted activity. 120 * 121 * @return the activity whose versions were deleted by the new set of versions. 122 */ 123 public Activity getActivity(); 124 } 125 126 /** 127 * An activity some of whose versions were deleted by the new set of versions. 128 */ 129 public interface PartiallyDeletedActivity extends CompareReport { 130 131 /** 132 * Return the partially deleted activity. 133 * 134 * @return the activity some of whose versions were deleted by the new set of versions. 135 */ 136 public Activity getActivity(); 137 } 138 139 /** 140 * An activity whose versions were both added and removed by the new set of versions. 141 */ 142 public interface ChangedActivity extends CompareReport { 143 144 /** 145 * Return the changed activity. 146 * 147 * @return the activity some of whose versions were added and some of whose versions 148 * were deleted by the new set of versions. 149 */ 150 public Activity getActivity(); 151 } 152 153 /** Boolean flags for the doCompareReport method */ 154 public static class CompareFlag 155 { 156 private CompareFlag(String flagName) { _flagName = flagName; } 157 158 /** 159 * Returns a string representation of this flag suitable for diagnostics. 160 */ 161 @Override 162 public String toString() { return _flagName; } 163 164 /** 165 * The string form of this flag. 166 */ 167 private final String _flagName; 168 169 /** 170 * Indicates that the comparison should include information about activities whose 171 * {@link Activity#ACTIVITY_VERSION_LIST} contain versions that are an ancestor of 172 * an old version or an ancestor of a new version, but not both. 173 * <p> 174 * In particular, let NewVersions be the set of versions that are a new version or an ancestor of 175 * a new version, but not an old version or an ancestor of an old version; and let OldVersions be the 176 * set of versions that are an old version or an ancestor of an old version, but not a new version 177 * or an ancestor of a new version. 178 * Then an activity is considered: 179 * <li>"added" if every version in its {@link Activity#ACTIVITY_VERSION_LIST} 180 * is in the NewVersions set. 181 * <li>"deleted" if every version in its {@link Activity#ACTIVITY_VERSION_LIST} 182 * is in the OldVersions set. 183 * <li>"partially added" if some versions in its {@link Activity#ACTIVITY_VERSION_LIST} 184 * are in the NewVersions set and the rest are in neither set. 185 * <li>"partially deleted" if some versions in its {@link Activity#ACTIVITY_VERSION_LIST} 186 * are in the OldVersions set and the rest are in neither set. 187 * <li>"changed" if some versions in its {@link Activity#ACTIVITY_VERSION_LIST} are in 188 * the NewVersions set and some are in the OldVersions set. 189 */ 190 public static final CompareFlag ACTIVITIES = new CompareFlag("activities"); //$NON-NLS-1$ 191 192 /** 193 * Report only on versions in the new set of versions. 194 * Changed versions are reported as added versions, 195 * and deleted versions are not reported at all. 196 */ 197 public static final CompareFlag NEW_ONLY = new CompareFlag("new-only"); //$NON-NLS-1$ 198 199 } 200 201 202 /** 203 * Compare two baselines. 204 * 205 * @param baseline the baseline being compared to this Baseline. 206 * @param flags boolean flags for the compare report. 207 * @param feedback the properties available in the returned proxies. 208 * @return a ResponseIterator of CompareReport objects, that enumerate the differences between the 209 * versions selected by this Baseline and the baseline argument. 210 * @throws WvcmException ReasonCode: 211 * <li>{@link ReasonCode#BAD_ARGUMENT_TYPE}: 212 * The resource identified by the <code>baseline</code> argument must be a baseline. 213 */ 214 public ResponseIterator<CompareReport> doCompareReport( 215 Baseline baseline, 216 CompareFlag[] flags, 217 Feedback feedback) 218 throws WvcmException; 219 220 /** 221 * Compare this Baseline with a stream. 222 * 223 * @param stream the stream being compared to this Baseline. 224 * @param flags boolean flags for the compare report. 225 * @param feedback the properties available in the returned proxies. 226 * @return a ResponseIterator of CompareReport objects, that enumerate the differences between the 227 * versions selected by this Stream and the stream argument. 228 * @throws WvcmException ReasonCode: 229 * <li>{@link ReasonCode#METHOD_NOT_SUPPORTED}: 230 * This resource does not support this report. 231 * <li>{@link ReasonCode#BAD_ARGUMENT_TYPE}: 232 * The resource identified by the <code>stream</code> argument must be a stream. 233 */ 234 public ResponseIterator<CompareReport> doCompareReport( 235 Stream stream, 236 CompareFlag[] flags, 237 Feedback feedback) 238 throws WvcmException; 239 240 /** 241 * A list of all the versions that make up this baseline. The list is 242 * created from all the {@link ControllableResource#CHECKED_IN} versions of 243 * all the version-controlled members of the 244 * {@link Configuration#ROOT_FOLDER} of the configuration at the time the 245 * baseline identified by this Baseline was created. 246 */ 247 public static final PropertyName<ResourceList<Version>> VERSION_LIST = 248 new PropertyName<ResourceList<Version>>("version-list"); //$NON-NLS-1$ 249 250 /** 251 * Get the {@link #VERSION_LIST} property. 252 * 253 * @return the {@link #VERSION_LIST} property. 254 * @throws WvcmException if this Baseline was not created with 255 * {@link #VERSION_LIST} as a wanted property. 256 */ 257 public ResourceList<Version> getVersionList() throws WvcmException; 258 259 }