treebasedtask.java

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

     * @param v  Value to assign to preloadFileInformation.
     */
    public void setPreloadFileInformation(boolean v) {
        this.preloadFileInformation = v;
    }

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

    /**
     * Flag to force actions regardless of the status
     * that StarTeam is maintaining for the file; optional, default false.
     * If <tt>rootlocalfolder</tt> is set then
     * this should be set "true" as otherwise the checkout will be based on statuses
     * which do not relate to the target folder.
     * @param v  Value to assign to forced.
     */
    public void setForced(boolean v) {
        this.forced = v;
    }

    /**
     *  returns true if a label has been specified and it is a view label.
     *
     * @return  true if a label has been specified and it is a view label
     */
    protected boolean isUsingViewLabel() {
        return null != this.labelInUse && this.labelInUse.isViewLabel();
    }

    /**
     *  returns true if a label has been specified and it is a revision label.
     *
     * @return  true if a label has been specified and it is a revision label
     */
    protected boolean isUsingRevisionLabel() {
        return null != this.labelInUse && this.labelInUse.isRevisionLabel();
    }

    /**
     * returns the label being used
     *
     * @return the label being used
     */
    protected Label getLabelInUse() {
        return this.labelInUse;
    }

    /**
     * show the label in the log and its type.
     */
    protected void logLabel() {
        if (this.isUsingViewLabel()) {
            log("  Using view label " + getLabel());
        } else if (this.isUsingRevisionLabel()) {
            log("  Using revision label " + getLabel());
        }
    }

    /**
     * show the asofDate in the log
     * @since Ant 1.6
     */
    protected void logAsOfDate() {
        if (null != this.asOfDate) {
            log("  Using view as of date " + getAsOfDate());
        }
    }

    ///////////////////////////////////////////////////////////////
    // INCLUDE-EXCLUDE processing
    ///////////////////////////////////////////////////////////////

    /**
     * Look if the file should be processed by the task.
     * Don't process it if it fits no include filters or if
     * it fits an exclude filter.
     *
     * @param pName  the item name to look for being included.
     *
     * @return whether the file should be processed or not.
     */
    protected boolean shouldProcess(String pName) {
        boolean includeIt = matchPatterns(getIncludes(), pName);
        boolean excludeIt = matchPatterns(getExcludes(), pName);
        return (includeIt && !excludeIt);
    }

    /**
     * Convenience method to see if a string match a one pattern
     * in given set of space-separated patterns.
     * @param patterns the space-separated list of patterns.
     * @param pName the name to look for matching.
     * @return whether the name match at least one pattern.
     */
    protected boolean matchPatterns(String patterns, String pName) {
        if (patterns == null) {
            return false;
        }
        StringTokenizer exStr = new StringTokenizer(patterns, ",");
        while (exStr.hasMoreTokens()) {
            if (DirectoryScanner.match(exStr.nextToken(), pName)) {
                return true;
            }
        }
        return false;
    }

    /**
     * Finds and opens the root starteam folder of the operation specified
     * by this task.  This will be one of the following cases:
     *
     * @return Starteam's root folder for the operation.
     * @exception BuildException
     *                   if the root folder cannot be found in the repository
     */
    private Folder configureRootStarteamFolder()
        throws BuildException {
        Folder starteamrootfolder = null;
        try {
            // no root local mapping has been specified.
            View snapshot = openView();

            // find the starteam folder specified to be the root of the
            // operation.  Throw if it can't be found.

            starteamrootfolder =
                    StarTeamFinder.findFolder(snapshot.getRootFolder(),
                            this.rootStarteamFolder);

            if (this.isPreloadFileInformation()) {
                PropertyNames pn = getServer().getPropertyNames();
                String[] props = new String[] {pn.FILE_NAME, pn.FILE_PATH,
                                               pn.FILE_STATUS, pn.MODIFIED_TIME,
                                               pn.FILE_FILE_TIME_AT_CHECKIN,
                                               pn.MODIFIED_USER_ID, pn.FILE_SIZE,
                                               pn.FILE_ENCODING};

                int depth = this.isRecursive() ? -1 : 0;
                starteamrootfolder.populateNow(getServer().getTypeNames().FILE,
                                                props, depth);
            }


        } catch (BuildException e) {
            throw e;
        } catch (Exception e) {
            StringBuffer msg = new StringBuffer("Unable to find root folder ")
                    .append(this.rootStarteamFolder)
                    .append(" in repository at ")
                    .append(getURL());
            if (this.label != null) {
                msg.append(" using specified label ").append(this.label);
            }
            if (this.asOfDate != null) {
                msg.append(" as of specified date ")
                    .append(this.asOfDate);
            }
            throw new BuildException(msg.toString(), e);

        }

        if (null == starteamrootfolder) {
            throw new BuildException("Unable to find root folder "
                + this.rootStarteamFolder + " in repository at " + getURL());
        }

        return starteamrootfolder;
    }

    /**
     * Returns the local folder mapped to the given StarTeam root folder
     * of the operation.  There are two cases here, depending on whether
     * <code>rootLocalFolder</code> is defined.
     * If <code>rootLocalFolder</code> is defined, it will be used to
     * establish a root mapping.  Otherwise, the repository's default root
     * folder will be used.
     *
     * @param starteamrootfolder
     *               root Starteam folder initialized for the operation
     *
     * @return the local folder corresponding to the root Starteam folder.
     * @see findRootStarteamFolder
     */
    private java.io.File getLocalRootMapping(Folder starteamrootfolder) {
        // set the local folder.
        String localrootfolder;
        if (null != this.rootLocalFolder) {
            localrootfolder = rootLocalFolder;
        } else  {
            // either use default path or root local mapping,
            // which is now embedded in the root folder
            localrootfolder = starteamrootfolder.getPathFragment();
        }

        return new java.io.File(localrootfolder);

    }

    /**
     * extenders should emit to the log an entry describing the parameters
     * that will be used by this operation.
     *
     * @param starteamrootFolder
     *               root folder in StarTeam for the operation
     * @param targetrootFolder
     *               root local folder for the operation (whether specified by the user or not.
     */
    protected abstract void logOperationDescription(
        Folder starteamrootFolder, java.io.File targetrootFolder);

    /**
     * This method does the work of opening the supplied  Starteam view and
     * calling the <code>visit()</code> method to perform the task.
     * Derived classes can customize the called methods
     * <code>testPreconditions()</code> and <code>visit()</code>.
     *
     * @exception BuildException if any error occurs in the processing
     * @see <code>testPreconditions()</code>
     * @see <code>visit()</code>
     */

    public final void execute() throws BuildException {
        try {

            Folder starteamrootfolder = configureRootStarteamFolder();

            // set the local folder.
            java.io.File localrootfolder =
                getLocalRootMapping(starteamrootfolder);

            testPreconditions();

            // Tell user what he is doing
            logOperationDescription(starteamrootfolder, localrootfolder);

            // Inspect everything in the root folder and then recursively
            visit(starteamrootfolder, localrootfolder);

        } catch (Exception e) {
            throw new BuildException(e);
        } finally {
            disconnectFromServer();
        }
    }

    private void findLabel(View v) throws BuildException {
        Label[] allLabels = v.getLabels();
        for (int i = 0; i < allLabels.length; i++) {
            Label stLabel = allLabels[i];
            log("checking label " + stLabel.getName(), Project.MSG_DEBUG);
            if (stLabel != null && !stLabel.isDeleted() && stLabel.getName().equals(this.label)) {
                if (!stLabel.isRevisionLabel() && !stLabel.isViewLabel()) {
                    throw new BuildException("Unexpected label type.");
                }
                log("using label " + stLabel.getName(), Project.MSG_VERBOSE);
                this.labelInUse = stLabel;
                return;
            }
        }
        throw new BuildException("Error: label "
                + this.label
                + " does not exist in view "
                + v.getFullName());

    }

    /**
     * Helper method calls on the StarTeam API to retrieve an ID number
     * for the specified view, corresponding to this.label.
     * @param v the <code>View</code> in which to search for <code>this.label</code>
     * @return the ID number corresponding to <code>this.label</code> or -1 if
     *         no label was provided.
     * @exception BuildException if <code>this.label</code> does not correspond
     *                           to any label in the supplied view
     */
    protected int getLabelID(View v) throws BuildException {
        if (null != this.label) {
            findLabel(v);
            return this.labelInUse.getID();
        }
        return -1;
    }

    /**
     * Get the id of the label in use.
     * @return id of the label in use, if labelinuse is present,
     *         otherwise return null
     */
    protected int getIDofLabelInUse() {
        if (null != this.labelInUse) {
            return this.labelInUse.getID();
        }
        return -1;
    }

    /**
     * Derived classes must override this class to define actual processing
     * to be performed on each folder in the tree defined for the task
     *
     * @param rootStarteamFolder
     *               the StarTeam folderto be visited
     * @param rootLocalFolder
     *               the local mapping of rootStarteamFolder
     *
     * @throws BuildException on error
     */
    protected abstract void visit(Folder rootStarteamFolder,
                                  java.io.File rootLocalFolder)
            throws BuildException;

    /**
     * Derived classes must override this method to define tests for
     * any preconditons required by the task.  This method is called at
     * the beginning of the execute() method.
     *
     * @exception BuildException throw if any fatal error exists in the
     * parameters supplied.  If there is a non-fatal condition, just writing
     * to the log may be appropriate.
     * @see <code>execute()</code>
     */
    protected abstract void testPreconditions() throws BuildException;

    /**
     * Return the full repository path name of a file.  Surprisingly there's
     * no method in com.starbase.starteam.File to provide this.
     *
     * @param remotefile the Star Team file whose path is to be returned
     *
     * @return the full repository path name of a file.
     */
    public static String getFullRepositoryPath(
        com.starbase.starteam.File remotefile) {
        StringBuffer sb = new StringBuffer();
        sb.append(remotefile.getParentFolderHierarchy())
          .append(remotefile.getName());
        return sb.toString();
    }

    /**
     * This class implements a map of existing local files to possibly
     * existing repository files.  The map is created by a TreeBasedTask
     * upon recursing into a directory.  Each local item is mapped to an
     * unattached StarTeam object of the proper type, File->File and
     * Directory->Folder.
     *
     * As the TreeBased does its work, it deletes from the map all items
     * it has processed.
     *
     * When the TreeBased task processes all the items from the repository,
     * whatever items left in the UnmatchedFileMap are uncontrolled items
     * and can be processed as appropriate to the task.  In the case of
     * Checkouts, they can be optionally deleted from the local tree.  In the
     * case of Checkins they can optionally be added to the repository.
     */
    protected abstract class UnmatchedFileMap extends Hashtable {

        /**
         * initializes the UnmatchedFileMap with entries from the local folder
         * These will be mapped to the corresponding StarTeam entry even though
         * it will not, in fact, exist in the repository.  But through it, it
         * can be added, listed, etc.
         *
         * @param localFolder
         *        the local folder from which the mappings will be made.
         * @param remoteFolder
         *        the corresponding StarTeam folder which will be processed.
         */
        UnmatchedFileMap init(java.io.File localFolder, Folder remoteFolder) {
            if (!localFolder.exists()) {
                return this;
            }

            String[] localFiles = localFolder.list();

            for (int i = 0; i < localFiles.length; i++) {
                String fn = localFiles[i];
                java.io.File localFile =
                    new java.io.File(localFolder, localFiles[i]).getAbsoluteFile();

                log("adding " + localFile + " to UnmatchedFileMap",
                    Project.MSG_DEBUG);

                if (localFile.isDirectory()) {
                    this.put(localFile, new Folder(remoteFolder, fn, fn));
                } else {
                    com.starbase.starteam.File remoteFile =
                        new com.starbase.starteam.File(remoteFolder);
                    remoteFile.setName(fn);
                    this.put(localFile, remoteFile);
                }
            }
            return this;
        }

        /**
         * remove an item found to be controlled from the map.
         *
         * @param localFile the local item found to be controlled.
         */
        void removeControlledItem(java.io.File localFile) {
            if (isActive()) {
                log("removing processed " + localFile.getAbsoluteFile()
                    + " from UnmatchedFileMap", Project.MSG_DEBUG);
                this.remove(localFile.getAbsoluteFile());
            }
        }
        /**
         * override will perform the action appropriate for its task to perform
         * on items which are on the local tree but not in StarTeam.  It is
         * assumed that this method will not be called until all the items in
         * the corresponding folder have been processed, and that the internal
         * map * will contain only uncontrolled items.
         */
        abstract void processUncontrolledItems() throws BuildException;

        /**
         * overrides must define this to declare how this method knows if it
         * is active.  This presents extra clock cycles when the functionality
         * is not called for.
         *
         * @return True if this object is to perform its functionality.
         */
        protected abstract boolean isActive();

    }

}