implemented issue JPPF-547

common/src/java/org/jppf/node/protocol/ClassPath.java

@@ -21,7 +21,7 @@
 import java.io.Serializable;
 import java.util.Collection;
 
-import org.jppf.location.Location;
+import org.jppf.location.*;
 
 /**
  * A container for class path elements.
@@ -35,24 +35,61 @@ public interface ClassPath extends Serializable, Iterable<ClassPathElement> {
    */
   ClassPath add(ClassPathElement element);
 
+  /**
+   * Add the specified element to this classpath.
+   * When using this method, the local and remote locations are assumed to be the same.
+   * @param location the location of the element to add.
+   * @return this {@code ClassPath}, for method call chaining.
+   */
+  ClassPath add(Location<?> location);
+
+  /**
+   * Add the specified element to this classpath.
+   * Upon processing by the node, the local location will be copied into the remote location.
+   * @param sourceLocation the location of the element to add, in the client environment.
+   * @param targetLocation the location of the element to add, in the node environment.
+   * @return this {@code ClassPath}, for method call chaining.
+   */
+  ClassPath add(Location<?> sourceLocation, Location<?> targetLocation);
+
+  /**
+   * Add the specified element to this classpath.
+   * Upon processing by the node, the local location will be copied into the remote location, unless all of the following are true:
+   * <ul>
+   * <li>copyToExistingFile is {@code false}</li>
+   * <li>targetLocation is a {@link FileLocation}</li>
+   * <li>the file pointed to by targetLocation already exists on the file system</li>
+   * </ul>
+   * @param sourceLocation the location of the element to add, in the client environment.
+   * @param targetLocation the location of the element to add, in the node environment.
+   * @param copyToExistingFile whether to copy the source to the target if the target is either a {@link FileLocation}
+   * or an {@link URLLocation} with a {@code file} URL protocol (e.g. {@code file:/home/user/mylib.jar}), and if it already exists on the file system.
+   * @return this {@code ClassPath}, for method call chaining.
+   */
+  ClassPath add(Location<?> sourceLocation, Location<?> targetLocation, final boolean copyToExistingFile);
+
   /**
    * Add the specified element to this classpath.
    * When using this method, the local and remote locations are assumed to be the same.
    * @param name the the name of the element to add.
    * @param location the location of the element to add.
    * @return this {@code ClassPath}, for method call chaining.
+   * @deprecated the {@code name} attribute has no clearly definied, consistent semantics. It is no longer used.
+   * Use {@link #add(Location) add(location)} instead.
    */
   ClassPath add(String name, Location<?> location);
 
   /**
    * Add the specified element to this classpath.
-   * Upon processing by the node, the local location will be copied into the remote location.
+   * Upon processing by the node, the source location will be copied into the target location.
    * @param name the the name of the element to add.
-   * @param localLocation the location of the element to add, in the client environment.
-   * @param remoteLocation the location of the element to add, in the node environment.
+   * @param sourceLocation the location of the element to add, in the client environment.
+   * @param targetLocation the location of the element to add, in the node environment.
    * @return this {@code ClassPath}, for method call chaining.
+   * @deprecated the {@code name} attribute has no clearly definied, consistent semantics. It is no longer used.
+   * Use {@link #add(Location, Location) add(sourceLocation, remoteLocation)} instead.
    */
-  ClassPath add(String name, Location<?> localLocation, Location<?> remoteLocation);
+  ClassPath add(String name, Location<?> sourceLocation, Location<?> targetLocation);
 
   /**
    * Remove the specified element from this classpath.
@@ -65,6 +102,8 @@ public interface ClassPath extends Serializable, Iterable<ClassPathElement> {
    * Remove the specified element from this classpath.
    * @param name the name of the classpath element to remove.
    * @return this {@code ClassPath}, for method call chaining.
+   * @deprecated the {@code name} attribute has no clearly definied, consistent semantics. It is no longer used.
+   * Use {@link #remove(ClassPathElement)} instead.
    */
   ClassPath remove(String name);
 
@@ -78,6 +117,7 @@ public interface ClassPath extends Serializable, Iterable<ClassPathElement> {
    * Get the element with the specified name.
    * @param name the name of the classpath element to find.
    * @return a {@link ClassPathElement} instance or <code>null</code> if the element could no be found.
+   * @deprecated the {@code name} attribute has no clearly definied, consistent semantics. It is no longer used.
    */
   ClassPathElement element(String name);
 

common/src/java/org/jppf/node/protocol/ClassPathElement.java

@@ -28,24 +28,40 @@
  * They are intended to be transported along with a job SLA.
  * @author Laurent Cohen
  */
-public interface ClassPathElement extends Serializable
-{
+public interface ClassPathElement extends Serializable {
   /**
    * Get the name of this classpath element.
    * @return the name as a string.
+   * @deprecated the {@code name} attribute has no clearly definied, consistent semantics. It can be bypassed entirely.
    */
   String getName();
 
   /**
    * Get the location of this element, pointing to or embedding the underlying jar or zip file in the client environment.
    * @return a {@link Location} object.
    */
+  Location<?> getSourceLocation();
+
+  /**
+   * Get the location of this element, pointing to or embedding the underlying jar or zip file in the client environment.
+   * @return a {@link Location} object.
+   * @deprecated use {@link #getSourceLocation()} instead.
+   * @exclude
+   */
   Location<?> getLocalLocation();
 
   /**
    * Get the location of this element, pointing to or embedding the underlying jar or zip file in the node environment.
    * @return a {@link Location} object.
    */
+  Location<?> getTargetLocation();
+
+  /**
+   * Get the location of this element, pointing to or embedding the underlying jar or zip file in the client environment.
+   * @return a {@link Location} object.
+   * @deprecated use {@link #getTargetLocation()} instead.
+   * @exclude
+   */
   Location<?> getRemoteLocation();
 
   /**
@@ -55,4 +71,11 @@ public interface ClassPathElement extends Serializable
    * @return <code>true</code> if the validation issuccessful, <code>false</code> if it fails.
    */
   boolean validate();
+
+  /**
+   * Determine whether to copy the source to the target if the target is a {@link FileLocation} and if it already exists on the file system.
+   * This is an optimization that can avoid unnecessary netword and/or disk I/O.
+   * @return {@code false} if the target is a {@link FileLocation} and should not be copied into, {@code true} otherwise.
+   */
+  boolean isCopyToExistingFile();
 }

common/src/java/org/jppf/node/protocol/ClassPathElementImpl.java

@@ -32,54 +32,117 @@ public class ClassPathElementImpl implements ClassPathElement {
   /**
    * The location of this classpath element in the client environment.
    */
-  protected final Location<?> localLocation;
+  private final Location<?> sourceLocation;
   /**
    * The location of this classpath element in the node environment.
    */
-  protected final Location<?> remoteLocation;
+  private final Location<?> targetLocation;
   /**
    * The name of this classpath element.
+   * @deprecated the {@code name} attribute has no clearly defined, consistent semantics. It is no longer used.
    */
-  protected final String name;
+  private final String name;
+  /**
+   * Whether to copy the source to the target if the target is a {@link FileLocation} and if it already exists on the file system.
+   */
+  private final boolean copyToExistingFile;
 
   /**
    * Initialize this classpath element with the specified name and local location.
    * The remote location is set to the same location.
    * @param name the name of this classpath element.
    * @param location the location of this classpath element.
+   * @deprecated the {@code name} attribute has no clearly defined, consistent semantics. It is no longer used.
    */
-  protected ClassPathElementImpl(final String name, final Location<?> location) {
-    this.name = name;
-    this.localLocation = location;
-    this.remoteLocation = this.localLocation;
+  ClassPathElementImpl(final String name, final Location<?> location) {
+    this(name, location, location);
   }
 
   /**
    * Initialize this classpath element with the specified name and local location.
    * The remote location is set to the same location.
    * @param name the name of this classpath element.
-   * @param localLocation the location of this classpath element in the client environment.
-   * @param remoteLocation the location of this classpath element in the node environment.
+   * @param sourceLocation the location of this classpath element in the client environment.
+   * @param targetLocation the location of this classpath element in the node environment.
+   * @deprecated the {@code name} attribute has no clearly defined, consistent semantics. It is no longer used.
    */
-  protected ClassPathElementImpl(final String name, final Location<?> localLocation, final Location<?> remoteLocation) {
+  ClassPathElementImpl(final String name, final Location<?> sourceLocation, final Location<?> targetLocation) {
     this.name = name;
-    this.localLocation = localLocation;
-    this.remoteLocation = remoteLocation;
+    this.sourceLocation = sourceLocation;
+    this.targetLocation = targetLocation;
+    this.copyToExistingFile = true;
+  }
+
+  /**
+   * Initialize this classpath element with the specified name and local location.
+   * The remote location is set to the same location.
+   * @param location the location of this classpath element.
+   */
+  ClassPathElementImpl(final Location<?> location) {
+    this(location, location, true);
+  }
+
+  /**
+   * Initialize this classpath element with the specified name and local location.
+   * The remote location is set to the same location.
+   * @param sourceLocation the location of this classpath element in the client environment.
+   * @param targetLocation the location of this classpath element in the node environment.
+   */
+  ClassPathElementImpl(final Location<?> sourceLocation, final Location<?> targetLocation) {
+    this(sourceLocation, targetLocation, true);
+  }
+
+  /**
+   * Initialize this classpath element with the specified name and local location.
+   * The remote location is set to the same location.
+   * @param sourceLocation the location of this classpath element in the client environment.
+   * @param targetLocation the location of this classpath element in the node environment.
+   * @param copyToExistingFileLocation whether to copy the source to the target if the target is a {@link FileLocation} and if it already exists on the file system.
+   */
+  ClassPathElementImpl(final Location<?> sourceLocation, final Location<?> targetLocation, final boolean copyToExistingFileLocation) {
+    this.name = null;
+    this.sourceLocation = sourceLocation;
+    this.targetLocation = targetLocation;
+    this.copyToExistingFile = copyToExistingFileLocation;
   }
 
+  /**
+   * {@inheritDoc}
+   * @deprecated the {@code name} attribute has no clearly defined, consistent semantics. It is no longer used.
+   */
   @Override
   public String getName() {
     return name;
   }
 
+  @Override
+  public Location<?> getSourceLocation() {
+    return sourceLocation;
+  }
+
+  /**
+   * {@inheritDoc}
+   * @deprecated use {@link #getSourceLocation()} instead.
+   * @exclude
+   */
   @Override
   public Location<?> getLocalLocation() {
-    return localLocation;
+    return sourceLocation;
   }
 
+  @Override
+  public Location<?> getTargetLocation() {
+    return targetLocation;
+  }
+
+  /**
+   * {@inheritDoc}
+   * @deprecated use {@link #getTargetLocation()} instead.
+   * @exclude
+   */
   @Override
   public Location<?> getRemoteLocation() {
-    return remoteLocation;
+    return targetLocation;
   }
 
   /**
@@ -93,6 +156,14 @@ public boolean validate() {
 
   @Override
   public String toString() {
-    return name;
+    return new StringBuilder(getClass().getSimpleName()).append('[')
+      .append("source=").append(sourceLocation)
+      .append(", target=").append(targetLocation)
+      .append(']').toString();
+  }
+
+  @Override
+  public boolean isCopyToExistingFile() {
+    return copyToExistingFile;
   }
 }