001/*
002 * Licensed Materials - Property of IBM
003 * Restricted Materials of IBM
004 *
005 * com.ibm.rational.wvcm.stp.cc.CcMergeElement
006 *
007 * (C) Copyright IBM Corporation 2010, 2011.  All Rights Reserved.
008 * Note to U.S. Government Users Restricted Rights:  Use, duplication or 
009 * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp.
010 */
011package com.ibm.rational.wvcm.stp.cc;
012
013import javax.wvcm.Feedback;
014import javax.wvcm.WvcmException;
015
016import com.ibm.rational.wvcm.stp.cc.CcFile.CcCheckoutFlag;
017
018/**
019 * An interface used to track the status of a Merge operation. This object
020 * is used by integration operations to maintain state through each phase of
021 * the operation. For example, from <code>CcView.doStartDeliver()</code> to
022 * <code>CcView.doCompleteDeliver()</code>.
023 */
024public interface CcMergeElement {
025
026    /**
027     * Enumerated states to determine if a merge is needed.
028     */
029    enum MergeState {
030        UNKNOWN,
031        NEEDS_MERGE,
032        MERGE_NOT_NEEDED,
033        MERGED,
034        NO_MERGE,
035        NEEDS_NOAUTOMERGE,
036        MERGE_ERROR,
037        NEVER_MERGE
038    }
039
040    /**
041     * Before the merge stage, the MergeInterventionType will either be 
042     * <code>TRIVIAL</code> or <code>NON_TRIVIAL</code>. After the merge stage,
043     * MergeInterventionType shows what type of merge was performed, 
044     * <code>AUTOMATIC</code> or <code>MANUAL</code>.
045     */
046    enum MergeInterventionType {
047        UNKNOWN,
048        /**
049         * No user intervention is required.
050         */
051        TRIVIAL,
052        /**
053         * User intervention is required.
054         */
055        NON_TRIVIAL,
056        /**
057         * No intervention during the merge. Decision was made automatically.
058         */
059        AUTOMATIC,
060        /**
061         * There was user intervention during the merge.
062         */
063        MANUAL
064    }
065
066    /**
067     * Retrieve whether a merge is needed or not
068     *
069     * @return MergeState describing the element merge
070     */
071    public MergeState getMergeState();
072
073    /**
074     * Retrieve the view relative pathname for this element
075     *
076     * @return String pathname to this object
077     */
078    public String getViewRelativePathname() throws WvcmException;
079
080    /**
081     * Is this element a directory?
082     *
083     * @return true if the element is a directory
084     */
085    public boolean getIsDirectory();
086
087    /**
088     * Determine whether this element is visible to the current view.
089     *
090     * @return true if the element is visible
091     */
092    public boolean getIsVisible();
093
094    /**
095     * Determine the file type for this element. This is the file type
096     * used to determine which type manager to use for the merge handler.
097     *
098     * @return String of file type (ie. text-delta)
099     */
100    public String getTypeManager();
101
102    /**
103     * Provides an accessor to the underlying CcFile object for this
104     * MergeElement. Use this method to request properties.
105     * @param wantedProps props to be fetched
106     *
107     * @return a new proxy for the underlying CcFile
108     */
109    public CcFile doReadProperties(Feedback wantedProps) throws WvcmException;
110
111    /**
112     * Returns the type of merge needed for this element. This
113     * will reveal if this element is marked as a USER merge or
114     * NEVER merge type.
115     *
116     * @return ElementMergeType
117     */
118    public CcElementType.MergeType getElementMergeType();
119
120    /**
121     * Returns the type of merge needed.
122     * <ul>
123     * <li>TRIVIAL - No intervention is needed.</li>
124     * <li>NON-TRIVIAL - User intervention is required.</li>
125     * <li>AUTOMATIC - No intervention during the merge. Decision was made
126     * automatically.</li>
127     * <li>MANUAL - There was user intervention during the merge.</li>
128     * </ul>
129     * @see MergeInterventionType
130     *
131     * @return MergeInterventionType describing the type of merge
132     */
133    public MergeInterventionType getMergeInterventionType();
134
135    /**
136     * Retrieve the from version contributor.
137     *
138     * @return String version extended pathname of the from version
139     */
140    public String getFromVersionExtendedPathname();
141
142    /**
143     * Retrieve the to version contributor.
144     *
145     * @return String version extended pathname of the to version
146     */
147    public String getToVersionExtendedPathname();
148
149    /**
150     * Retrieve the base version contributor. May be null.
151     *
152     * @return String version extended pathname of the base version
153     */
154    public String getBaseVersionExtendedPathname();
155
156    /**
157     * Get the provider proxy for the underlying CcFile for this element
158     *
159     * @return CcProvider proxy
160     */
161    public CcProvider getProvider();
162
163    /**
164     * Utility method to request the underlying CcFile object to be
165     * checked out for merge.
166     *
167     * @param coFlags Checkout flags
168     * @param feedback properties to be requested
169     * @return new proxy to the underlying file with requested properties
170     * @throws WvcmException
171     */
172    public CcFile doCheckout(CcCheckoutFlag[] coFlags, Feedback feedback) throws WvcmException;
173
174}