001    /*
002    * file CcComponent.java
003    *
004    * Licensed Materials - Property of IBM
005    * Restricted Materials of IBM
006    * 
007    * com.ibm.rational.wvcm.stp.cc.CcComponent
008    *
009    * © 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    
014    package com.ibm.rational.wvcm.stp.cc;
015    
016    import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017    
018    import javax.wvcm.Activity;
019    import javax.wvcm.Component;
020    import javax.wvcm.Feedback;
021    import javax.wvcm.WvcmException;
022    import javax.wvcm.PropertyNameList.PropertyName;
023    
024    import com.ibm.rational.wvcm.stpex.StpExBase;
025    
026    /**
027     * A proxy for a ClearCase UCM component.
028     * <p>
029     * A UCM component defines the set of files that will be captured in a baseline
030     * of that component. A baseline is a version of a component, and records a
031     * version of each element selected by the stream's configuration.
032     * </p>
033     * <p>
034     * A <i>rootless</i> component has no root directory element. Rootless
035     * components are typically used to aggregate other components. Baselines of
036     * rootless components contain other baselines, rather than file versions.
037     * </p>
038     * <p>
039     * NOTE: Not all WVCM properties and operations are supported in this release of
040     * CM API. For a list of properties currently supported by a particular resource
041     * type, use doGetPropertyNameList() on an instance of that type:
042     * </p>
043     * 
044     * <pre>
045     *     PropertyRequest supportedProps = myResource.doGetPropertyNameList();
046     * </pre>
047     */
048    public interface CcComponent extends Component, CcVobResource
049    {
050            /**
051         * <p>Create a new UCM component at the location identified by this proxy. The
052         * location should be an object name selector specifying the component's name
053         * and the repository (project VOB) in which to create it.
054         * </p>
055         * <p>Set the {@link #ROOT_DIRECTORY_ELEMENT} property to specify the new component's
056         * root.  If no root directory element is set, a rootless component is created.
057         * </p>
058         * <p>This method fails if the root directory element is not a legal choice for
059         * a component root.
060         * </p>
061         */
062        public CcComponent doCreateCcComponent(Feedback feedback) throws WvcmException;
063    
064        /**
065         * Does this component have a root directory element?  Or is it "rootless"?
066         */
067        PropertyName<Boolean> HAS_ROOT_DIRECTORY_ELEMENT = 
068            new PropertyName<Boolean>(PROPERTY_NAMESPACE, "has-root-directory-element");
069    
070        /**
071         * Get the {@link #HAS_ROOT_DIRECTORY_ELEMENT} property of this component.
072         * @return   true if this component has a root directory element;
073         *           false if this is a rootless component.
074         * @throws WvcmException if this proxy doesn't define a value for this property.
075         */
076        boolean getHasRootDirectoryElement() throws WvcmException;
077    
078        /**
079         * This component's initial baseline.  A component's initial
080         * baseline contains exactly one version - the /main/0 version of the
081         * component's root directory element.
082         */
083        PropertyName<CcBaseline> INITIAL_BASELINE = 
084            new PropertyName<CcBaseline>(PROPERTY_NAMESPACE, "initial-baseline");
085    
086        /**
087         * Get the the {@link #INITIAL_BASELINE} property of this component.
088         * @return   A proxy for this component's initial baseline
089         * @throws WvcmException if this proxy doesn't define a value for this property.
090         */
091        CcBaseline getInitialBaseline() throws WvcmException;
092    
093        /**
094         * This component's root directory element - the directory element in the
095         * VOB that defines the scope of files that are captured in this component's
096         * baselines.
097         */
098        PropertyName<CcElement> ROOT_DIRECTORY_ELEMENT = 
099            new PropertyName<CcElement>(PROPERTY_NAMESPACE, "root-directory-element");
100    
101        /**
102         * Get the {@link #ROOT_DIRECTORY_ELEMENT} property of this component.
103         * @return   A proxy for this component's root directory element, or null if this is a
104         *           rootless component.
105         * @throws WvcmException if this proxy doesn't define a value for this property.
106         */
107        CcElement getRootDirectoryElement() throws WvcmException;
108    
109        /**
110         * Set the value of this component's {@link #ROOT_DIRECTORY_ELEMENT} property.
111         * This property can only be set at component creation time.
112         * 
113         * @param root  A proxy for this component's root directory element
114         */
115        void setRootDirectoryElement(CcElement root);
116    }