001/*
002* file CcProjectFolder.java
003*
004* Licensed Materials - Property of IBM
005* Restricted Materials of IBM
006* 
007* com.ibm.rational.wvcm.stp.cc.CcProjectFolder
008*
009* (C) Copyright IBM Corporation 2004, 2008.  All Rights Reserved. 
010* Note to U.S. Government Users Restricted Rights:  Use, duplication or  
011* disclosure restricted by GSA ADP  Schedule Contract with IBM Corp. 
012*/
013
014package com.ibm.rational.wvcm.stp.cc;
015
016import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018import javax.wvcm.Feedback;
019import javax.wvcm.ResourceList;
020import javax.wvcm.WvcmException;
021import javax.wvcm.PropertyNameList.PropertyName;
022
023/**
024 * <p>A proxy for a ClearCase UCM project folder.
025 * </p>
026 * <p>Project folders are used to organize the projects in a project VOB. A project
027 * folder may contain both UCM projects and project subfolders.
028 * </p>
029 * <p>A project VOB has one distinguished <i>root folder</i>.
030 * </p>
031 * <p>
032 * For more project folder information, see the ClearCase "Guide to Developing Software with UCM"
033 * manual, and the cleartool man page "mkfolder".
034 * </p>
035 */
036public interface CcProjectFolder extends CcVobResource {
037
038    /**
039     * <p>
040     * Create a new UCM project folder at the location specified by this proxy. The
041     * location should be an object name selector specifying the folder's name
042     * and the repository (project VOB) in which to create it.
043     * </p>
044     * <p>
045     * Must specify the new project folder's parent folder by setting the
046     * folder's {@link #PARENT_FOLDER} property.
047     * </p>
048     */
049    CcProjectFolder doCreateCcProjectFolder(Feedback feedback) throws WvcmException;
050
051    /** Is this the root folder of its project VOB? */
052    PropertyName<Boolean> IS_ROOT = new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-root");
053
054    /**
055     * Get the value of this proxy's {@link #IS_ROOT} property.
056     * 
057     * @return true if this is the root project folder, else false.
058     * @throws WvcmException
059     *             if this proxy doesn't define a value for this property.
060     */
061    boolean getIsRoot() throws WvcmException;
062
063    /** This folder's parent folder. Will be null if this is the root folder. */
064    PropertyName<CcProjectFolder> PARENT_FOLDER =
065        new PropertyName<CcProjectFolder>(PROPERTY_NAMESPACE,
066                                          "parent-folder");
067
068    /**
069     * Get the value of this proxy's {@link #PARENT_FOLDER} property.
070     * 
071     * @return a client proxy for this folder's parent, or null if this is the
072     *         root folder
073     * @throws WvcmException
074     *             if this proxy doesn't define a value for this property.
075     */
076    CcProjectFolder getParentFolder() throws WvcmException;
077
078    /**
079     * Set the value of this proxy's {@link #PARENT_FOLDER} property.
080     * @param parentFolder this folder's new parent folder; cannot be null.
081     */
082    void setParentFolder(CcProjectFolder parentFolder);
083
084    /** This folder's subfolders. */
085    PropertyName<ResourceList<CcProjectFolder>> SUBFOLDER_LIST =
086        new PropertyName<ResourceList<CcProjectFolder>>(PROPERTY_NAMESPACE,
087                                                        "subfolder-list");
088
089    /**
090     * Get the value of this proxy's {@link #SUBFOLDER_LIST}property.
091     * 
092     * @return a list of client proxies for this folder's subfolders
093     * @throws WvcmException
094     *             if this proxy doesn't define a value for this property.
095     */
096    ResourceList<CcProjectFolder> getSubfolderList() throws WvcmException;
097
098    /** This folder's projects. */
099    PropertyName<ResourceList<CcProject>> PROJECT_LIST =
100        new PropertyName<ResourceList<CcProject>>(PROPERTY_NAMESPACE,
101                                                  "project-list");
102
103    /**
104     * Get the value of this proxy's {@link #PROJECT_LIST} property.
105     * 
106     * @return a list of client proxies for this folder's projects
107     * @throws WvcmException
108     *             if this proxy doesn't define a value for this property.
109     */
110    ResourceList<CcProject> getProjectList() throws WvcmException;
111}