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