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
014package com.ibm.rational.wvcm.stp.cc;
015
016import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018import javax.wvcm.Component;
019import javax.wvcm.Feedback;
020import javax.wvcm.PropertyNameList.PropertyName;
021import javax.wvcm.ResourceList;
022import 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 */
046public 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}