javadoc

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

src/main/org/apache/tools/ant/taskdefs/optional/ssh/AbstractSshMessage.java

@@ -1,5 +1,5 @@
 /*
- * Copyright  2003-2004 The Apache Software Foundation
+ * Copyright  2003-2005 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -29,6 +29,9 @@ import java.text.NumberFormat;
 
 import org.apache.tools.ant.BuildException;
 
+/**
+ * Abstract class for ssh upload and download
+ */
 public abstract class AbstractSshMessage {
 
     private Session session;
@@ -39,11 +42,18 @@ public abstract class AbstractSshMessage {
         }
     };
 
+    /**
+     * Constructor for AbstractSshMessage
+     * @param session the ssh session to use
+     */
     public AbstractSshMessage(Session session) {
         this(false, session);
     }
 
     /**
+     * Constructor for AbstractSshMessage
+     * @param verbose if true do verbose logging
+     * @param session the ssh session to use
      * @since Ant 1.6.2
      */
     public AbstractSshMessage(boolean verbose, Session session) {
@@ -51,6 +61,12 @@ public abstract class AbstractSshMessage {
         this.session = session;
     }
 
+    /**
+     * Open an ssh channel.
+     * @param command the command to use
+     * @return the channel
+     * @throws JSchException on error
+     */
     protected Channel openExecChannel(String command) throws JSchException {
         ChannelExec channel = (ChannelExec) session.openChannel("exec");
         channel.setCommand(command);
@@ -58,6 +74,11 @@ public abstract class AbstractSshMessage {
         return channel;
     }
 
+    /**
+     * Send an ack.
+     * @param out the output stream to use
+     * @throws IOException on error
+     */
     protected void sendAck(OutputStream out) throws IOException {
         byte[] buf = new byte[1];
         buf[0] = 0;
@@ -68,6 +89,9 @@ public abstract class AbstractSshMessage {
     /**
      * Reads the response, throws a BuildException if the response
      * indicates an error.
+     * @param in the input stream to use
+     * @throws IOException on I/O error
+     * @throws BuildException on other errors
      */
     protected void waitForAck(InputStream in)
         throws IOException, BuildException {
@@ -102,16 +126,35 @@ public abstract class AbstractSshMessage {
         }
     }
 
+    /**
+     * Carry out the transfer.
+     * @throws IOException on I/O errors
+     * @throws JSchException on ssh errors
+     */
     public abstract void execute() throws IOException, JSchException;
 
+    /**
+     * Set a log listener.
+     * @param aListener the log listener
+     */
     public void setLogListener(LogListener aListener) {
         listener = aListener;
     }
 
+    /**
+     * Log a message to the log listener.
+     * @param message the message to log
+     */
     protected void log(String message) {
         listener.log(message);
     }
 
+    /**
+     * Log transfer stats to the log listener.
+     * @param timeStarted the time started
+     * @param timeEnded   the finishing time
+     * @param totalLength the total length
+     */
     protected void logStats(long timeStarted,
                              long timeEnded,
                              int totalLength) {
@@ -125,15 +168,21 @@ public abstract class AbstractSshMessage {
     }
 
     /**
+     * Is the verbose attribute set.
+     * @return true if the verbose attribute is set
      * @since Ant 1.6.2
      */
     protected final boolean getVerbose() {
         return verbose;
     }
 
-    /*
+    /**
      * Track progress every 10% if 100kb < filesize < 1mb. For larger
      * files track progress for every percent transmitted.
+     * @param filesize the size of the file been transmitted
+     * @param totalLength the total transmission size
+     * @param percentTransmitted the current percent transmitted
+     * @return the percent that the file is of the total
      */
     protected final int trackProgress(int filesize, int totalLength,
                                       int percentTransmitted) {

src/main/org/apache/tools/ant/taskdefs/optional/ssh/Directory.java

@@ -1,5 +1,5 @@
 /*
- * Copyright  2003-2004 The Apache Software Foundation
+ * Copyright  2003-2005 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -22,6 +22,9 @@ import java.util.Iterator;
 import java.util.StringTokenizer;
 import java.io.File;
 
+/**
+ * A helper object for Scp representing a directory in a file system.
+ */
 public class Directory {
 
     private File directory;
@@ -29,10 +32,19 @@ public class Directory {
     private ArrayList files;
     private Directory parent;
 
+    /**
+     * Constructor for a Directory.
+     * @param directory a directory.
+     */
     public Directory(File directory) {
         this(directory,  null);
     }
 
+    /**
+     * Constructor for a Directory.
+     * @param directory a directory
+     * @param parent    a parent Directory
+     */
     public Directory(File directory , Directory parent) {
         this.parent = parent;
         this.childDirectories = new ArrayList();
@@ -40,36 +52,69 @@ public class Directory {
         this.directory = directory;
     }
 
+    /**
+     * Add a directory to the child directories.
+     * @param directory a Directory
+     */
     public void addDirectory(Directory directory) {
         if (!childDirectories.contains(directory)) {
             childDirectories.add(directory);
         }
     }
 
+    /**
+     * Add a file to the list of files.
+     * @param file a file to add
+     */
     public void addFile(File file) {
         files.add(file);
     }
 
+    /**
+     * Get an iterator over the child Directories.
+     * @return an iterator
+     */
     public Iterator directoryIterator() {
         return childDirectories.iterator();
     }
 
+    /**
+     * Get an iterator over the files.
+     * @return an iterator
+     */
     public Iterator filesIterator() {
         return files.iterator();
     }
 
+    /**
+     * Get the parent Directory.
+     * @return the parent Directory.
+     */
     public Directory getParent() {
         return parent;
     }
 
+    /**
+     * Is this a root Directory?
+     * @return true if there is no parent Directory
+     */
     public boolean isRoot() {
         return parent == null;
     }
 
+    /**
+     * Get the directory file.
+     * @return the directory file
+     */
     public File getDirectory() {
         return directory;
     }
 
+    /**
+     * Get a child directory of this directory.
+     * @param dir the directory to look for
+     * @return the child directory, or null if not found
+     */
     public Directory getChild(File dir) {
         for (int i = 0; i < childDirectories.size(); i++) {
             Directory current = (Directory) childDirectories.get(i);
@@ -81,6 +126,12 @@ public class Directory {
         return null;
     }
 
+    /**
+     * The equality method.
+     * This checks if the directory field is the same.
+     * @param obj the object to compare to
+     * @return true if this object has an equal directory field as the other object
+     */
     public boolean equals(Object obj) {
         if (obj == this) {
             return true;
@@ -95,14 +146,28 @@ public class Directory {
         return this.directory.equals(d.directory);
     }
 
+    /**
+     * The hashcode method.
+     * @return the hash code of the directory field
+     */
     public int hashCode() {
         return directory.hashCode();
     }
 
+    /**
+     * Get the path components of this directory.
+     * @return the path components as an array of strings.
+     */
     public String[] getPath() {
         return getPath(directory.getAbsolutePath());
     }
 
+    /**
+     * Convert a file path to an array of path components.
+     * This uses File.sepatator to split the file path string.
+     * @param thePath the file path string to convert
+     * @return an array of path components
+     */
     public static String[] getPath(String thePath) {
         StringTokenizer tokenizer = new StringTokenizer(thePath,
                 File.separator);
@@ -117,6 +182,10 @@ public class Directory {
         return path;
     }
 
+    /**
+     * Get the number of files in the files attribute.
+     * @return the number of files
+     */
     public int fileSize() {
         return files.size();
     }

src/main/org/apache/tools/ant/taskdefs/optional/ssh/LogListener.java

@@ -1,5 +1,5 @@
 /*
- * Copyright  2003-2004 The Apache Software Foundation
+ * Copyright  2003-2005 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -17,6 +17,13 @@
 
 package org.apache.tools.ant.taskdefs.optional.ssh;
 
+/**
+ * Interface for ssh log listeners to implement.
+ */
 public interface LogListener {
+    /**
+     * Method for the loglistener to implement to recieve log messages.
+     * @param message the message to log
+     */
     void log(String message);
 }

src/main/org/apache/tools/ant/taskdefs/optional/ssh/SSHUserInfo.java

@@ -21,6 +21,7 @@ import com.jcraft.jsch.UserInfo;
 import com.jcraft.jsch.UIKeyboardInteractive;
 
 /**
+ * Class containing information on an SSH user.
  */
 public class SSHUserInfo implements UserInfo, UIKeyboardInteractive {
 
@@ -31,11 +32,17 @@ public class SSHUserInfo implements UserInfo, UIKeyboardInteractive {
     private boolean firstTime = true;
     private boolean trustAllCertificates;
 
+    /** Constructor for SSHUserInfo. */
     public SSHUserInfo() {
         super();
         this.trustAllCertificates = false;
     }
 
+    /**
+     * Constructor for SSHUserInfo.
+     * @param password the user's password
+     * @param trustAllCertificates if true trust hosts whose identity is unknown
+     */
     public SSHUserInfo(String password, boolean trustAllCertificates) {
         super();
         this.password = password;
@@ -147,10 +154,22 @@ public class SSHUserInfo implements UserInfo, UIKeyboardInteractive {
         this.keyfile = keyfile;
     }
 
+    // (NOTE: this method does not seem to be called
+    /**
+     * Whether to prompt for a passphase.
+     * @param message ignored
+     * @return true always
+     */
     public boolean promptPassphrase(String message) {
         return true;
     }
 
+    // (NOTE: this method does not seem to be called
+    /**
+     * Whether to prompt for a password.
+     * @param passwordPrompt ignored
+     * @return true the first time this is called, false otherwise
+     */
     public boolean promptPassword(String passwordPrompt) {
         //log(passwordPrompt, Project.MSG_DEBUG);
         if (firstTime) {
@@ -160,11 +179,22 @@ public class SSHUserInfo implements UserInfo, UIKeyboardInteractive {
         return firstTime;
     }
 
+    // (NOTE: this method does not seem to be called
+    /**
+     * Whether to prompt yes or no.
+     * @param message ignored
+     * @return the value of trustAllCertificates
+     */
     public boolean promptYesNo(String message) {
         //log(prompt, Project.MSG_DEBUG);
         return trustAllCertificates;
     }
 
+    // (NOTE: this method does not seem to be called
+    /**
+     * Do nothing.
+     * @param message ignored
+     */
     public void showMessage(String message) {
         //log(message, Project.MSG_DEBUG);
     }

src/main/org/apache/tools/ant/taskdefs/optional/ssh/Scp.java

@@ -1,5 +1,5 @@
 /*
- * Copyright  2003-2004 The Apache Software Foundation
+ * Copyright  2003-2005 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -77,6 +77,7 @@ public class Scp extends SSHBase {
      * Similiar to {@link #setFile setFile} but explicitly states that
      * the file is a local file.  This is the only way to specify a
      * local file with a @ character.
+     * @param aFromUri a string representing the source of the copy.
      * @since Ant 1.6.2
      */
     public void setLocalFile(String aFromUri) {
@@ -87,6 +88,7 @@ public class Scp extends SSHBase {
     /**
      * Similiar to {@link #setFile setFile} but explicitly states that
      * the file is a remote file.
+     * @param aFromUri a string representing the source of the copy.
      * @since Ant 1.6.2
      */
     public void setRemoteFile(String aFromUri) {
@@ -98,6 +100,7 @@ public class Scp extends SSHBase {
      * Similiar to {@link #setTodir setTodir} but explicitly states
      * that the directory is a local.  This is the only way to specify
      * a local directory with a @ character.
+     * @param aToUri a string representing the target of the copy.
      * @since Ant 1.6.2
      */
     public void setLocalTodir(String aToUri) {
@@ -108,6 +111,7 @@ public class Scp extends SSHBase {
     /**
      * Similiar to {@link #setTodir setTodir} but explicitly states
      * that the directory is a remote.
+     * @param aToUri a string representing the target of the copy.
      * @since Ant 1.6.2
      */
     public void setRemoteTodir(String aToUri) {
@@ -118,6 +122,7 @@ public class Scp extends SSHBase {
     /**
      * Changes the file name to the given name while receiving it,
      * only useful if receiving a single file.
+     * @param aToUri a string representing the target of the copy.
      * @since Ant 1.6.2
      */
     public void setLocalTofile(String aToUri) {
@@ -128,6 +133,7 @@ public class Scp extends SSHBase {
     /**
      * Changes the file name to the given name while sending it,
      * only useful if sending a single file.
+     * @param aToUri a string representing the target of the copy.
      * @since Ant 1.6.2
      */
     public void setRemoteTofile(String aToUri) {
@@ -148,6 +154,10 @@ public class Scp extends SSHBase {
         fileSets.add(set);
     }
 
+    /**
+     * Initialize this task.
+     * @throws BuildException on error
+     */
     public void init() throws BuildException {
         super.init();
         this.toUri = null;
@@ -155,6 +165,10 @@ public class Scp extends SSHBase {
         this.fileSets = null;
     }
 
+    /**
+     * Execute this task.
+     * @throws BuildException on error
+     */
     public void execute() throws BuildException {
         if (toUri == null) {
             throw new BuildException("Either 'todir' or 'tofile' attribute "
@@ -176,7 +190,8 @@ public class Scp extends SSHBase {
                     upload(fromUri, toUri);
                 }
             } else if (isFromRemote && isToRemote) {
-                throw new BuildException("Copying from a remote server to a remote server is not supported.");
+                throw new BuildException(
+                    "Copying from a remote server to a remote server is not supported.");
             } else {
                 throw new BuildException("'todir' and 'file' attributes "
                     + "must have syntax like the following: "

src/main/org/apache/tools/ant/taskdefs/optional/ssh/ScpFromMessage.java

@@ -28,6 +28,9 @@ import com.jcraft.jsch.JSchException;
 import com.jcraft.jsch.Session;
 import com.jcraft.jsch.Channel;
 
+/**
+ * A helper object representing an scp download.
+ */
 public class ScpFromMessage extends AbstractSshMessage {
 
     private static final byte LINE_FEED = 0x0a;
@@ -38,6 +41,12 @@ public class ScpFromMessage extends AbstractSshMessage {
     private boolean isRecursive = false;
 
     /**
+     * Constructor for ScpFromMessage.
+     * @param verbose if true log extra information
+     * @param session the Scp session to use
+     * @param aRemoteFile the remote file name
+     * @param aLocalFile  the local file
+     * @param recursive   if true use recursion (-r option to scp)
      * @since Ant 1.6.2
      */
     public ScpFromMessage(boolean verbose,
@@ -51,6 +60,13 @@ public class ScpFromMessage extends AbstractSshMessage {
         this.isRecursive = recursive;
     }
 
+    /**
+     * Constructor for ScpFromMessage.
+     * @param session the Scp session to use
+     * @param aRemoteFile the remote file name
+     * @param aLocalFile  the local file
+     * @param recursive   if true use recursion (-r option to scp)
+     */
     public ScpFromMessage(Session session,
                            String aRemoteFile,
                            File aLocalFile,
@@ -58,6 +74,11 @@ public class ScpFromMessage extends AbstractSshMessage {
         this(false, session, aRemoteFile, aLocalFile, recursive);
     }
 
+    /**
+     * Carry out the transfer.
+     * @throws IOException on i/o errors
+     * @throws JSchException on errors detected by scp
+     */
     public void execute() throws IOException, JSchException {
         String command = "scp -f ";
         if (isRecursive) {

src/main/org/apache/tools/ant/taskdefs/optional/ssh/ScpToMessage.java

@@ -1,5 +1,5 @@
 /*
- * Copyright  2003-2004 The Apache Software Foundation
+ * Copyright  2003-2005 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -28,6 +28,9 @@ import java.io.OutputStream;
 import java.util.List;
 import java.util.Iterator;
 
+/**
+ * Utility class to carry out an upload scp transfer.
+ */
 public class ScpToMessage extends AbstractSshMessage {
 
     private static final int BUFFER_SIZE = 1024;
@@ -37,6 +40,11 @@ public class ScpToMessage extends AbstractSshMessage {
     private List directoryList;
 
     /**
+     * Constructor for a local file to remote.
+     * @param verbose if true do verbose logging
+     * @param session the scp session to use
+     * @param aLocalFile the local file
+     * @param aRemotePath the remote path
      * @since Ant 1.6.2
      */
     public ScpToMessage(boolean verbose,
@@ -49,6 +57,11 @@ public class ScpToMessage extends AbstractSshMessage {
     }
 
     /**
+     * Constructor for a local directories to remote.
+     * @param verbose if true do verbose logging
+     * @param session the scp session to use
+     * @param aDirectoryList a list of directories
+     * @param aRemotePath the remote path
      * @since Ant 1.6.2
      */
     public ScpToMessage(boolean verbose,
@@ -61,6 +74,10 @@ public class ScpToMessage extends AbstractSshMessage {
     }
 
     /**
+     * Constructor for ScpToMessage.
+     * @param verbose if true do verbose logging
+     * @param session the scp session to use
+     * @param aRemotePath the remote path
      * @since Ant 1.6.2
      */
     private ScpToMessage(boolean verbose,
@@ -70,18 +87,35 @@ public class ScpToMessage extends AbstractSshMessage {
         this.remotePath = aRemotePath;
     }
 
+    /**
+     * Constructor for ScpToMessage.
+     * @param session the scp session to use
+     * @param aLocalFile the local file
+     * @param aRemotePath the remote path
+     */
     public ScpToMessage(Session session,
                         File aLocalFile,
                         String aRemotePath) {
         this(false, session, aLocalFile, aRemotePath);
     }
 
+    /**
+     * Constructor for ScpToMessage.
+     * @param session the scp session to use
+     * @param aDirectoryList a list of directories
+     * @param aRemotePath the remote path
+     */
     public ScpToMessage(Session session,
                          List aDirectoryList,
                          String aRemotePath) {
         this(false, session, aDirectoryList, aRemotePath);
     }
 
+    /**
+     * Carry out the transfer.
+     * @throws IOException on i/o errors
+     * @throws JSchException on errors detected by scp
+     */
     public void execute() throws IOException, JSchException {
         if (directoryList != null) {
             doMultipleTransfer();
@@ -212,10 +246,18 @@ public class ScpToMessage extends AbstractSshMessage {
         }
     }
 
+    /**
+     * Get the local file
+     * @return the local file
+     */
     public File getLocalFile() {
         return localFile;
     }
 
+    /**
+     * Get the remote path
+     * @return the remote path
+     */
     public String getRemotePath() {
         return remotePath;
     }

src/main/org/apache/tools/ant/taskdefs/optional/starteam/StarTeamLabel.java

@@ -1,5 +1,5 @@
 /*
- * Copyright  2001-2004 The Apache Software Foundation
+ * Copyright  2001-2005 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -77,14 +77,16 @@ public class StarTeamLabel extends StarTeamTask {
 
 
     /**
-    * The name to be given to the label; required.
-    */
+     * The name to be given to the label; required.
+     * @param label the name to be used
+     */
     public void setLabel(String label) {
         this.labelName = label;
     }
 
     /**
      * Description of the label to be stored in the StarTeam project.
+     * @param description the description to be used
      */
     public void setDescription(String description) {
         this.description = description;
@@ -117,6 +119,8 @@ public class StarTeamLabel extends StarTeamTask {
     /**
      * The timestamp of the build that will be stored with the label; required.
      * Must be formatted <code>yyyyMMddHHmmss</code>
+     * @param lastbuild the timestamp of the last build
+     * @throws BuildException on error
      */
     public void setLastBuild(String lastbuild) throws BuildException {
         try {
@@ -131,7 +135,7 @@ public class StarTeamLabel extends StarTeamTask {
     /**
      * This method does the work of creating the new view and checking it into
      * Starteam.
-     *
+     * @throws BuildException on error
      */
     public void execute() throws BuildException {
 

src/main/org/apache/tools/ant/taskdefs/optional/starteam/StarTeamTask.java

@@ -1,5 +1,5 @@
 /*
- * Copyright  2001-2004 The Apache Software Foundation
+ * Copyright  2001-2005 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -304,6 +304,7 @@ public abstract class StarTeamTask extends Task {
      *
      * @param rawview the unconfigured <code>View</code>
      * @return the snapshot <code>View</code> appropriately configured.
+     * @throws BuildException on error
      */
     protected abstract View createSnapshotView(View rawview)
     throws BuildException;
@@ -317,6 +318,7 @@ public abstract class StarTeamTask extends Task {
      * @return the <code>View</code> that will be used for processing.
      * @see #createSnapshotView(View)
      * @see #getServer()
+     * @throws BuildException on error
      */
     protected View openView() throws BuildException {