New p4labelsync task - update in documentation of Perforce tasks

PR: 18431


git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@274612 13f79535-47bb-0310-9956-ffa450edef68

docs/manual/OptionalTasks/perforce.html

@@ -9,6 +9,7 @@
     <li>Les Hughes (<a href="mailto:leslie.hughes@rubus.com">leslie.hughes@rubus.com</a>)</li>
     <li>Kirk Wylie (<a href="mailto:kirk@radik.com">kirk@radik.com</a>)</li>
     <li>Matt Bishop (<a href="mailto:matt@thebishops.org">matt@thebishops.org</a>)</li>
+    <li>Antoine Levy-Lambert (<a href="mailto:levylambert@tiscali-dsl.de">levylambert@tiscali-dsl.de</a>)</li>
 </ul>
 <p>Version $Revision$ - $Date$</p>
 <hr>
@@ -61,6 +62,10 @@ You will also need the Perforce client executable (p4 or p4.exe but not p4win.ex
         <td><a href="#p4label">P4Label</a></td>
         <td>Create a label reflecting files in the current workspace</td>
     </tr>
+    <tr>
+        <td><a href="#p4labelsync">P4Labelsync</a></td>
+        <td>Syncs an existing label</td>
+    </tr>
     <tr>
         <td><a href="#p4counter">P4Counter</a></td>
         <td>Obtain or set the value of a counter</td>
@@ -202,23 +207,6 @@ For more information regarding the underlying 'p4' commands you are referred to
 available from the <a href="http://www.perforce.com/" target="_top">Perforce website</a>.
 </p>
 
-<h3>Taskdefs</h3>
-<p>Standard taskdefs (for you to copy'n'paste) -- normally this is done automatically if you install this optional task.</p>
-<pre>
-    &lt;taskdef name=&quot;p4sync&quot; classname=&quot;org.apache.tools.ant.taskdefs.optional.perforce.P4Sync&quot;/&gt;
-    &lt;taskdef name=&quot;p4change&quot; classname=&quot;org.apache.tools.ant.taskdefs.optional.perforce.P4Change&quot;/&gt;
-    &lt;taskdef name=&quot;p4edit&quot; classname=&quot;org.apache.tools.ant.taskdefs.optional.perforce.P4Edit&quot;/&gt;
-    &lt;taskdef name=&quot;p4submit&quot; classname=&quot;org.apache.tools.ant.taskdefs.optional.perforce.P4Submit&quot;/&gt;
-    &lt;taskdef name=&quot;p4have&quot; classname=&quot;org.apache.tools.ant.taskdefs.optional.perforce.P4Have&quot;/&gt;
-    &lt;taskdef name=&quot;p4label&quot; classname=&quot;org.apache.tools.ant.taskdefs.optional.perforce.P4Label&quot;/&gt;
-    &lt;taskdef name=&quot;p4counter&quot; classname=&quot;org.apache.tools.ant.taskdefs.optional.perforce.P4Counter&quot;/&gt;
-    &lt;taskdef name=&quot;p4reopen&quot; classname=&quot;org.apache.tools.ant.taskdefs.optional.perforce.P4Reopen&quot;/&gt;
-    &lt;taskdef name=&quot;p4revert&quot; classname=&quot;org.apache.tools.ant.taskdefs.optional.perforce.P4Revert&quot;/&gt;
-    &lt;taskdef name=&quot;p4add&quot; classname=&quot;org.apache.tools.ant.taskdefs.optional.perforce.P4Add&quot;/&gt;
-    &lt;taskdef name=&quot;p4delete&quot; classname=&quot;org.apache.tools.ant.taskdefs.optional.perforce.P4Delete&quot;/&gt;
-    &lt;taskdef name=&quot;p4integrate&quot; classname=&quot;org.apache.tools.ant.taskdefs.optional.perforce.P4Integrate&quot;/&gt;
-    &lt;taskdef name=&quot;p4resolve&quot; classname=&quot;org.apache.tools.ant.taskdefs.optional.perforce.P4Resolve&quot;/&gt;
-</pre>
 
 <hr>
 <h2>Task Descriptions</h2>
@@ -423,6 +411,96 @@ is not the latest any more.
 <hr>
 
 
+<h2><a name="p4labelsync">P4Labelsync</a></h2>
+<h3>Description:</h3>
+<p>Syncs an existing label against the current workspace or against specified revisions.
+</p>
+<h3>Parameters</h3>
+<table border="1" cellpadding="2" cellspacing="0">
+  <tr>
+    <td valign="top"><b>Attribute</b></td>
+    <td valign="top"><b>Description</b></td>
+    <td align="center" valign="top"><b>Required</b></td>
+    <td align="center" valign="top"><b>Perforce command line flag</b></td>
+  </tr>
+  <tr>
+    <td valign="top">name</td>
+    <td valign="top">The name of the label</td>
+    <td valign="center" align="center">Yes</td>
+    <td valign="top" align="center">-l labelname</td>
+  </tr>
+  <tr>
+    <td valign="top">view</td>
+    <td valign="top">
+    list of files or revision specs separated by : or ;<br>
+    in the absence of this attribute, the labelsync will be done against the current Perforce client or the value of the p4client attribute or the value of the p4.client property or the value of the environment variable P4CLIENT</td>
+    <td valign="center" align="center">No</td>
+    <td valign="center" align="center">file[revRange] ... </td>
+  </tr>
+  <tr>
+    <td valign="top">simulationmode</td>
+    <td valign="top">Displays which effect the operation would have on the label but do not actually do it</td>
+    <td valign="center" align="center">No</td>
+    <td valign="top" align="center">-n</td>
+  </tr>
+  <tr>
+    <td valign="top">add</td>
+    <td valign="top">If set to true, preserve files which exist in the label, but not in the current view</td>
+    <td valign="center" align="center">No</td>
+    <td valign="top" align="center">-a</td>
+  </tr>
+  <tr>
+    <td valign="top">delete</td>
+    <td valign="top">If set to true, remove from the label the files mentioned in the view attribute</td>
+    <td valign="center" align="center">No</td>
+    <td valign="top" align="center">-d</td>
+  </tr>
+
+
+</table>
+<h3>Examples</h3>
+<pre>
+&lt;
+p4labelsync
+name=&quot;current_release&quot;
+view="//depot/...#head;//depot2/file1#25"
+add=&quot;true&quot;
+/&gt;
+</pre>
+This example will add into the label called <i>current_release</i> the current head revision of all the files located under <i>//depot</i>
+and the revision 25 of the file <i>//depot2/file1</i>.
+<pre>
+&lt;
+p4labelsync
+name=&quot;current_release&quot;
+p4client=&quot;myclient&quot;
+/&gt;
+</pre>
+This example will update the label called <i>current_release</i> so that it reflects the Perforce client <i>myclient</i>.<br>
+Files present in the label before the sync and not present currently in the client will be removed from the label, because the add attribute is not set.
+<pre>
+&lt;
+p4labelsync
+name=&quot;current_release&quot;
+/&gt;
+</pre>
+This example will update the label called <i>current_release</i> so that it reflects the current default client for the ant Perforce tasks.<br>
+The default client is by order of priority :
+<ul>
+<li>
+the value of the p4.client property if set in the project
+</li>
+<li>
+the value of the P4CLIENT environment variable
+</li>
+<li>
+the default Perforce client from the Windows registry under Windows operating systems
+</li>
+</ul>
+Files present in the label before the sync and not present currently in the client will be removed from the label, because the add attribute is not set.
+<hr>
+
+
 <h2><a name="p4counter">P4Counter</a></h2>
 <h3>Description:</h3>
 <p>
@@ -873,6 +951,13 @@ P4Resolve does not use a change list number (it takes it from the files it is wo
                      additional global options to be set.<br>
                      Added p4fstat task</td>
 </tr>
+<tr>
+    <td valign="top">May 2003</td>
+    <td valign="top">V1.3</td>
+    <td valign="top">Added p4labelsync, p4resolve, p4integrate.<br>
+                     Changed p4submit (detection of changes of change numbers,
+                     and of failed submits due to resolution needed)</td>
+</tr>
 </table>
 <hr>
 <p align="center">Copyright &copy; 2001-2003 Apache Software Foundation. All rights

src/main/org/apache/tools/ant/taskdefs/defaults.properties

@@ -128,6 +128,7 @@ pvcs=org.apache.tools.ant.taskdefs.optional.pvcs.Pvcs
 p4change=org.apache.tools.ant.taskdefs.optional.perforce.P4Change
 p4delete=org.apache.tools.ant.taskdefs.optional.perforce.P4Delete
 p4label=org.apache.tools.ant.taskdefs.optional.perforce.P4Label
+p4labelsync=org.apache.tools.ant.taskdefs.optional.perforce.P4Labelsync
 p4have=org.apache.tools.ant.taskdefs.optional.perforce.P4Have
 p4sync=org.apache.tools.ant.taskdefs.optional.perforce.P4Sync
 p4edit=org.apache.tools.ant.taskdefs.optional.perforce.P4Edit

src/main/org/apache/tools/ant/taskdefs/optional/perforce/P4Labelsync.java

@@ -0,0 +1,179 @@
+/*
+ * The Apache Software License, Version 1.1
+ *
+ * Copyright (c) 2000-2003 The Apache Software Foundation.  All rights
+ * reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in
+ *    the documentation and/or other materials provided with the
+ *    distribution.
+ *
+ * 3. The end-user documentation included with the redistribution, if
+ *    any, must include the following acknowlegement:
+ *       "This product includes software developed by the
+ *        Apache Software Foundation (http://www.apache.org/)."
+ *    Alternately, this acknowlegement may appear in the software itself,
+ *    if and wherever such third-party acknowlegements normally appear.
+ *
+ * 4. The names "Ant" and "Apache Software
+ *    Foundation" must not be used to endorse or promote products derived
+ *    from this software without prior written permission. For written
+ *    permission, please contact apache@apache.org.
+ *
+ * 5. Products derived from this software may not be called "Apache"
+ *    nor may "Apache" appear in their names without prior written
+ *    permission of the Apache Group.
+ *
+ * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
+ * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation.  For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ */
+/*
+ * Portions of this software are based upon public domain software
+ * originally written at the National Center for Supercomputing Applications,
+ * University of Illinois, Urbana-Champaign.
+ */
+
+package org.apache.tools.ant.taskdefs.optional.perforce;
+
+import java.text.SimpleDateFormat;
+import java.util.Date;
+import org.apache.tools.ant.BuildException;
+import org.apache.tools.ant.Project;
+import org.apache.tools.ant.util.StringUtils;
+
+/**
+ *  Syncs an existing Perforce label against the Perforce client
+ *  or against a set of files/revisions
+ *
+ *
+ * Example Usage:
+ * <pre>
+ *   &lt;p4labelsync name="MyLabel-${TSTAMP}-${DSTAMP}" view="//depot/...#head;//depot2/file1#25" /&gt;
+ * </pre>
+ *
+ * @author <A HREF="mailto:levylambert@tiscali-dsl.de">Antoine Levy-Lambert</A>
+ *
+ * @ant.task category="scm"
+ */
+public class P4Labelsync extends P4Base {
+
+    protected String name;
+    private boolean add; /* -a */
+    private boolean delete; /* -n */
+    private boolean simulationmode;  /* -n */
+    /**
+     * -a flag of p4 labelsync - preserve files which exist in the label, but not in the current view
+     * @return  add attribute
+     * if set to true the task will not remove any files from the label
+     * only add files which were not there previously or update these where the revision has changed
+     * the add attribute is the -a flag of p4 labelsync
+     */
+    public boolean isAdd() {
+        return add;
+    }
+    /**
+     * -a flag of p4 labelsync - preserve files which exist in the label, but not in the current view
+     * @param add  if set to true the task will not remove any files from the label
+     * only add files which were not there previously or update these where the revision has changed
+     * the add attribute is the -a flag of p4 labelsync
+     */
+    public void setAdd(boolean add) {
+        this.add = add;
+    }
+    /**
+     * -d flag of p4 labelsync; indicates an intention of deleting from the label the files specified in the view
+     * @return  delete attribute
+     */
+    public boolean isDelete() {
+        return delete;
+    }
+
+    /**
+     * -d flag of p4 labelsync; indicates an intention of deleting from the label the files specified in the view
+     * @param delete
+     */
+    public void setDelete(boolean delete) {
+        this.delete = delete;
+    }
+
+
+    /**
+     * The name of the label; optional, default "AntLabel"
+     */
+    public void setName(String name) {
+        this.name = name;
+    }
+    /**
+     * -n flag of p4 labelsync - display changes without actually doing them
+     * @return -n flag of p4 labelsync
+     */
+    public boolean isSimulationmode() {
+        return simulationmode;
+    }
+    /**
+     * -n flag of p4 labelsync - display changes without actually doing them
+     * @param simulationmode
+     */
+    public void setSimulationmode(boolean simulationmode) {
+        this.simulationmode = simulationmode;
+    }
+
+
+    /**
+     *  do the work
+     */
+    public void execute() throws BuildException {
+        log("P4Labelsync exec:", Project.MSG_INFO);
+
+        if (P4View != null && P4View.length() >= 1) {
+            P4View = StringUtils.replace(P4View, ":", "\n\t");
+            P4View = StringUtils.replace(P4View, ";", "\n\t");
+        }
+        if (P4View == null) {
+            P4View="";
+        }
+
+        if (name == null || name.length() < 1) {
+            throw new BuildException("name attribute is compulsory for labelsync");
+        }
+
+        if ( this.isSimulationmode() ) {
+            P4CmdOpts = P4CmdOpts + " -n";
+        }
+        if ( this.isDelete() ) {
+            P4CmdOpts = P4CmdOpts + " -d";
+        }
+        if ( this.isAdd() ) {
+            P4CmdOpts = P4CmdOpts + " -a";
+        }
+
+        execP4Command("-s labelsync -l "+name +" "+ P4CmdOpts + " " + P4View, new SimpleP4OutputHandler(this));
+
+
+    }
+}
+

src/main/org/apache/tools/ant/taskdefs/optional/perforce/SimpleP4OutputHandler.java

@@ -84,8 +84,11 @@ public class SimpleP4OutputHandler extends P4HandlerAdapter {
         //Others mark errors as info, for example edit a file
         //which is already open for edit.....
         //Just look for error: - catches most things....
+        //when running labelsync, if view elements are in sync, Perforce produces a line of output
+        //looking like this one :
+        //error: //depot/file2 - label in sync.
 
-        if (parent.util.match("/error:/", line) && !parent.util.match("/up-to-date/", line)) {
+        if (parent.util.match("/error:/", line) && !parent.util.match("/up-to-date/", line) && !parent.util.match("/label in sync/", line)) {
             throw new BuildException(line);
 
         }