From 0110162c6f9c51c80cd7f21805bbbed8e3813648 Mon Sep 17 00:00:00 2001 From: Peter Reilly Date: Fri, 8 Jul 2005 13:48:44 +0000 Subject: [PATCH] javadoc git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@278455 13f79535-47bb-0310-9956-ffa450edef68 --- .../optional/ssh/AbstractSshMessage.java | 53 +++++++++++++- .../ant/taskdefs/optional/ssh/Directory.java | 71 ++++++++++++++++++- .../taskdefs/optional/ssh/LogListener.java | 9 ++- .../taskdefs/optional/ssh/SSHUserInfo.java | 30 ++++++++ .../tools/ant/taskdefs/optional/ssh/Scp.java | 19 ++++- .../taskdefs/optional/ssh/ScpFromMessage.java | 21 ++++++ .../taskdefs/optional/ssh/ScpToMessage.java | 44 +++++++++++- .../optional/starteam/StarTeamLabel.java | 12 ++-- .../optional/starteam/StarTeamTask.java | 4 +- 9 files changed, 251 insertions(+), 12 deletions(-) diff --git a/src/main/org/apache/tools/ant/taskdefs/optional/ssh/AbstractSshMessage.java b/src/main/org/apache/tools/ant/taskdefs/optional/ssh/AbstractSshMessage.java index ac12dff39..dd4586365 100644 --- a/src/main/org/apache/tools/ant/taskdefs/optional/ssh/AbstractSshMessage.java +++ b/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) { diff --git a/src/main/org/apache/tools/ant/taskdefs/optional/ssh/Directory.java b/src/main/org/apache/tools/ant/taskdefs/optional/ssh/Directory.java index 4782b5953..66f1f4e78 100644 --- a/src/main/org/apache/tools/ant/taskdefs/optional/ssh/Directory.java +++ b/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(); } diff --git a/src/main/org/apache/tools/ant/taskdefs/optional/ssh/LogListener.java b/src/main/org/apache/tools/ant/taskdefs/optional/ssh/LogListener.java index b742cdba0..289b98102 100644 --- a/src/main/org/apache/tools/ant/taskdefs/optional/ssh/LogListener.java +++ b/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); } diff --git a/src/main/org/apache/tools/ant/taskdefs/optional/ssh/SSHUserInfo.java b/src/main/org/apache/tools/ant/taskdefs/optional/ssh/SSHUserInfo.java index 3337ac216..857d6e212 100644 --- a/src/main/org/apache/tools/ant/taskdefs/optional/ssh/SSHUserInfo.java +++ b/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); } diff --git a/src/main/org/apache/tools/ant/taskdefs/optional/ssh/Scp.java b/src/main/org/apache/tools/ant/taskdefs/optional/ssh/Scp.java index 38d9659b0..42848348a 100644 --- a/src/main/org/apache/tools/ant/taskdefs/optional/ssh/Scp.java +++ b/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: " diff --git a/src/main/org/apache/tools/ant/taskdefs/optional/ssh/ScpFromMessage.java b/src/main/org/apache/tools/ant/taskdefs/optional/ssh/ScpFromMessage.java index e1e6c3209..cfb2494f1 100644 --- a/src/main/org/apache/tools/ant/taskdefs/optional/ssh/ScpFromMessage.java +++ b/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) { diff --git a/src/main/org/apache/tools/ant/taskdefs/optional/ssh/ScpToMessage.java b/src/main/org/apache/tools/ant/taskdefs/optional/ssh/ScpToMessage.java index 9f0a358b6..fd31a2c8b 100644 --- a/src/main/org/apache/tools/ant/taskdefs/optional/ssh/ScpToMessage.java +++ b/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; } diff --git a/src/main/org/apache/tools/ant/taskdefs/optional/starteam/StarTeamLabel.java b/src/main/org/apache/tools/ant/taskdefs/optional/starteam/StarTeamLabel.java index 122712742..80a9518c2 100644 --- a/src/main/org/apache/tools/ant/taskdefs/optional/starteam/StarTeamLabel.java +++ b/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 yyyyMMddHHmmss + * @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 { diff --git a/src/main/org/apache/tools/ant/taskdefs/optional/starteam/StarTeamTask.java b/src/main/org/apache/tools/ant/taskdefs/optional/starteam/StarTeamTask.java index d063b6356..3d9f38681 100644 --- a/src/main/org/apache/tools/ant/taskdefs/optional/starteam/StarTeamTask.java +++ b/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 View * @return the snapshot View 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 View that will be used for processing. * @see #createSnapshotView(View) * @see #getServer() + * @throws BuildException on error */ protected View openView() throws BuildException {