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, 2015.  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 component's root is a directory beneath the VOB, then {@link #VIEW}
055         * property must also be set.
056         * 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        
117        /**
118         * This component's full closure of baselines.
119         */
120        PropertyName<ResourceList<CcBaseline>> BASELINE_LIST_CLOSURE = 
121            new PropertyName<ResourceList<CcBaseline>>(PROPERTY_NAMESPACE, "baseline-list-closure");
122        
123        /**
124         * Get the value of the this proxy's {@link #BASELINE_LIST_CLOSURE} property
125         * @return a list of client proxies for this component's baselines
126         * @throws WvcmException if this proxy doesn't define a value for this property.
127         */
128        ResourceList<CcBaseline> getBaselineListClosure() throws WvcmException;
129        
130        /**
131         * A <em>write-only</em> property used to specify the view context
132         * to be used for the component creation, whose root directory element
133         * is a directory one level beneath the VOB. 
134         */
135        PropertyName<CcView> VIEW = 
136            new PropertyName<CcView>(PROPERTY_NAMESPACE, "view");
137        
138        /**
139         * Set the value of this proxy's {@link #VIEW} property. This property
140         * can only be set at component creation time to be used by 
141         * {@link #doCreateCcComponent(Feedback)} method.
142         * @param view  view context to be used for component creation.
143         * @throws WvcmException
144         */
145        public void setView(CcView view) throws WvcmException;
146    }