stevel 2002/06/19 20:45:13
Modified: src/main/org/apache/tools/ant/taskdefs Tag: ANT_15_BRANCH
Property.java Recorder.java Rmic.java
SendEmail.java
Log:
updated javadocs. Would be good to go back and flesh out the getters, some
time.
Revision Changes Path
No revision
No revision
1.48.2.4 +128 -2
jakarta-ant/src/main/org/apache/tools/ant/taskdefs/Property.java
Index: Property.java
===================================================================
RCS file:
/home/cvs/jakarta-ant/src/main/org/apache/tools/ant/taskdefs/Property.java,v
retrieving revision 1.48.2.3
retrieving revision 1.48.2.4
diff -u -r1.48.2.3 -r1.48.2.4
--- Property.java 11 Jun 2002 08:14:15 -0000 1.48.2.3
+++ Property.java 20 Jun 2002 03:45:12 -0000 1.48.2.4
@@ -70,8 +70,31 @@
import java.util.Enumeration;
/**
- * Will set a Project property. Used to be a hack in ProjectHelper
- * Will not override values set by the command line or parent projects.
+ * Sets a property by name, or set of properties (from file or
+ * resource) in the project. </p>
+ * Properties are immutable: whoever sets a property first freezes it for the
+ * of the build; they are most definately not variable.
+ * <p>There are five ways to set properties:</p>
+ * <ul>
+ * <li>By supplying both the <i>name</i> and <i>value</i> attribute.</li>
+ * <li>By supplying both the <i>name</i> and <i>refid</i> attribute.</li>
+ * <li>By setting the <i>file</i> attribute with the filename of the
property
+ * file to load. This property file has the format as defined by the
file used
+ * in the class java.util.Properties.</li>
+ * <li>By setting the <i>resource</i> attribute with the resource name of
the
+ * property file to load. This property file has the format as defined
by the
+ * file used in the class java.util.Properties.</li>
+ * <li>By setting the <i>environment</i> attribute with a prefix to use.
+ * Properties will be defined for every environment variable by
+ * prefixing the supplied name and a period to the name of the
variable.</li>
+ * </ul>
+ * <p>Although combinations of these ways are possible, only one should be
used
+ * at a time. Problems might occur with the order in which properties are
set, for
+ * instance.</p>
+ * <p>The value part of the properties being set, might contain references
to other
+ * properties. These references are resolved at the time these properties
are set.
+ * This also holds for properties loaded from a property file.</p>
+ * Properties are case sensitive.
*
* @author [EMAIL PROTECTED]
* @author <a href="mailto:[EMAIL PROTECTED]">Sam Ruby</a>
@@ -111,6 +134,10 @@
this.fallback = fallback;
}
+ /**
+ * sets the name of the property to set.
+ * @param name property name
+ */
public void setName(String name) {
this.name = name;
}
@@ -119,18 +146,36 @@
return name;
}
+ /**
+ * Sets the property to the absolute filename of the
+ * given file. If the value of this attribute is an absolute path, it
+ * is left unchanged (with / and \ characters converted to the
+ * current platforms conventions). Otherwise it is taken as a path
+ * relative to the project's basedir and expanded.
+ * @param location path to set
+ */
public void setLocation(File location) {
setValue(location.getAbsolutePath());
}
+ /**
+ * Sets the value of the property.
+ * @param value value to assign
+ */
+
public void setValue(String value) {
this.value = value;
}
+
public String getValue() {
return value;
}
+ /**
+ * the filename of a property file to load.
+ [EMAIL PROTECTED] file filename
+ */
public void setFile(File file) {
this.file = file;
}
@@ -140,6 +185,10 @@
}
/**
+ * Prefix to apply to properties loaded using <code>file</code>
+ * or <code>resource</code>.
+ * A "." is appended to the prefix if not specified.
+ * @param prefix prefix string
* @since Ant 1.5
*/
public void setPrefix(String prefix) {
@@ -156,6 +205,13 @@
return prefix;
}
+ /**
+ * Sets a reference to an Ant datatype
+ * declared elsewhere.
+ * Only yields reasonable results for references
+ * PATH like structures or properties.
+ * @param ref reference
+ */
public void setRefid(Reference ref) {
this.ref = ref;
}
@@ -164,6 +220,10 @@
return ref;
}
+ /**
+ * the resource name of a property file to load
+ * @param resource resource on classpath
+ */
public void setResource(String resource) {
this.resource = resource;
}
@@ -172,6 +232,25 @@
return resource;
}
+ /**
+ * the prefix to use when retrieving environment variables.
+ * Thus if you specify environment="myenv"
+ * you will be able to access OS-specific
+ * environment variables via property names "myenv.PATH" or
+ * "myenv.TERM".
+ * <p>
+ * Note that if you supply a property name with a final
+ * "." it will not be doubled. ie
environment="myenv." will still
+ * allow access of environment variables through "myenv.PATH"
and
+ * "myenv.TERM". This functionality is currently only
implemented
+ * on select platforms. Feel free to send patches to increase the number
of platforms
+ * this functionality is supported on ;).<br>
+ * Note also that properties are case sensitive, even if the
+ * environment variables on your operating system are not, e.g. it
+ * will be ${env.Path} not ${env.PATH} on Windows 2000.
+ * @param env prefix
+ */
+
public void setEnvironment(String env) {
this.env = env;
}
@@ -183,6 +262,12 @@
return env;
}
+
+ /**
+ * The classpath to use when looking up a resource.
+ * @param classpath to add to any existing classpath
+ */
+
public void setClasspath(Path classpath) {
if (this.classpath == null) {
this.classpath = classpath;
@@ -191,6 +276,9 @@
}
}
+ /**
+ * The classpath to use when looking up a resource.
+ */
public Path createClasspath() {
if (this.classpath == null) {
this.classpath = new Path(project);
@@ -198,6 +286,9 @@
return this.classpath.createPath();
}
+ /**
+ * the classpath to use when lookingup a resource,
+ * given as reference to a <path> defined elsewhere
public void setClasspathRef(Reference r) {
createClasspath().setRefid(r);
}
@@ -212,16 +303,26 @@
/**
* @deprecated This was never a supported feature and has been
* deprecated without replacement
+ * @ant.setter skip="true"
*/
public void setUserProperty(boolean userProperty) {
log("DEPRECATED: Ignoring request to set user property in Property"
+ " task.", Project.MSG_WARN);
}
+ /**
+ * get the value of this property
+ * @return the current value or the empty string
+ */
public String toString() {
return value == null ? "" : value;
}
+ /**
+ * set the property in the project to the value.
+ * if the task was give a file, resource or env attribute
+ * here is where it is loaded
+ */
public void execute() throws BuildException {
if (name != null) {
if (value == null && ref == null) {
@@ -273,6 +374,10 @@
}
}
+ /**
+ * load properties from a file
+ * @param file file to load
+ */
protected void loadFile(File file) throws BuildException {
Properties props = new Properties();
log("Loading " + file.getAbsolutePath(), Project.MSG_VERBOSE);
@@ -296,6 +401,10 @@
}
}
+ /**
+ * load properties from a resource in the current classpath
+ * @param name name of resource to load
+ */
protected void loadResource(String name) {
Properties props = new Properties();
log("Resource Loading " + name, Project.MSG_VERBOSE);
@@ -333,6 +442,10 @@
}
+ /**
+ * load the environment values
+ * @param prefix prefix to place before them
+ */
protected void loadEnvironment(String prefix) {
Properties props = new Properties();
if (!prefix.endsWith(".")) {
@@ -353,6 +466,10 @@
addProperties(props);
}
+ /**
+ * iterate through a set of properties,
+ * resolve them then assign them
+ */
protected void addProperties(Properties props) {
resolveAllProperties(props);
Enumeration e = props.keys();
@@ -370,6 +487,11 @@
}
}
+ /**
+ * add a name value pair to the project property set
+ * @param n name of property
+ * @param v value to set
+ */
protected void addProperty(String n, String v) {
if (userProperty) {
if (project.getUserProperty(n) == null) {
@@ -382,6 +504,10 @@
}
}
+ /**
+ * resolve properties inside a properties hashtable
+ * @param props properties object to resolve
+ */
private void resolveAllProperties(Properties props) throws
BuildException {
for (Enumeration e = props.keys(); e.hasMoreElements();) {
String name = (String) e.nextElement();
1.12.2.1 +13 -4
jakarta-ant/src/main/org/apache/tools/ant/taskdefs/Recorder.java
Index: Recorder.java
===================================================================
RCS file:
/home/cvs/jakarta-ant/src/main/org/apache/tools/ant/taskdefs/Recorder.java,v
retrieving revision 1.12
retrieving revision 1.12.2.1
diff -u -r1.12 -r1.12.2.1
--- Recorder.java 15 Apr 2002 14:56:29 -0000 1.12
+++ Recorder.java 20 Jun 2002 03:45:12 -0000 1.12.2.1
@@ -67,10 +67,19 @@
import java.util.Hashtable;
/**
- * This task is the manager for RecorderEntry's. It is this class that holds
- * all entries, modifies them every time the <recorder> task is called,
- * and addes them to the build listener process.
- *
+ * Add a listener to the current build process that records the
+ * output to a file.
+ * <p>Several recorders can exist at the same time. Each recorder is
+ * associated with a file. The filename is used as a unique identifier for
+ * the recorders. The first call to the recorder task with an unused
filename
+ * will create a recorder (using the parameters provided) and add it to the
+ * listeners of the build. All subsequent calls to the recorder task using
+ * this filename will modify that recorders state (recording or not) or other
+ * properties (like logging level).</p>
+ * <p>Some technical issues: the file's print stream is flushed for
"finished"
+ * events (buildFinished, targetFinished and taskFinished), and is closed on
+ * a buildFinished event.</p>
+
* @author <a href="mailto:[EMAIL PROTECTED]">J D Glanville</a>
* @see RecorderEntry
* @version 0.5
1.36.2.2 +111 -40
jakarta-ant/src/main/org/apache/tools/ant/taskdefs/Rmic.java
Index: Rmic.java
===================================================================
RCS file:
/home/cvs/jakarta-ant/src/main/org/apache/tools/ant/taskdefs/Rmic.java,v
retrieving revision 1.36.2.1
retrieving revision 1.36.2.2
diff -u -r1.36.2.1 -r1.36.2.2
--- Rmic.java 27 May 2002 16:00:27 -0000 1.36.2.1
+++ Rmic.java 20 Jun 2002 03:45:12 -0000 1.36.2.2
@@ -74,27 +74,41 @@
import java.util.Vector;
/**
- * Task to compile RMI stubs and skeletons. This task can take the following
- * arguments:
+ * Runs the rmic compiler against classes.</p>
+ * <p>Rmic can be run on a single class (as specified with the classname
+ * attribute) or a number of classes at once (all classes below base that
+ * are neither _Stub nor _Skel classes). If you want to rmic a single
+ * class and this class is a class nested into another class, you have to
+ * specify the classname in the form <code>Outer$$Inner</code> instead of
+ * <code>Outer.Inner</code>.</p>
+ * <p>It is possible to refine the set of files that are being rmiced. This
can be
+ * done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>,
+ * <i>excludesfile</i> and <i>defaultexcludes</i>
+ * attributes. With the <i>includes</i> or <i>includesfile</i> attribute you
specify the files you want to
+ * have included by using patterns. The <i>exclude</i> or
<i>excludesfile</i> attribute is used to specify
+ * the files you want to have excluded. This is also done with patterns. And
+ * finally with the <i>defaultexcludes</i> attribute, you can specify
whether you
+ * want to use default exclusions or not. See the section on
+ * directory based tasks</a>, on how the
+ * inclusion/exclusion of files works, and how to write patterns.</p>
+ * <p>This task forms an implicit FileSet and
+ * supports all attributes of <code><fileset></code>
+ * (<code>dir</code> becomes <code>base</code>) as well as the nested
+ * <code><include></code>, <code><exclude></code> and
+ * <code><patternset></code> elements.</p>
+ * <p>It is possible to use different compilers. This can be selected
+ * with the "build.rmic" property or the <code>compiler</code>
+ * attribute. <a name="compilervalues">There are three choices</a>:</p>
* <ul>
- * <li>base: The base directory for the compiled stubs and skeletons
- * <li>class: The name of the class to generate the stubs from
- * <li>stubVersion: The version of the stub prototol to use (1.1, 1.2,
compat)
- * <li>sourceBase: The base directory for the generated stubs and skeletons
- * <li>classpath: Additional classpath, appended before the system classpath
- * <li>iiop: Generate IIOP compatable output
- * <li>iiopopts: Include IIOP options
- * <li>idl: Generate IDL output
- * <li>idlopts: Include IDL options
- * <li>includeantruntime
- * <li>includejavaruntime
- * <li>extdirs
+ * <li>sun (the standard compiler of the JDK)</li>
+ * <li>kaffe (the standard compiler of
+ * {@ link <a href="http://www.kaffe.org";>Kaffe</a>})</li>
+ * <li>weblogic</li>
* </ul>
- * Of these arguments, <b>base</b> is required.
- * <p>
- * If classname is specified then only that classname will be compiled. If it
- * is absent, then <b>base</b> is traversed for classes according to
patterns.
- * <p>
+ *
+ * <p> The <a href="http://dione.zcu.cz/~toman40/miniRMI/";>miniRMI</a>
+ * project contains a compiler implementation for this task as well,
+ * please consult miniRMI's documentation to learn how to use it.</p>
*
* @author [EMAIL PROTECTED]
* @author [EMAIL PROTECTED]
@@ -146,37 +160,54 @@
}
}
- /** Sets the base directory to output generated class. */
+ /**
+ * Sets the location to store the compiled files; required
+ */
public void setBase(File base) {
this.baseDir = base;
}
- /** Gets the base directory to output generated class. */
+ /**
+ * Gets the base directory to output generated class.
+ */
+
public File getBase() {
return this.baseDir;
}
- /** Sets the class name to compile. */
+ /**
+ * Sets the the class to run <code>rmic</code> against;
+ * optional
+ */
public void setClassname(String classname) {
this.classname = classname;
}
- /** Gets the class name to compile. */
+ /**
+ * Gets the class name to compile.
+ */
public String getClassname() {
return classname;
}
- /** Sets the source dirs to find the source java files. */
+ /**
+ * optional directory to save generated source files to.
+ */
public void setSourceBase(File sourceBase) {
this.sourceBase = sourceBase;
}
- /** Gets the source dirs to find the source java files. */
+ /**
+ * Gets the source dirs to find the source java files.
+ */
public File getSourceBase() {
return sourceBase;
}
- /** Sets the stub version. */
+ /**
+ * Specify the JDK version for the generated stub code.
+ * Specify "1.1" to pass the "-v1.1" option to
rmic.</td>
+ */
public void setStubVersion(String stubVersion) {
this.stubVersion = stubVersion;
}
@@ -185,6 +216,10 @@
return stubVersion;
}
+ /**
+ * indicates whether token filtering should take place;
+ * optional, default=false
+ */
public void setFiltering(boolean filter) {
filtering = filter;
}
@@ -193,12 +228,17 @@
return filtering;
}
- /** Sets the debug flag. */
+ /**
+ * generate debug info (passes -g to rmic);
+ * optional, defaults to false
+ */
public void setDebug(boolean debug) {
this.debug = debug;
}
- /** Gets the debug flag. */
+ /**
+ * Gets the debug flag.
+ */
public boolean getDebug() {
return debug;
}
@@ -225,7 +265,8 @@
}
/**
- * Adds a reference to a CLASSPATH defined elsewhere.
+ * Adds to the classpath a reference to
+ * a <path> defined elsewhere.
*/
public void setClasspathRef(Reference r) {
createClasspath().setRefid(r);
@@ -239,9 +280,12 @@
}
/**
- * Indicates that the classes found by the directory match should be
+ * Flag to enable verification so that the classes
+ * found by the directory match are
* checked to see if they implement java.rmi.Remote.
- * This defaults to false if not set. */
+ * Optional; his defaults to false if not set.
+ */
+
public void setVerify(boolean verify) {
this.verify = verify;
}
@@ -253,26 +297,30 @@
/**
* Indicates that IIOP compatible stubs should
- * be generated. This defaults to false
+ * be generated; optional, defaults to false
* if not set.
*/
public void setIiop(boolean iiop) {
this.iiop = iiop;
}
- /** Gets iiop flags. */
+ /**
+ * Gets iiop flags.
+ */
public boolean getIiop() {
return iiop;
}
/**
- * pass additional arguments for iiop
+ * Set additional arguments for iiop
*/
public void setIiopopts(String iiopopts) {
this.iiopopts = iiopopts;
}
- /** Gets additional arguments for iiop. */
+ /**
+ * Gets additional arguments for iiop.
+ */
public String getIiopopts() {
return iiopopts;
}
@@ -286,7 +334,9 @@
this.idl = idl;
}
- /* Gets IDL flags. */
+ /**
+ * Gets IDL flags.
+ */
public boolean getIdl() {
return idl;
}
@@ -305,13 +355,17 @@
return idlopts;
}
- /** Gets file list to compile. */
+ /**
+ * Gets file list to compile.
+ */
public Vector getFileList() {
return compileList;
}
/**
* Include ant's own classpath in this task's classpath?
+ * sets whether to include the Ant run-time libraries;
+ * optional defaults to true.
*/
public void setIncludeantruntime(boolean include) {
includeAntRuntime = include;
@@ -326,8 +380,10 @@
}
/**
- * Sets whether or not to include the java runtime libraries to this
* task's classpath.
+ * Enables or disables including the default run-time
+ * libraries from the executing VM; optional,
+ * defaults to false
*/
public void setIncludejavaruntime(boolean include) {
includeJavaRuntime = include;
@@ -343,7 +399,7 @@
/**
* Sets the extension directories that will be used during the
- * compilation.
+ * compilation; optional.
*/
public void setExtdirs(Path extdirs) {
if (this.extdirs == null) {
@@ -376,6 +432,9 @@
}
/**
+ * Sets the compiler implementation to use; optional,
+ * defaults to the value of the <code>build.rmic</code> property,
+ * or failing that, default compiler for the current VM
* @since Ant 1.5
*/
public void setCompiler(String compiler) {
@@ -383,6 +442,7 @@
}
/**
+ * get the name of the current compiler
* @since Ant 1.5
*/
public String getCompiler() {
@@ -411,6 +471,10 @@
return facade.getArgs();
}
+ /**
+ * execute by creating an instance of an implementation
+ * class and getting to do the work
+ */
public void execute() throws BuildException {
if (baseDir == null) {
throw new BuildException("base attribute must be set!",
location);
@@ -487,7 +551,7 @@
/**
* Move the generated source file(s) to the base directory
*
- * @exception org.apache.tools.ant.BuildException When error
+ * @throws org.apache.tools.ant.BuildException When error
* copying/removing files.
*/
private void moveGeneratedFile (File baseDir, File sourceBaseFile,
@@ -629,6 +693,13 @@
public class ImplementationSpecificArgument extends
org.apache.tools.ant.util.facade.ImplementationSpecificArgument {
+ /**
+ * Only pass the specified argument if the
+ * chosen compiler implementation matches the
+ * value of this attribute. Legal values are
+ * the same as those in the above list of
+ * valid compilers.)
+ */
public void setCompiler(String impl) {
super.setImplementation(impl);
}
1.15.2.1 +6 -46
jakarta-ant/src/main/org/apache/tools/ant/taskdefs/SendEmail.java
Index: SendEmail.java
===================================================================
RCS file:
/home/cvs/jakarta-ant/src/main/org/apache/tools/ant/taskdefs/SendEmail.java,v
retrieving revision 1.15
retrieving revision 1.15.2.1
diff -u -r1.15 -r1.15.2.1
--- SendEmail.java 15 Apr 2002 13:36:17 -0000 1.15
+++ SendEmail.java 20 Jun 2002 03:45:12 -0000 1.15.2.1
@@ -57,52 +57,12 @@
import org.apache.tools.ant.taskdefs.email.EmailTask;
/**
- * A task to send SMTP email.
- * <p>
- * <table border="1" cellpadding="3" cellspacing="0">
- * <tr bgcolor="#CCCCFF">
- * <th>Attribute</th>
- * <th>Description</th>
- * <th>Required</th>
- * </tr>
- * <tr>
- * <td>from</td>
- * <td>Email address of sender.</td>
- * <td>Yes</td>
- * </tr>
- * <tr>
- * <td>mailhost</td>
- * <td>Host name of the mail server.</td>
- * <td>No, default to "localhost"</td>
- * </tr>
- * <tr>
- * <td>toList</td>
- * <td>Comma-separated list of recipients.</td>
- * <td>Yes</td>
- * </tr>
- * <tr>
- * <td>subject</td>
- * <td>Email subject line.</td>
- * <td>No</td>
- * </tr>
- * <tr>
- * <td>files</td>
- * <td>Filename(s) of text to send in the body of the email. Multiple files
are
- * comma-separated.</td>
- * <td rowspan="2">One of these two attributes</td>
- * </tr>
- * <tr>
- * <td>message</td>
- * <td>Message to send inthe body of the email.</td>
- * </tr>
- * </table>
- * <tr>
- * <td>includefilenames</td>
- * <td>Includes filenames before file contents when set to true.</td>
- * <td>No, default is <I>false</I></td>
- * </tr>
- * <p>
- *
+ * A task to send SMTP email.
+ * This task can send mail using either plain
+ * text, UU encoding or Mime format mail depending on what is available.
+ * Attachments may be sent using nested FileSet
+ * elements.
+
* @author [EMAIL PROTECTED]
* @author <a href="mailto:[EMAIL PROTECTED]">Magesh Umasankar</a>
*
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
