001/*  
002 * file CcDirectory.java
003 *
004 * Licensed Materials - Property of IBM and/or HCL
005 * Restricted Materials of IBM and/or HCL
006 *
007 * com.ibm.rational.wvcm.stp.cc.CcDirectory
008 *
009 * (C) Copyright IBM Corporation 2004, 2015.  All Rights Reserved.
010 * (C) Copyright HCL Technologies Ltd. 2017.  All Rights Reserved.
011 * Note to U.S. Government Users Restricted Rights:  Use, duplication or 
012 * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp.
013 */
014
015package com.ibm.rational.wvcm.stp.cc;
016
017import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
018
019import java.util.List;
020
021import javax.wvcm.ControllableFolder;
022import javax.wvcm.Feedback;
023import javax.wvcm.ResourceList;
024import javax.wvcm.WvcmException;
025import javax.wvcm.PropertyNameList.PropertyName;
026
027/**
028 * <p>
029 * A proxy for a directory in a ClearCase view.
030 * This directory is either under version control or could potentially be
031 * put under version control.
032 * </p>
033 */
034public interface CcDirectory
035    extends CcFile, ControllableFolder 
036{
037    /**
038     * Create a new view-private directory at the location specified by this
039     * resource.  The request will fail if a resource already exists at that
040     * location.
041     * @see javax.wvcm.ControllableResource#doCreateResource(Feedback)
042     */
043    public CcDirectory createCcDirectory(Feedback feedback) throws WvcmException;
044    
045    /**
046     * Create a new VOB hard link in this directory.
047     * The request will fail if the directory is not already checked-out
048     * or a child with name {@code linkName} already exists.
049     * <p>Note: For web views, this method is only supported for targets that
050     * are visible in the view at the time of invocation.
051     * @param comment Comment to be attached to the newly created link, or {@code null}
052     * for no comment.
053     * @param targets  Controlled resource to which the new link is created.
054     * The resource must exist in the same VOB as this directory.
055     * @param linkName Leaf name for the new link to be created in this directory.
056     * @param feedback 
057     * @return Proxy for the new link object
058     * @throws WvcmException
059     */
060    public CcResource doCreateHardLink(String comment, CcResource target, String linkName, 
061            Feedback feedback) throws WvcmException;
062    
063    /**
064     * Create new VOB hard links in this directory.
065     * The links will be created with names identical to the leaf of the specified targets.
066     * The request will fail if the directory is not already checked-out
067     * or a child with name matching one of the target leafs already exists.
068     * <p>Note: For web views, this method is only supported for targets that
069     * are visible in the view at the time of invocation.
070     * @param comment Comment to be attached to the newly created link, or {@code null}
071     * for no comment.
072     * @param targets  List of controlled resources to which the new links are created.
073     * The resources must exist in the same VOB as this directory.
074     * @param feedback 
075     * @return List of proxies for the new link objects.  If only some of the links can be created,
076     * the operation succeeds and only the newly created links are returned from the method.
077     * @throws WvcmException
078     */
079    public ResourceList<CcResource> doCreateHardLink(String comment, ResourceList<CcResource> targets, 
080            Feedback feedback) throws WvcmException;
081
082    /**
083     * Create a new VOB symbolic link in this directory.
084     * The request will fail if the directory is not already checked-out
085     * or a child with name {@code linkName} already exists.
086     * <p>Note that for a web or snapshot view, it is possible for a new link to be
087     * successfully created, but not loaded into the view if the target is not currently
088     * visible.
089     * @param comment Comment to be attached to the newly created link, or {@code null}
090     * for no comment.
091     * @param target Path (absolute or relative) to which the new link is created.
092     * The path does <strong>not</strong> have to resolve to an existing object. 
093     * @param linkName Leaf name for the new link to be created in this directory.
094     * @param feedback
095     * @return Proxy for the new link object
096     * @throws WvcmException
097     */
098    public CcResource doCreateSymlink(String comment, String target, String linkName, 
099            Feedback feedback) throws WvcmException;
100    
101    /**
102     * Create new VOB symbolic links in this directory.
103     * The links will be created with names identical to the leaf of the specified targets.
104     * The request will fail if the directory is not already checked-out
105     * or a child with name matching one of the target leafs  already exists.
106     * <p>Note that for a web or snapshot view, it is possible for a new link to be
107     * successfully created, but not loaded into the view if the target is not currently
108     * visible.
109     * @param comment Comment to be attached to the newly created link, or {@code null}
110     * for no comment.
111     * @param targets List of paths (absolute or relative) to which the new links are created.
112     * The paths do not <strong>not</strong> have to resolve to an existing object. 
113     * @param feedback
114     * @return List of proxies for the new link objects.  If only some of the links can be created,
115     * the operation succeeds and only the newly created links are returned from the method.
116     * @throws WvcmException
117     */
118    public ResourceList<CcResource> doCreateSymlink(String comment, List<String> targets, 
119            Feedback feedback) throws WvcmException;
120
121    /**
122     * The list of String objects that identify the names of version-controlled
123     * resources in this CcDirectory that are eclipsed by non-version-controlled resources.
124     * <p>
125     * A
126     * {@link javax.wvcm.Workspace#doUpdate(ResourceList, Feedback) Workspace.doUpdate}
127     * or
128     * {@link javax.wvcm.Workspace#doMerge(ResourceList, javax.wvcm.Workspace.MergeFlag[], Feedback) Workspace.doMerge}
129     * request can give a version-controlled folder a version-controlled bound
130     * member that has the same name as an existing uncontrolled bound member.
131     * In this case, the uncontrolled bound member takes precedence and is said
132     * to &quot;eclipse&quot; the new versioned-controlled bound member.
133     */
134    PropertyName<List<String>> ECLIPSED_LIST =
135      new PropertyName<List<String>>(PROPERTY_NAMESPACE, "eclipsed-list");
136
137    /**
138     * Get the {@link #ECLIPSED_LIST} property.
139     * @return String list of the names of the eclipsed version-controlled resources
140     * @throws WvcmException if this ControllableFolder was not created with
141     * {@link #ECLIPSED_LIST} as a wanted property.
142     */
143    List<String> getEclipsedList() throws WvcmException;
144
145
146    /**
147     * Are there checkouts anywhere in the tree below this directory?
148     */
149    PropertyName<Boolean> HAS_DESCENDANT_CHECKOUTS =
150        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "has-descendant-checkouts");
151    
152    /**
153     * Get the {@link #HAS_DESCENDANT_CHECKOUTS} property.
154     * @return true if there are checkouts anywhere in the tree rooted by this directory, else false.
155     * @throws WvcmException if this ControllableFolder was not created with
156     * {@link #HAS_DESCENDANT_CHECKOUTS} as a wanted property.
157     * */
158    boolean getHasDescendantCheckouts() throws WvcmException;
159
160    
161    /**
162     * Are there hijacks anywhere in the tree below this directory?
163     * Not supported for Snapshot view resources.
164     */
165    PropertyName<Boolean> HAS_DESCENDANT_HIJACKS =
166        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "has-descendant-hijacks");
167    
168    /**
169     * Get the {@link #HAS_DESCENDANT_HIJACKS} property.
170     * @return true if there are hijacks anywhere in the tree rooted by this directory, else false.
171     * @throws WvcmException if this ControllableFolder was not created with
172     * {@link #HAS_DESCENDANT_HIJACKS} as a wanted property.
173     * */
174    public boolean getHasDescendantHijacks() throws WvcmException;
175
176    /**
177     * A list of all checkouts in the tree below this directory. Returns a list of CcFile resources.
178     */
179    PropertyName<ResourceList<CcFile>> AGGREGATED_CHECKOUT_LIST =
180        new PropertyName<ResourceList<CcFile>>(PROPERTY_NAMESPACE, "aggregated-checkout-list");
181
182    /**
183     * Get the {@link #AGGREGATED_CHECKOUT_LIST} property.
184     * @return List of CcFile proxies representing all checkouts in the tree rooted by this directory.
185     * @throws WvcmException if this ControllableFolder was not created with
186     * {@link #AGGREGATED_CHECKOUT_LIST} as a wanted property.
187     * */
188    ResourceList<CcFile> getAggregatedCheckoutList() throws WvcmException;
189    
190    
191    /**
192     * A list of all hijacks in the tree below this directory. Returns a list of CcFile resources.
193     * Not supported for Snapshot view resources.
194     */
195    PropertyName<ResourceList<CcFile>> AGGREGATED_HIJACK_LIST =
196        new PropertyName<ResourceList<CcFile>>(PROPERTY_NAMESPACE, "aggregated-hijack-list");
197    
198    /**
199     * Get the {@link #AGGREGATED_HIJACK_LIST} property.
200     * @return List of CcFile proxies representing all hijacks in the tree rooted by this directory.
201     * @throws WvcmException if this ControllableFolder was not created with
202     * {@link #AGGREGATED_HIJACK_LIST} as a wanted property.
203     * */
204    public ResourceList<CcFile> getAggregatedHijackList() throws WvcmException;
205    
206    /**
207     * A list of all the view private files in the tree below this directory.  Does not include
208     * checkouts, hijacks or derived objects.  Returns a list of CcFile resources.
209     * Only supported for the view root and VOB root directories of automatic views.
210     */
211    PropertyName<ResourceList<CcFile>> AGGREGATED_VIEW_PRIVATE_LIST = 
212        new PropertyName<ResourceList<CcFile>>(PROPERTY_NAMESPACE, "aggregated-view-private-list");
213    
214    /**
215     * Get the {@link #AGGREGATED_VIEW_PRIVATE_LIST} property.
216     * @return List of CcFile proxies representing view private files in the tree rooted by this directory.
217     * @throws WvcmException if this ControllableFolder was not created with
218     * {@link #AGGREGATED_VIEW_PRIVATE_LIST} as a wanted property.
219     * */
220    public ResourceList<CcFile> getAggregatedViewPrivateList() throws WvcmException;
221
222    /**
223     * Is this directory the root of a ClearCase VOB.
224     */
225    PropertyName<Boolean> IS_VOB_ROOT =
226        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-vob-root");
227    
228    /**
229     * Returns the value of this proxy's {@link #IS_VOB_ROOT} property. 
230     * @return true if the directory is the root of a VOB, else false
231     * @throws WvcmException
232     *             if this proxy doesn't define a value for this property.
233     */
234    public boolean getIsVobRoot() throws WvcmException;
235    
236}
237