[Javaprofiler-commits] CVS: jpi/net/sourceforge/javaprofiler/jpi/connect VMStartException.java,NONE,1.1 Transport.java,NONE,1.1 IllegalConnectorArgumentsException.java,NONE,1.1 Connector.java,NONE,1.1 ConnectingException.java,NONE,1.1

[Jan S. <st...@us...>]

Update of /cvsroot/javaprofiler/jpi/net/sourceforge/javaprofiler/jpi/connect
In directory usw-pr-cvs1:/tmp/cvs-serv6321

Added Files:
	VMStartException.java Transport.java 
	IllegalConnectorArgumentsException.java Connector.java 
	ConnectingException.java 
Log Message:
Connectors.

--- NEW FILE: VMStartException.java ---
/*
 *                         Sun Public License Notice
 *
 * The contents of this file are subject to the Sun Public License Version 
 * 1.0 (the "License"). You may not use this file except in compliance with 
 * the License. A copy of the License is available at http://www.sun.com/
 *
 * The Original Code is the Java Profiler module.
 * The Initial Developers of the Original Code are Jan Stola, Pavel Vacha,
 * Michal Pise, Petr Luner, Lukas Petru and Marek Przeczek.
 * Portions created by Jan Stola are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Pavel Vacha are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Michal Pise are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Petr Luner are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Lukas Petru are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Marek Przeczek are Copyright (C) 2000-2001. All Rights Reserved.
 *
 * Contributors: Jan Stola, Pavel Vacha, Michal Pise, Petr Luner,
 *               Lukas Petru and Marek Przeczek.
 */
package net.sourceforge.javaprofiler.jpi.connect;

/**
 * A target VM was successfully launched, but terminated with an error before
 * a connection could be established. This exception provides the <code>Process</code>
 * object for the launched target to help in diagnosing the problem.
 *
 * @author Jan Stola
 */
public class VMStartException extends Exception {
    private Process process;

    /**
     * Creates new VMStartException.
     *
     * @param process <code>Process</code> object of the launched target.
     */
    public VMStartException(Process process) {
        this.process=process;
    }

    /**
     * Creates new VMStartException.
     *
     * @param msg message of the exception.
     * @param process <code>Process</code> object of the launched target.
     */
    public VMStartException(String msg, Process process) {
        super(msg);
        this.process=process;
    }

}

/*
 * $Log: VMStartException.java,v $
 * Revision 1.1  2002/07/02 20:19:27  stolis
 * Connectors.
 *
 */
--- NEW FILE: Transport.java ---
/*
 *                         Sun Public License Notice
 *
 * The contents of this file are subject to the Sun Public License Version 
 * 1.0 (the "License"). You may not use this file except in compliance with 
 * the License. A copy of the License is available at http://www.sun.com/
 *
 * The Original Code is the Java Profiler module.
 * The Initial Developers of the Original Code are Jan Stola, Pavel Vacha,
 * Michal Pise, Petr Luner, Lukas Petru and Marek Przeczek.
 * Portions created by Jan Stola are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Pavel Vacha are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Michal Pise are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Petr Luner are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Lukas Petru are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Marek Przeczek are Copyright (C) 2000-2001. All Rights Reserved.
 *
 * Contributors: Jan Stola, Pavel Vacha, Michal Pise, Petr Luner,
 *               Lukas Petru and Marek Przeczek.
 */
package net.sourceforge.javaprofiler.jpi.connect;

/**
 * A method of communication between a profiler and a target VM.
 *
 * @author Jan Stola
 */
public interface Transport {

    /**
     * Returns a short identifier for the transport. Transport implementors
     * should follow similar naming conventions as are used with packages
     * to avoid name collisions. For example, our transport implementations
     * have names prefixed with "net.sourceforge.javaprofiler.jpi.".
     *
     * @return the name of this transport.
     */
    public String name();
    
    /**
     * Returns short human-readable description of this transport.
     *
     * @return short human-readable description of this transport.
     */
    public String label();

}

/*
 * $Log: Transport.java,v $
 * Revision 1.1  2002/07/02 20:19:27  stolis
 * Connectors.
 *
 */
--- NEW FILE: IllegalConnectorArgumentsException.java ---
/*
 *                         Sun Public License Notice
 *
 * The contents of this file are subject to the Sun Public License Version 
 * 1.0 (the "License"). You may not use this file except in compliance with 
 * the License. A copy of the License is available at http://www.sun.com/
 *
 * The Original Code is the Java Profiler module.
 * The Initial Developers of the Original Code are Jan Stola, Pavel Vacha,
 * Michal Pise, Petr Luner, Lukas Petru and Marek Przeczek.
 * Portions created by Jan Stola are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Pavel Vacha are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Michal Pise are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Petr Luner are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Lukas Petru are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Marek Przeczek are Copyright (C) 2000-2001. All Rights Reserved.
 *
 * Contributors: Jan Stola, Pavel Vacha, Michal Pise, Petr Luner,
 *               Lukas Petru and Marek Przeczek.
 */
package net.sourceforge.javaprofiler.jpi.connect;

import java.util.List;
import java.util.ArrayList;

/**
 * Thrown to indicate an invalid argument or inconsistent passed
 * to a {@link Connector}.
 *
 * @author  Jan Stola
 */
public class IllegalConnectorArgumentsException extends IllegalArgumentException {
    /** Names of invalid arguments. */
    private List names;

    /**
     * Creates new IllegalConnectorArgumentsException.
     *
     * @param msg message of the exception.
     * @param name name of invalid argument.
     */
    public IllegalConnectorArgumentsException(String msg, String name) {
        super(msg);
        names=new ArrayList(1);
        names.add(name);
    }

    /**
     * Creates new IllegalConnectorArgumentsException.
     *
     * @param msg message of the exception.
     * @param names names of invalid arguments.
     */
    public IllegalConnectorArgumentsException(String msg, List names) {
        super(msg);
        this.names=names;
    }

    /**
     * Returns list of invalid arguments.
     *
     * @return list of invalid arguments.
     */
    public List argumentNames() {
        return names;
    }

}

/*
 * $Log: IllegalConnectorArgumentsException.java,v $
 * Revision 1.1  2002/07/02 20:19:27  stolis
 * Connectors.
 *
 */

--- NEW FILE: Connector.java ---
/*
 *                         Sun Public License Notice
 *
 * The contents of this file are subject to the Sun Public License Version 
 * 1.0 (the "License"). You may not use this file except in compliance with 
 * the License. A copy of the License is available at http://www.sun.com/
 *
 * The Original Code is the Java Profiler module.
 * The Initial Developers of the Original Code are Jan Stola, Pavel Vacha,
 * Michal Pise, Petr Luner, Lukas Petru and Marek Przeczek.
 * Portions created by Jan Stola are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Pavel Vacha are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Michal Pise are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Petr Luner are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Lukas Petru are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Marek Przeczek are Copyright (C) 2000-2001. All Rights Reserved.
 *
 * Contributors: Jan Stola, Pavel Vacha, Michal Pise, Petr Luner,
 *               Lukas Petru and Marek Przeczek.
 */
package net.sourceforge.javaprofiler.jpi.connect;

import java.util.Map;
import java.util.List;
import net.sourceforge.javaprofiler.jpi.VirtualMachineRef;

/**
 * A method of connection between a profiler and a target VM. A connector
 * encapsulates exactly one {@link Transport} used to establish the connection.
 * Each connector has a set of arguments which controls its operation.
 * The arguments are stored as a map, keyed by a string. Each implementation
 * defines the string argument keys it accepts.
 *
 * @author  Jan Stola
 * @author  Michal Pise
 */
public interface Connector {
    /**
     * Mask for attaching connectors. Attaching connectors can be used to attach
     * to an existing target VM and create a {@link VirtualMachine} mirror for it.
     */
    public static final int ATTACHING_CONNECTOR = 1;
    /**
     * Mask for listening connectors. Listening connectors can be used to listen
     * for a connection initiated by a target VM and create
     * a {@link VirtualMachine} mirror for it.
     */    
    public static final int LISTENING_CONNECTOR = 2;
    /**
     * Mask for launching connectors. Launching connectors can be used to launch
     * a new target VM and immediately create a {@link VirtualMachine} mirror for it.
     */    
    public static final int LAUNCHING_CONNECTOR = 4;

    /**
     * Returns a short identifier for the connector. Connector implementors
     * should follow similar naming conventions as are used with packages
     * to avoid name collisions. For example, our connector implementations
     * have names prefixed with "net.sourceforge.javaprofiler.jpi.". Not intended
     * for exposure to the end-user.
     *
     * @return the name of this connector.
     */
    public String name();

    /**
     * Returns a human-readable description of this connector and its purpose.
     *
     * @return the description of this connector
     */
    public String description();

    /**
     * Returns a type of this connector. Three currently supported types are
     * attaching, listening and launching connectors.
     *
     * @return the type of this connector
     */
    public int type();

    /**
     * Returns the transport mechanism used by this connector to establish
     * connections with a target VM.
     *
     * @return the {@link Transport} used by this connector.
     */
    public Transport transport();

    /**
     * Returns the arguments accepted by this Connector and their default values.
     * The keys of the returned map are string argument names. The values are
     * {@link Connector.Argument} containing information about the argument
     * and its default value.
     *
     * @return the map associating argument names with argument information
     * and default value.
     */
    public Map defaultArguments();

    /**
     * Connects to a VM. Exact meaning of word "connecting" depends on the type
     * of this connector - a listening connector for example quietly listens
     * when <code>connect()</code> is called.
     */
    public VirtualMachineRef connect(Map arguments)
    throws IllegalConnectorArgumentsException, ConnectingException;

    /**
     * Specification for and value of a Connector argument. Will always implement
     * a subinterface of Argument: {@link Connector.StringArgument},
     * {@link Connector.BooleanArgument}, {@link Connector.IntegerArgument},
     * or {@link Connector.SelectedArgument}.
     */
    public static interface Argument extends java.io.Serializable {

        /**
         * Returns a short, unique identifier for the argument. Not intended for
         * exposure to end-user.
         *
         * @return the name of this argument.
         */
        public String name();

        /**
         * Returns a short human-readable label for this argument.
         *
         * @return a label for this argument
         */
        public String label();

        /**
         * Returns a human-readable description of this argument and its purpose.
         *
         * @return the description of this argument
         */
        public String description();

        /**
         * Returns the current value of the argument. Initially, the default value
         * is returned. If the value is currently unspecified, <code>null</code> is returned.
         *
         * @return the current value of the argument.
         */
        public String value();

        /**
         * Sets the value of the argument. The value should be checked with
         * {@link #isValid(String)} before setting it; invalid values will throw
         * an exception when the connection is established ({@link #connect}
         * method is called).
         */
        public void setValue(String value);

        /**
         * Performs basic sanity check of argument.
         *
         * @return <code>true</code> if the value is valid to be used in {@link #setValue(String)}
         */
        public boolean isValid(String value);

        /**
         * Indicates whether the argument must be specified. If <code>true</code>,
         * {@link #setValue(String)} must be used to set a non-<code>null</code> value
         * before using this argument in establishing a connection.
         *
         * @return <code>true</code> if the argument must be specified; <code>false</code> otherwise.
         */
        public boolean isMandatory();
    }

    /**
     * Specification for and value of a Connector argument, whose value is
     * Boolean.
     */
    public static interface BooleanArgument extends Argument {

        /**
         * Sets the value of the argument.
         */
        public void setValue(boolean value);

        /**
         * Performs basic sanity check of argument.
         *
         * @return <code>true</code> if value is a string representation of a boolean value.
         */
        public boolean isValid(String value);

        /**
         * Return the value of the argument as a boolean. Since the argument
         * may not have been set or may have an invalid value {@link #isValid(String)}
         * should be called on {@link Connector.Argument#value()} to check its validity.
         * If it is invalid the boolean returned by this method is undefined.
         *
         * @return the value of the argument as a boolean.
         */
        public boolean booleanValue();
    }

    /**
     * Specification for and value of a Connector argument, whose value is
     * an integer. Integer values are represented by their corresponding strings.
     */
    public static interface IntegerArgument extends Argument {

        /**
         * Sets the value of the argument. The value should be checked with
         * {@link #isValid(int)} before setting it; invalid values will throw
         * an exception when the connection is established ({@link #connect}
         * method is called).
         */
        public void setValue(int value);

        /**
         * Performs basic sanity check of argument.
         *
         * @return <code>true</code> if value represents an int that is
         * <code>min() <= value <= max()</code>
         */
        public boolean isValid(String value);

        /**
         * Performs basic sanity check of argument.
         *
         * @return <code>true</code> if <code>min() <= value <= max()</code>
         */
        public boolean isValid(int value);

        /**
         * Return the value of the argument as a int. Since the argument may
         * not have been set or may have an invalid value {@link #isValid(String)}
         * should be called on {@link Connector.Argument#value()} to check its
         * validity. If it is invalid the int returned by this method is undefined.
         *
         * @return the value of the argument as a int.
         */
        public int intValue();

        /**
         * The upper bound for the value.
         *
         * @return the maximum allowed value for this argument.
         */
        public int max();

        /**
         * The lower bound for the value.
         *
         * @return the minimum allowed value for this argument.
         */
        public int min();
    }

    /**
     * Specification for and value of a Connector argument, whose value is
     * a String selected from a list of choices.
     */
    public static interface SelectedArgument extends Argument {

        /**
         * Return the possible values for the argument.
         *
         * @return List of String
         */
        public List choices();

        /**
         * Performs basic sanity check of argument.
         *
         * @return <code>true</code> if value is one of {@link #choices()}.
         */
        public boolean isValid(String value);

    }

    /**
     * Specification for and value of a Connector argument, whose value
     * is a String.
     */
    public static interface StringArgument extends Argument {

    }

}

/*
 * $Log: Connector.java,v $
 * Revision 1.1  2002/07/02 20:19:27  stolis
 * Connectors.
 *
 */

--- NEW FILE: ConnectingException.java ---
/*
 *                         Sun Public License Notice
 *
 * The contents of this file are subject to the Sun Public License Version 
 * 1.0 (the "License"). You may not use this file except in compliance with 
 * the License. A copy of the License is available at http://www.sun.com/
 *
 * The Original Code is the Java Profiler module.
 * The Initial Developers of the Original Code are Jan Stola, Pavel Vacha,
 * Michal Pise, Petr Luner, Lukas Petru and Marek Przeczek.
 * Portions created by Jan Stola are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Pavel Vacha are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Michal Pise are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Petr Luner are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Lukas Petru are Copyright (C) 2000-2001. All Rights Reserved.
 * Portions created by Marek Przeczek are Copyright (C) 2000-2001. All Rights Reserved.
 *
 * Contributors: Jan Stola, Pavel Vacha, Michal Pise, Petr Luner,
 *               Lukas Petru and Marek Przeczek.
 */
package net.sourceforge.javaprofiler.jpi.connect;

/**
 * Thrown to indicate an exception during connecting to a VM.
 *
 * @author Michal Pise, Jan Stola
 */
public class ConnectingException extends Exception {
    
    /**
     * Creates new <code>ConnectingException</code>.
     *
     * @param msg message describing encountered problem.
     */
    public ConnectingException(String msg) {
        super(msg);
    }
    
}

/*
 * $Log: ConnectingException.java,v $
 * Revision 1.1  2002/07/02 20:19:27  stolis
 * Connectors.
 *
 */