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