- adding documentation and copyright headers

- supporting auto-discovery. Since this is the first release of this feature, I removed the LIST field.

git-svn-id: https://hudson.dev.java.net/svn/hudson/trunk/hudson/main@15705 71c3de6d-444a-0410-be80-ed276b4c234a

core/src/main/java/hudson/model/Environment.java

+/*
+ * The MIT License
+ *
+ * Copyright (c) 2004-2009, Sun Microsystems, Inc., Tom Huybrechts
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
 package hudson.model;
 
-import hudson.Launcher;
-import hudson.Util;
-import hudson.model.AbstractBuild;
-import hudson.model.Build;
-import hudson.model.BuildListener;
-import hudson.slaves.NodeProperty;
+import hudson.tasks.Builder;
 
 import java.io.IOException;
 import java.util.Map;
 
 /**
- * Represents the environment set up by
- * {@link NodeProperty#setUp(Build,Launcher,BuildListener)}.
- * 
+ * Represents some resources that are set up for the duration of a build
+ * to be torn down when the build is over.
+ *
+ * <p>
+ * This is often used to run a parallel server necessary during a build,
+ * such as an application server, a database reserved for the build,
+ * X server for performing UI tests, etc.
+ *
  * <p>
- * It is expected that the subclasses of {@link NodeProperty} extends this class
- * and implements its own semantics.
+ * By having a plugin that does this, instead of asking each build script to do this,
+ * we can simplify the build script. {@link Environment} abstraction also gives
+ * you guaranteed "tear down" phase, so that such resource won't keep running forever.
+ *
+ * @since 1.286
  */
 public abstract class Environment {
 	/**

core/src/main/java/hudson/model/EnvironmentSpecific.java

+/*
+ * The MIT License
+ *
+ * Copyright (c) 2004-2009, Sun Microsystems, Inc., Tom Huybrechts
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
 package hudson.model;
 
 import java.util.Map;
@@ -7,13 +30,12 @@ import java.util.Map;
  * 
  * Mainly for documentation purposes.
  *
+ * @since 1.286
  * @param <T>
  */
 public interface EnvironmentSpecific<T> {
-
 	/**
 	 * Returns a specialized copy of T for functioning in the given environment.
 	 */
 	T forEnvironment(Map<String,String> environment);
-	
 }

core/src/main/java/hudson/model/Hudson.java

@@ -2057,7 +2057,7 @@ public final class Hudson extends Node implements ItemGroup<TopLevelItem>, Stapl
 
             clouds.rebuildHetero(req,json, Cloud.all(), "cloud");
 
-            nodeProperties.rebuild(req, json.getJSONObject("nodeProperties"), getNodePropertyDescriptors());
+            nodeProperties.rebuild(req, json.getJSONObject("nodeProperties"), NodeProperty.for_(this));
 
             save();
             if(result)

core/src/main/java/hudson/model/Node.java

@@ -32,7 +32,6 @@ import hudson.remoting.VirtualChannel;
 import hudson.security.ACL;
 import hudson.security.AccessControlled;
 import hudson.security.Permission;
-import hudson.slaves.EnvironmentVariablesNodeProperty;
 import hudson.slaves.NodeDescriptor;
 import hudson.slaves.NodeProperty;
 import hudson.slaves.NodePropertyDescriptor;
@@ -41,9 +40,7 @@ import hudson.util.DescribableList;
 import hudson.util.EnumConverter;
 
 import java.io.IOException;
-import java.util.ArrayList;
 import java.util.Collection;
-import java.util.List;
 import java.util.Set;
 
 import org.kohsuke.stapler.Stapler;
@@ -59,10 +56,6 @@ import org.kohsuke.stapler.Stapler;
  * @see NodeDescriptor
  */
 public abstract class Node extends AbstractModelObject implements Describable<Node>, ExtensionPoint, AccessControlled {
-
-	public static final List<NodePropertyDescriptor> PROPERTIES = Descriptor
-		.toList((NodePropertyDescriptor) EnvironmentVariablesNodeProperty.DESCRIPTOR);
-	
     public String getDisplayName() {
         return getNodeName(); // default implementation
     }
@@ -197,17 +190,7 @@ public abstract class Node extends AbstractModelObject implements Describable<No
     public abstract DescribableList<NodeProperty<?>, NodePropertyDescriptor> getNodeProperties();
     
     public abstract void setNodeProperties(Collection<NodeProperty<?>> nodeProperties) throws IOException;
-    
-    public List<NodePropertyDescriptor> getNodePropertyDescriptors() {
-		List<NodePropertyDescriptor> result = new ArrayList<NodePropertyDescriptor>();
-		for (NodePropertyDescriptor npd : PROPERTIES) {
-			if (npd.isApplicable(getClass())) {
-				result.add(npd);
-			}
-		}
-		return result;
-    }
-    
+
     public <N extends NodeProperty<?>> N getNodeProperty(Class<N> clazz) {
     	for (NodeProperty<?> p: getNodeProperties()) {
     		if (clazz.isInstance(p)) {

core/src/main/java/hudson/slaves/EnvironmentVariablesNodeProperty.java

 package hudson.slaves;
 
 import hudson.Launcher;
+import hudson.Extension;
 import hudson.model.*;
 
 import java.io.IOException;
@@ -38,12 +39,7 @@ public class EnvironmentVariablesNodeProperty extends NodeProperty<Node> {
     	return Environment.create(envVars);
 	}
 
-    public NodePropertyDescriptor getDescriptor() {
-		return DESCRIPTOR;
-	}
-	
-	public static final DescriptorImpl DESCRIPTOR = new DescriptorImpl();
-	
+    @Extension
 	public static class DescriptorImpl extends NodePropertyDescriptor {
 
 		@Override

core/src/main/java/hudson/slaves/NodeProperties.java

-package hudson.slaves;
-
-import hudson.model.Descriptor;
-import hudson.model.Node;
-
-import java.util.ArrayList;
-import java.util.List;
-
-public class NodeProperties {
-	public static final List<NodePropertyDescriptor> PROPERTIES = Descriptor
-			.toList((NodePropertyDescriptor) EnvironmentVariablesNodeProperty.DESCRIPTOR);
-
-	/**
-	 * List up all {@link NodePropertyDescriptor}s that are applicable for the
-	 * given project.
-	 */
-	public static List<NodePropertyDescriptor> getFor(Node node) {
-		List<NodePropertyDescriptor> result = new ArrayList<NodePropertyDescriptor>();
-		for (NodePropertyDescriptor npd : PROPERTIES) {
-			if (npd.isApplicable(node.getClass())) {
-				result.add(npd);
-			}
-		}
-		return result;
-	}
-	
-}

core/src/main/java/hudson/slaves/NodeProperty.java

+/*
+ * The MIT License
+ *
+ * Copyright (c) 2004-2009, Sun Microsystems, Inc., Tom Huybrechts
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
 package hudson.slaves;
 
 import hudson.ExtensionPoint;
 import hudson.Launcher;
+import hudson.DescriptorExtensionList;
 import hudson.model.AbstractBuild;
 import hudson.model.BuildListener;
 import hudson.model.Describable;
@@ -12,15 +36,40 @@ import hudson.tasks.Builder;
 
 import java.io.IOException;
 import java.util.List;
+import java.util.ArrayList;
 
+/**
+ * Extensible property of {@link Node}.
+ *
+ * <p>
+ * Plugins can contribute this extension point to add additional data or UI actions to {@link Node}.
+ * {@link NodeProperty}s show up in the configuration screen of a node, and they are persisted with the {@link Node} object.
+ *
+ *
+ * <h2>Views</h2>
+ * <dl>
+ * <dt>config.jelly</dt>
+ * <dd>Added to the configuration page of the node.
+ * <dt>global.jelly</dt>
+ * <dd>Added to the system configuration page.
+ * <dl>
+ *
+ * @param <N>
+ *      {@link NodeProperty} can choose to only work with a certain subtype of {@link Node}, and this 'N'
+ *      represents that type. Also see {@link NodePropertyDescriptor#isApplicable(Class)}.
+ *
+ * @since 1.286
+ */
 public abstract class NodeProperty<N extends Node> implements Describable<NodeProperty<?>>, ExtensionPoint {
 
-	public abstract NodePropertyDescriptor getDescriptor();
-	
     protected transient N node;
 	
 	protected void setNode(N node) { this.node = node; }
 	
+    public NodePropertyDescriptor getDescriptor() {
+        return (NodePropertyDescriptor)Hudson.getInstance().getDescriptor(getClass());
+    }
+
     /**
      * Runs before the {@link Builder} runs, and performs a set up. Can contribute additional properties
      * to the environment.
@@ -63,5 +112,25 @@ public abstract class NodeProperty<N extends Node> implements Describable<NodePr
 			}
 		}
     }
-    
+
+    /**
+     * Lists up all the registered {@link NodeDescriptor}s in the system.
+     */
+    public static DescriptorExtensionList<NodeProperty<?>,NodePropertyDescriptor> all() {
+        return (DescriptorExtensionList)Hudson.getInstance().getDescriptorList(NodeProperty.class);
+    }
+
+    /**
+     * List up all {@link NodePropertyDescriptor}s that are applicable for the
+     * given project.
+     */
+    public static List<NodePropertyDescriptor> for_(Node node) {
+        List<NodePropertyDescriptor> result = new ArrayList<NodePropertyDescriptor>();
+        for (NodePropertyDescriptor npd : all()) {
+            if (npd.isApplicable(node.getClass())) {
+                result.add(npd);
+            }
+        }
+        return result;
+    }
 }

core/src/main/java/hudson/slaves/NodePropertyDescriptor.java

+/*
+ * The MIT License
+ *
+ * Copyright (c) 2004-2009, Sun Microsystems, Inc., Tom Huybrechts
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
 package hudson.slaves;
 
 import hudson.model.Descriptor;
 import hudson.model.Node;
+import hudson.Extension;
 
 import java.lang.reflect.ParameterizedType;
 import java.lang.reflect.Type;
 
 import org.jvnet.tiger_types.Types;
 
+/**
+ * Descriptor for {@link NodeProperty}.
+ *
+ * <p>
+ * Put {@link Extension} on your descriptor implementation to have it auto-registered.
+ *
+ * @since 1.286
+ * @see NodeProperty
+ */
 public abstract class NodePropertyDescriptor extends Descriptor<NodeProperty<?>> {
-
-	protected NodePropertyDescriptor() {}
-	
     /**
      * Returns true if this {@link NodeProperty} type is applicable to the
      * given job type.