treebasedtask.java

Use the links below to download a source distribution of Ant from one of our mirrors. It is good pra

/*
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (the "License"); you may not use this file except in compliance with
 *  the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *
 */
package org.apache.tools.ant.taskdefs.optional.starteam;

import com.starbase.starteam.Folder;
import com.starbase.starteam.Label;
import com.starbase.starteam.PropertyNames;
import com.starbase.starteam.StarTeamFinder;
import com.starbase.starteam.View;
import com.starbase.starteam.ViewConfiguration;
import com.starbase.util.OLEDate;
import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.Hashtable;
import java.util.StringTokenizer;
import org.apache.tools.ant.BuildException;
import org.apache.tools.ant.util.DateUtils;
import org.apache.tools.ant.DirectoryScanner;
import org.apache.tools.ant.Project;

/**
 * TreeBasedTask.java
 * This abstract class is the base for any tasks that are tree-based, that
 * is, for tasks which iterate over a tree of folders in StarTeam which
 * is reflected in a tree of folder the local machine.
 *
 * This class provides the tree-iteration functionality.  Derived classes
 * will implement their specific task functionality by the visitor pattern,
 * specifically by implementing the method
 * <code>visit(Folder rootStarteamFolder, java.io.File rootLocalFolder)</code>
 *
 * Created: Sat Dec 15 16:55:19 2001
 *
 * @see <a href="http://www.borland.com/us/products/starteam/index.html"
 * >borland StarTeam Web Site</a>
 */

public abstract class TreeBasedTask extends StarTeamTask {


    ///////////////////////////////////////////////////////////////
    // default values for attributes.
    ///////////////////////////////////////////////////////////////
    /**
     * This constant sets the filter to include all files. This default has
     * the same result as <code>setIncludes("*")</code>.
     *
     * @see #getIncludes()
     * @see #setIncludes(String includes)
     */
    public static final String DEFAULT_INCLUDESETTING = "*";

    /**
     * This disables the exclude filter by default. In other words, no files
     * are excluded. This setting is equivalent to
     * <code>setExcludes(null)</code>.
     *
     * @see #getExcludes()
     * @see #setExcludes(String excludes)
     */
    public static final String DEFAULT_EXCLUDESETTING = null;

    //ATTRIBUTES settable from ant.

    /**
     * The root folder of the operation in StarTeam.
     */
    private String rootStarteamFolder = "/";

    /**
     * The local folder corresponding to starteamFolder.  If not specified
     * the Star Team default folder will be used.
     */
    private String rootLocalFolder = null;

    /**
     * All files that fit this pattern are checked out.
     */
    private String includes = DEFAULT_INCLUDESETTING;

    /**
     * All files fitting this pattern are ignored.
     */
    private String excludes = DEFAULT_EXCLUDESETTING;

    /**
     * StarTeam label on which to perform task.
     */
    private String label = null;

    /**
     * Set recursion to false to check out files in only the given folder
     * and not in its subfolders.
     */
    private boolean recursive = true;

    /**
     * Set preloadFileInformation to true to load all file information from the server
     * at once.  Increases performance significantly for projects with many files and/or folders.
     */
    private boolean preloadFileInformation = true;

    /**
     * If forced set to true, files in the target directory will
     * be processed regardless of status in the repository.
     * Usually this should be  true if rootlocalfolder is set
     * because status will be relative to the default folder, not
     * to the one being processed.
     */
    private boolean forced = false;

    private Label labelInUse = null;

    /**
     * holder for the asofdate attribute
     */
    private String asOfDate = null;

    /**
     * holder for the asofdateformat attribute
     */
    private String asOfDateFormat = null;



    ///////////////////////////////////////////////////////////////
    // GET/SET methods.
    // Setters, of course are where ant user passes in values.
    ///////////////////////////////////////////////////////////////

    /**
     * Set the root of the subtree in the StarTeam repository from which to
     * work; optional.  Defaults to the root folder of the view ('/').
     * @param rootStarteamFolder the root folder
     */
    public void setRootStarteamFolder(String rootStarteamFolder) {
        this.rootStarteamFolder = rootStarteamFolder;
    }

    /**
     * returns the root folder in the Starteam repository
     * used for this operation
     * @return the root folder in use
     */
    public String getRootStarteamFolder() {
        return this.rootStarteamFolder;
    }

    /**
     * Set the local folder that will be the root of the tree
     * to which files are checked out; optional.
     * If this is not supplied, then the StarTeam "default folder"
     * associated with <tt>rootstarteamfolder</tt> is used.
     *
     * @param rootLocalFolder
     *               the local folder that will mirror
     *               this.rootStarteamFolder
     */
    public void setRootLocalFolder(String rootLocalFolder) {
        this.rootLocalFolder = rootLocalFolder;
    }



    /**
     * Returns the local folder specified by the user,
     * corresponding to the starteam folder for this operation
     * or null if not specified.
     *
     * @return the local folder that mirrors this.rootStarteamFolder
     */
    public String getRootLocalFolder() {
        return this.rootLocalFolder;
    }


    /**
     * Declare files to include using standard <tt>includes</tt> patterns; optional.
     * @param includes A string of filter patterns to include. Separate the
     *                 patterns by spaces.
     * @see #getIncludes()
     * @see #setExcludes(String excludes)
     * @see #getExcludes()
     */
    public void setIncludes(String includes) {
        this.includes = includes;
    }

    /**
     * Gets the patterns from the include filter. Rather that duplicate the
     * details of AntStarTeamCheckOut's filtering here, refer to these
     * links:
     *
     * @return A string of filter patterns separated by spaces.
     * @see #setIncludes(String includes)
     * @see #setExcludes(String excludes)
     * @see #getExcludes()
     */
    public String getIncludes() {
        return includes;
    }

    /**
     * if excludes have been specified, emit the list to the log
     */
    protected void logIncludes() {
        if (DEFAULT_INCLUDESETTING != this.includes) {
            log("  Includes specified: " + this.includes);
        }
    }

    /**
     * Declare files to exclude using standard <tt>excludes</tt> patterns; optional.
     * When filtering files, AntStarTeamCheckOut
     * uses an unmodified version of <code>DirectoryScanner</code>'s
     * <code>match</code> method, so here are the patterns straight from the
     * Ant source code:
     * <br/>
     * Matches a string against a pattern. The pattern contains two special
     * characters:
     * <br/>'*' which means zero or more characters,
     * <br/>'?' which means one and only one character.
     * <br/>
     *  For example, if you want to check out all files except .XML and
     * .HTML files, you would put the following line in your program:
     * <code>setExcludes("*.XML,*.HTML");</code>
     * Finally, note that filters have no effect on the <b>directories</b>
     * that are scanned; you could not skip over all files in directories
     * whose names begin with "project," for instance.
     * <br/>
     * Treatment of overlapping inlcudes and excludes: To give a simplistic
     * example suppose that you set your include filter to "*.htm *.html"
     * and your exclude filter to "index.*". What happens to index.html?
     * AntStarTeamCheckOut will not check out index.html, as it matches an
     * exclude filter ("index.*"), even though it matches the include
     * filter, as well.
     * <br/>
     * Please also read the following sections before using filters:
     *
     * @param excludes A string of filter patterns to exclude. Separate the
     *                 patterns by spaces.
     * @see #setIncludes(String includes)
     * @see #getIncludes()
     * @see #getExcludes()
     */
    public void setExcludes(String excludes) {
        this.excludes = excludes;
    }

    /**
     * Gets the patterns from the exclude filter. Rather that duplicate the
     * details of AntStarTeanCheckOut's filtering here, refer to these
     * links:
     *
     * @return A string of filter patterns separated by spaces.
     * @see #setExcludes(String excludes)
     * @see #setIncludes(String includes)
     * @see #getIncludes()
     */
    public String getExcludes() {
        return excludes;
    }

    /**
     * if excludes have been specified, emit the list to the log
     */
    protected void logExcludes() {
        if (DEFAULT_EXCLUDESETTING != this.excludes) {
            log("  Excludes specified: " + this.excludes);
        }
    }

    // CheckStyle:MethodNameCheck OFF - bc

    /**
     * protected function to allow subclasses to set the label (or not).
     * sets the StarTeam label
     *
     * @param label name of the StarTeam label to be set
     */
    protected void _setLabel(String label) {
        if (null != label) {
            label = label.trim();
            if (label.length() > 0) {
                this.label = label;
            }
        }
    }

    /**
     * non-public method callable only by derived classes that implement
     * setAsOfDate (so that derived tasks that do not accept this
     * parameter will fail if user attempts to use it.
     *
     * @param asOfDate asOfDate entered by user.
     * @since Ant 1.6
     */
    protected void _setAsOfDate(String asOfDate) {
        if (asOfDate != null && asOfDate.length() > 0) {
            this.asOfDate = asOfDate;
        }
    }

    /**
     * non-public method callable only by derived classes that implement
     * setAsOfDateFormat (so that derived tasks that do not accept this
     * parameter will fail if user attempts to use it.
     *
     * @param asOfDateFormat asOfDate format entered by user.
     * @since Ant 1.6
     */
    protected void _setAsOfDateFormat(String asOfDateFormat) {
        if (asOfDateFormat != null && asOfDateFormat.length() > 0) {
            this.asOfDateFormat = asOfDateFormat;
        }
    }

    // CheckStyle:VisibilityModifier ON


    /**
     * return the asOfDate entered by the user for internal use by derived
     * classes.
     *
     * @return the asOfDate entered by the user
     * @since Ant 1.6
     */
    protected String getAsOfDate() {
        return this.asOfDate;
    }

    /**
     * If an asofDate parameter has been supplied by the user return a
     * StarTeam view based on the configuration of the StarTeam view
     * specified the user as of the date specified in the parameter.
     * If no asofDate has been specified, return null.
     *
     * This method is meant to be called from within implementations of the
     * <code>createSnapshotView</code> abstract method.
     *
     * @param raw    the raw view to be configured as of the supplied date
     *
     * @return the view as configured.
     * @exception BuildException
     *                   thrown if the date is not parsable by the default or
     *                   supplied format patterns.
     * @since Ant 1.6
     */
    protected View getViewConfiguredByDate(View raw) throws BuildException {
        if (this.asOfDate == null) {
            return null;
        }
        Date asOfDate = null;
        SimpleDateFormat fmt = null;
        if (this.asOfDateFormat != null) {
            fmt = new SimpleDateFormat(this.asOfDateFormat);
            try {
                asOfDate = fmt.parse(this.asOfDate);
            } catch (ParseException px) {
                throw new BuildException("AsOfDate "
                                         + this.asOfDate
                                         + " not parsable by supplied format "
                                         + this.asOfDateFormat);
            }
        } else {
            try {
                asOfDate = DateUtils.parseIso8601DateTimeOrDate(
                    this.asOfDate);
            } catch (ParseException px) {
                throw new BuildException("AsOfDate "
                                         + this.asOfDate
                                         + " not parsable by default"
                                         + " ISO8601 formats");
            }
        }
        return new View(raw, ViewConfiguration.createFromTime(
            new OLEDate(asOfDate)));
    }

    /**
     * return the label passed to the task by the user as a string
     *
     * @return the label passed to the task by the user as a string
     */
    protected String getLabel() {
        return this.label;
    }

    /**
     * Get the value of recursive.
     * @return value of recursive.
     */
    public boolean isRecursive() {
        return this.recursive;
    }

    /**
     * Flag to set to include files in subfolders in the operation; optional,
     * default true.
     * @param v  Value to assign to recursive.
     */
    public void setRecursive(boolean v) {
        this.recursive = v;
    }

    /**
     * Get the value of preloadFileInformation.
     * @return value of preloadFileInformation.
     */
    public boolean isPreloadFileInformation() {
        return this.preloadFileInformation;
    }

    /**
     * Flag to set to preload file information from the server; optional,
     * default true.
     * Increases performance significantly for projects with many files
     * and/or folders.