Builder.java

/*
 *	P4Java - java integration with Perforce SCM
 *	Copyright (C) 2007-,  Mike Wille, Tek42
 *
 *	This library is free software; you can redistribute it and/or
 *	modify it under the terms of the GNU Lesser General Public
 *	License as published by the Free Software Foundation; either
 *	version 2.1 of the License, or (at your option) any later version.
 *
 *	This library is distributed in the hope that it will be useful,
 *	but WITHOUT ANY WARRANTY; without even the implied warranty of
 *	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *	Lesser General Public License for more details.
 *
 *	You should have received a copy of the GNU Lesser General Public
 *	License along with this library; if not, write to the Free Software
 *	Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 *
 *	You can contact the author at:
 *
 *	Web:	http://tek42.com
 *	Email:	mike@tek42.com
 *	Mail:	755 W Big Beaver Road
 *			Suite 1110
 *			Troy, MI 48084
 */

package com.tek42.perforce.parse;

import java.io.Writer;

import com.tek42.perforce.PerforceException;

/**
 * Interface for parsing perforce output into a concrete object and also for saving the object back to perforce. 
 * <p>
 * The pattern for using this template to build an object is:
 * <ol>
 * <li>Retrieve commands to execute via {@link #getBuildCmd(String)}</li>
 * <li>Execute those commands and capture the output.</li>
 * <li>Pass the output to {@link #build(StringBuilder)}</li>
 * </ol>
 * <p>And conversely for saving:
 * <ol>
 * <li>Retrieve commands to execute via {@link Builder#getSaveCmd(Object)}</li>
 * <li>Execute those commands and retrieve a Writer for I/O</li>
 * <li>Pass the writer and the object to save to {@link #save(Object, Writer)}</li>
 * </ol>
 * 
 * @author Mike Wille
 */
public interface Builder<T> {
	/**
	 * This should return the command line tokens to execute for retrieving an object from Perforce. For example:
	 * String[] { "p4", "user", "-o", "mwille" }
	 * 
	 * @param id
	 *            The ID or Name of the object we are working on. In the case of a changelist, the changelist number. In
	 *            the case of a user, the username.
	 * @return A 1D string array of tokens to execute.
	 */
	public String[] getBuildCmd(String p4exe, String id);

	/**
	 * This should assemble an object from a string value. Format of the string is dependent on the object we are
	 * building and is unspecified.
	 * 
	 * @param sb
	 *            The StringBuilder containing the string value.
	 * @return The resulting object
	 * @throws PerforceException
	 *             If the format is invalid or other errors occur.
	 */
	public T build(StringBuilder sb) throws PerforceException;

	/**
	 * The converse of {@link #getBuildCmd(String)} this should return the command line tokens to execute for saving an
	 * object to Perforce. For example: String[] { "p4", "user", "-i", "mwille" }
	 * <p>
	 * Note, although the object being saved is passed to this method, this method does not need to do anything with it.
	 * 
	 * @return A 1D string array of tokens to execute
	 * @param obj	The object that is being saved, useful if propert(ies) are needed for the save command to be generated.
	 */
	public String[] getSaveCmd(String p4exe, T obj);

	/**
	 * Tells the AbstractPerforceTemplate whether or not this builder will write data on Standard Input to the perforce
	 * command specified in getSaveCmd().  Currently, this only applies to saving as their is no writing required for
	 * building.
	 *
	 * @return	True if standard input should be opened and this builder's save() method called.  False otherwise.
	 */
	public boolean requiresStandardInput();
	
	/**
	 * The converse of {@link #build(StringBuilder)} this should take an object and disassemble it for writing to the
	 * Perforce server. The specification of what is written to the Writer is dependant on the object being saved.
	 * 
	 * @param obj
	 *            The object to be saved
	 * @param writer
	 *            The Writer to write the string representation to
	 * @throws PerforceException
	 *             If the object is invalid or there is an issue with writing
	 */
	public void save(T obj, Writer writer) throws PerforceException;

}