IImportRefactorer.java

/*******************************************************************************
 * Copyright (c) 2012 Arapiki Solutions Inc.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *    psmith - initial API and 
 *        implementation and/or initial documentation
 *******************************************************************************/ 

package com.buildml.refactor;

import java.util.List;

import com.buildml.model.IPackageMemberMgr.MemberDesc;
import com.buildml.model.types.ActionSet;
import com.buildml.model.undo.MultiUndoOp;

/**
 * Various refactoring operations that can be performed on an imported BuildStore.
 * That is, when we use a build scanner to import a legacy build, it's often necessary
 * to clean up the imported information. This includes deleting unused files and
 * actions, and merging multiple actions into a single action.
 * 
 * This class sits on top of the standard BuildStore infrastructure and provides
 * an intelligence layer that determines the correct sequence of adds/deletes/moves.
 * This code ensures that consistency rules are maintained and that the refactoring
 * operations can always be undone and redone as requested by the user.
 * 
 * @author Peter Smith <psmith@arapiki.com>
 */
public interface IImportRefactorer {
	
	/**
	 * Delete a path from the BuildStore. A path can only be deleted under the following
	 * situations:
	 *   - The path exists and has not already been deleted.
	 *   - The path is not a non-empty directory.
	 *   - The path is not being used as input to one or more actions.
	 *   - The path is not generated by an action (unless alsoDeleteAction is true)
	 *   - The path is generated by an atomic action.
	 *   - The path is not generated by an action that also generates other files that
	 *     are still in use (the action can't be deleted).
	 * 
	 * @param multiOp          The multi-undo/redo operation to append changes to.
	 * @param pathId           The path (file/directory) to be deleted.
	 * @param alsoDeleteAction If true, also proceed to delete the action(s) that generate
	 *                         this file.
     * @param removeFromAction If this path is read by an action, remove the path-access from the action.
	 * @throws CanNotRefactorException If the refactoring can not proceed for some reason.
	 */
	public void deletePath(MultiUndoOp multiOp, int pathId, boolean alsoDeleteAction, boolean removeFromAction)
			throws CanNotRefactorException;
	
	/**
	 * @param multiOp             The multi-undo/redo operation to append changes to.
	 * @param dirId			      ID of the directory (path) to remove.
	 * @param alsoDeleteActions   True if we should also delete actions that generate the
	 *                            files in this directory.
	 * @param removeFromAction    If this path is read by an action, remove the path-access from the action.
	 * @throws CanNotRefactorException
	 */
	public void deletePathTree(MultiUndoOp multiOp, int dirId, boolean alsoDeleteActions, boolean removeFromAction)
			throws CanNotRefactorException;
	
	/**
	 * Modify a build action so that it no longer has child actions, yet has the same
	 * effect as the original action hierarchy. For many tools, a process may create
	 * additional sub-processes to complete the job. If we are not interested in
	 * knowing about these sub-processes, the parent action can be made "atomic".
	 * 
	 * @param multiOp   The IUndoOp multi operation to add changes to.
	 * @param actionId ID of the action to be made atomic.
	 * @throws CanNotRefactorException If the refactoring can not proceed for some reason.
	 */
	public void makeActionAtomic(MultiUndoOp multiOp, int actionId) throws CanNotRefactorException;
	
	/**
	 * @param multiOp   The IUndoOp multi operation to add changes to.
	 * @param actionId	The ID of the action to delete.
	 * @throws CanNotRefactorException
	 */
	public void deleteAction(MultiUndoOp multiOp, int actionId) throws CanNotRefactorException;
	
	/**
	 * Merge two or more actions into a single action, with the shell commands
	 * from each action merged into a single shell command. The actions must
	 * all be atomic.
	 *
	 * @param multiOp   The IUndoOp multi operation to add changes to.
	 * @param actionIds The actions to be merged.
	 * @throws CanNotRefactorException If the refactoring can not proceed for some reason.
	 */
	public void mergeActions(MultiUndoOp multiOp, ActionSet actionIds) throws CanNotRefactorException;
	
	/**
	 * Move any number of package members from one package to another. Depending on which
	 * members are being moved, this may result in a whole chain of members being moved.
	 * If moving from the <import> package, new file groups and filters might need
	 * to be created.
	 * @param multiOp   	The IUndoOp multi operation to add changes to.
	 * @param destPkgId		ID of the package to move the members into.
	 * @param members		A List of members to be moved into the destination package.
	 * @throws CanNotRefactorException Refactoring failed for some reason.
	 */
	public void moveMembersToPackage(MultiUndoOp multiOp, int destPkgId, List<MemberDesc> members)
			throws CanNotRefactorException;

}