public interface IBuildEngine extends IBuildEngineHandle, IAuditable, IBuildItem

    /**
     * Returns the primary predecessor state of this auditable item state. The
     * predecessor state is another state of the same audtiable item. When
     * IRepositoryItemService.fetchAllStates(IAuditableHandle) is
     * used to retrieve all the known states of the item, the predecessor (and
     * merge predecessor) states of each state can be used to construct the
     * version graph.
     * 

     * The initial state of an item has no predecessor state.
     * 
     * 
     * @return the predecessor state, or null if none
     * @ShortOp This is a short operation; it may block only momentarily; safe
     *          to call from a responsive thread.
     */
    public IAuditableHandle getPredecessorState();

    /**
     * Returns the secondary merge predecessor state of this auditable item
     * state. The merge predecessor state is another state of the same auditable
     * item, and is always used in conjuction with the main predecessor state.
     * When IRepositoryItemService.fetchAllStates(IAuditableHandle)
     * is used to retrieve all the known states of the item, the predecessor
     * (and merge predecessor) states of each state can be used to construct the
     * version graph.
     * 

     * The initial state of an item has no predecessor state.
     * 
     * 

     * Design note: Without loss of generality, 0..2 predecessors is sufficient.
     * Most states have exactly 1 predecessor. The initial state has 0
     * predecessors. And a state that comes about from a 3-way merge has 2
     * predecessors, tops.
     * 
     * 
     * @return the merge predecessor state, or null if none
     * @ShortOp This is a short operation; it may block only momentarily; safe
     *          to call from a responsive thread.
     */
    public IAuditableHandle getMergePredecessorState();

    /**
     * Retrieves the full history of the given auditable item. The auditable
     * item states retrieved as part of the resulting history object are
     * complete states. The operation fails if the client is not logged in to
     * the repository.
     * 

     * The item states in the result are considered immutable. The client must
     * not attempt to modify any of these item states.
     * 
     *
     * @param itemHandle
     *            the auditable handle; must not be null
     * @param monitor
     *            a progress monitor, or null if progress
     *            reporting is not desired
     * @return the history of the auditable containing all states (element type:
     *         {@link IAuditableHandle}) of the given item known to the
     *         repository; never null
     * @throws NotLoggedInException
     *             if the operation fails because the client was not logged in
     *             to the repository
     * @throws ItemNotFoundException
     *             if the item was not found
     * @throws TeamRepositoryException
     *             if the operation fails for any other reason
     * @throws OperationCanceledException
     *             if the operation is canceled. Cancellation can occur even if
     *             no progress monitor is provided.
     * @LongOp This is a long operation; it may block indefinitely; must not be
     *         called from a responsive thread.
     */
    public List fetchAllStateHandles(IAuditableHandle itemHandle,
            IProgressMonitor monitor) throws TeamRepositoryException;