001/* 002 * file Stream.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.Baseline.CompareFlag; 014import javax.wvcm.Baseline.CompareReport; 015import javax.wvcm.PropertyNameList.PropertyName; 016import javax.wvcm.ResourceList.ResponseIterator; 017import javax.wvcm.WvcmException.ReasonCode; 018 019/** 020 * A proxy for a stream resource. 021 * 022 * A stream resource is an activity whose versions are baselines. 023 * 024 * @since 1.0 025 */ 026public interface Stream extends Activity { 027 028 /** 029 * A list of all the versions that are the current versions in this stream. 030 */ 031 public static final PropertyName<ResourceList<Version>> VERSION_LIST = 032 new PropertyName<ResourceList<Version>>("version-list"); //$NON-NLS-1$ 033 034 /** 035 * Get the {@link #VERSION_LIST} property. 036 * 037 * @return the {@link #VERSION_LIST} property. 038 * @throws WvcmException if this Stream was not created with 039 * {@link #VERSION_LIST} as a wanted property. 040 */ 041 public ResourceList<Version> getVersionList() throws WvcmException; 042 043 /** 044 * The stream to which changes in this stream are to be merged. 045 * An implementation MAY reject changing this property once the stream 046 * has been created. May be null. 047 * @see #getTarget 048 * @see #setTarget 049 */ 050 public static final PropertyName<Stream> TARGET = 051 new PropertyName<Stream>("target"); //$NON-NLS-1$ 052 053 /** 054 * Get the {@link #TARGET} property. 055 * 056 * @return the {@link #TARGET} property. 057 * @throws WvcmException if this Version was not created with 058 * {@link #TARGET} as a wanted property. 059 */ 060 public Stream getTarget() throws WvcmException; 061 062 /** 063 * Set the {@link #TARGET} property. 064 * 065 * @param target the {@link Stream} object that 066 * identifies the {@link #TARGET} for this Stream. 067 * @see #getTarget 068 */ 069 public void setTarget(Stream target); 070 071 /** 072 * A list of all streams which are declared to merge to this stream. 073 * The {@link #SOURCE_LIST} property is the computed inverse of the 074 * {@link #TARGET} property. 075 * @see #getSourceList 076 */ 077 public static final PropertyName<ResourceList<Stream>> SOURCE_LIST = 078 new PropertyName<ResourceList<Stream>>("source-list"); //$NON-NLS-1$ 079 080 /** 081 * Get the {@link #SOURCE_LIST} property. 082 * 083 * @return the {@link #SOURCE_LIST} property. 084 * @throws WvcmException if this Version was not created with 085 * {@link #SOURCE_LIST} as a wanted property. 086 */ 087 public ResourceList<Stream> getSourceList() throws WvcmException; 088 089 /** 090 * A workspace that can be used to browse the contents of this stream. 091 * This workspace MAY refuse to allow any change other than a 092 * {@link Workspace#doUpdate} whose argument is this stream. 093 */ 094 public static final PropertyName<Workspace> WORKSPACE = 095 new PropertyName<Workspace>("workspace"); //$NON-NLS-1$ 096 097 /** 098 * Get the {@link #WORKSPACE} property. 099 * 100 * @return the {@link #WORKSPACE} property. 101 * @throws WvcmException if this Stream was not created with 102 * {@link #WORKSPACE} as a wanted property. 103 */ 104 public Workspace getWorkspace() throws WvcmException; 105 106 /** 107 * Compare this Stream with another stream. 108 * 109 * @param stream the stream being compared to this Stream. 110 * @param flags boolean flags for the compare report. 111 * @param feedback the properties available in the returned proxies. 112 * @return a ResponseIterator of CompareReport objects, that enumerate the differences between the 113 * versions selected by this Stream and the stream argument. 114 * @throws WvcmException ReasonCode: 115 * <li>{@link ReasonCode#METHOD_NOT_SUPPORTED}: 116 * This resource does not support this report. 117 * <li>{@link ReasonCode#BAD_ARGUMENT_TYPE}: 118 * The resource identified by the <code>stream</code> argument must be a stream. 119 */ 120 public ResponseIterator<CompareReport> doCompareReport( 121 Stream stream, 122 CompareFlag[] flags, 123 Feedback feedback) 124 throws WvcmException; 125 126 /** 127 * Compare this Stream with a baseline. 128 * 129 * @param baseline the baseline being compared to this Stream. 130 * @param flags boolean flags for the compare report. 131 * @param feedback the properties available in the returned proxies. 132 * @return a ResponseIterator of CompareReport objects, that enumerate the differences between the 133 * versions selected by this Stream and the baseline argument. 134 * @throws WvcmException ReasonCode: 135 * <li>{@link ReasonCode#METHOD_NOT_SUPPORTED}: 136 * This resource does not support this report. 137 * <li>{@link ReasonCode#BAD_ARGUMENT_TYPE}: 138 * The resource identified by the <code>baseline</code> argument must be a baseline. 139 */ 140 public ResponseIterator<CompareReport> doCompareReport( 141 Baseline baseline, 142 CompareFlag[] flags, 143 Feedback feedback) 144 throws WvcmException; 145 146 /** 147 * Update the {@link #VERSION_LIST} of this stream to contain the versions 148 * specified in the sourceList argument. 149 * If {@link #VERSION_LIST} already contains a version from the same VersionHistory 150 * as the source version already, that version is replaced by the source version. 151 * <p> 152 * Postconditions: 153 * <li>(update-sources): Each of the versions in the sourceList MUST have updated 154 * the {@link #VERSION_LIST} of this Stream. 155 * 156 * @param sourceList the list of resources specifying the versions whose target in this stream should be updated. 157 * If a member of sourceList is an activity, it must not be a stream, and 158 * each version in the {@link Activity#ACTIVITY_VERSION_LIST} is a source version. 159 * If a member of sourceList is a version-controlled resource, 160 * the checked-in version of the member is a source version; 161 * if that version-controlled resource is a folder, all members 162 * of that folder are considered members of the sourceList. 163 * @param feedback Specifies optional feedback to the caller. 164 * @return A new proxy for this resource, whose properties are specified by feedback. 165 * @throws WvcmException An implementation may throw a single exception on the first error encountered, 166 * or may attempt to update all of the source versions, with any errors accumulated in the 167 * {@link WvcmException#getNestedExceptions} list. 168 * <br>ReasonCode: 169 * <li>{@link ReasonCode#BAD_ARGUMENT_TYPE}: 170 * The resources identified by the <code>sourceList</code> argument must be versions, activities, 171 * streams, or controllable resources. 172 * <li>{@link ReasonCode#MUST_BE_CHECKED_IN}: 173 * A version-controlled resource in the sourceList must be checked in. 174 */ 175 public <T extends Resource> Stream doUpdate(ResourceList<T> sourceList, Feedback feedback) 176 throws WvcmException; 177}