001/*
002 * JPPF.
003 * Copyright (C) 2005-2018 JPPF Team.
004 * http://www.jppf.org
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 *   http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019package org.jppf.node.protocol;
020
021import java.io.Serializable;
022import java.util.Collection;
023
024import org.jppf.location.*;
025
026/**
027 * A container for class path elements.
028 * @author Laurent Cohen
029 */
030public interface ClassPath extends Serializable, Iterable<ClassPathElement> {
031  /**
032   * Add the specified element to this classpath.
033   * @param element the classpath element to add.
034   * @return this <code>ClassPath</code>.
035   */
036  ClassPath add(ClassPathElement element);
037
038  /**
039   * Add the specified element to this classpath.
040   * When using this method, the local and remote locations are assumed to be the same.
041   * @param location the location of the element to add.
042   * @return this {@code ClassPath}, for method call chaining.
043   */
044  ClassPath add(Location<?> location);
045
046  /**
047   * Add the specified element to this classpath.
048   * Upon processing by the node, the local location will be copied into the remote location.
049   * @param sourceLocation the location of the element to add, in the client environment.
050   * @param targetLocation the location of the element to add, in the node environment.
051   * @return this {@code ClassPath}, for method call chaining.
052   */
053  ClassPath add(Location<?> sourceLocation, Location<?> targetLocation);
054
055  /**
056   * Add the specified element to this classpath.
057   * Upon processing by the node, the local location will be copied into the remote location, unless all of the following are true:
058   * <ul>
059   * <li>copyToExistingFile is {@code false}</li>
060   * <li>targetLocation is a {@link FileLocation}</li>
061   * <li>the file pointed to by targetLocation already exists on the file system</li>
062   * </ul>
063   * @param sourceLocation the location of the element to add, in the client environment.
064   * @param targetLocation the location of the element to add, in the node environment.
065   * @param copyToExistingFile whether to copy the source to the target if the target is either a {@link FileLocation}
066   * 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.
067   * @return this {@code ClassPath}, for method call chaining.
068   */
069  ClassPath add(Location<?> sourceLocation, Location<?> targetLocation, final boolean copyToExistingFile);
070
071  /**
072   * Add the specified element to this classpath.
073   * When using this method, the local and remote locations are assumed to be the same.
074   * @param name the the name of the element to add.
075   * @param location the location of the element to add.
076   * @return this {@code ClassPath}, for method call chaining.
077   * @deprecated the {@code name} attribute has no clearly definied, consistent semantics. It is no longer used.
078   * Use {@link #add(Location) add(location)} instead.
079   */
080  ClassPath add(String name, Location<?> location);
081
082  /**
083   * Add the specified element to this classpath.
084   * Upon processing by the node, the source location will be copied into the target location.
085   * @param name the the name of the element to add.
086   * @param sourceLocation the location of the element to add, in the client environment.
087   * @param targetLocation the location of the element to add, in the node environment.
088   * @return this {@code ClassPath}, for method call chaining.
089   * @deprecated the {@code name} attribute has no clearly definied, consistent semantics. It is no longer used.
090   * Use {@link #add(Location, Location) add(sourceLocation, remoteLocation)} instead.
091   */
092  ClassPath add(String name, Location<?> sourceLocation, Location<?> targetLocation);
093
094  /**
095   * Remove the specified element from this classpath.
096   * @param element the classpath element to remove.
097   * @return this {@code ClassPath}, for method call chaining.
098   */
099  ClassPath remove(ClassPathElement element);
100
101  /**
102   * Remove the specified element from this classpath.
103   * @param name the name of the classpath element to remove.
104   * @return this {@code ClassPath}, for method call chaining.
105   * @deprecated the {@code name} attribute has no clearly definied, consistent semantics. It is no longer used.
106   * Use {@link #remove(ClassPathElement)} instead.
107   */
108  ClassPath remove(String name);
109
110  /**
111   * Empty this classpath (remove all classpath elements).
112   * @return this {@code ClassPath}, for method call chaining.
113   */
114  ClassPath clear();
115
116  /**
117   * Get the element with the specified name.
118   * @param name the name of the classpath element to find.
119   * @return a {@link ClassPathElement} instance or <code>null</code> if the element could no be found.
120   * @deprecated the {@code name} attribute has no clearly definied, consistent semantics. It is no longer used.
121   */
122  ClassPathElement element(String name);
123
124  /**
125   * Get a collection of all the classpath elements in this classpath.
126   * @return a {@link Collection} of {@link ClassPathElement}s.
127   */
128  Collection<ClassPathElement> allElements();
129
130  /**
131   * Determine whether this classpath is empty.
132   * @return <code>true</code> if this classpath has no element, <code>false</code> otherwise.
133   */
134  boolean isEmpty();
135
136  /**
137   * Determine whether the node should force a reset of the class loader before executing the tasks.
138   * <p>This only applies when this classpath is empty. If it is not empty, then the reset will occur regardless the value of this flag.
139   * @return <code>true</code> if the class loader reset should be forced, <code>false</code> otherwise.
140   */
141  boolean isForceClassLoaderReset();
142
143  /**
144   * Specify whether the node should force a reset of the class loader before executing the tasks.
145   * <p>This only applies when this classpath is empty. If it is not empty, then the reset will occur regardless the value of the specified flag.
146   * @param forceReset <code>true</code> if the class loader reset should be forced, <code>false</code> otherwise.
147   * @return this {@code ClassPath}, for method call chaining.
148   */
149  ClassPath setForceClassLoaderReset(boolean forceReset);
150}