Java example source code file (Connector.java)

This example Java source code file (Connector.java) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

argument, booleanargument, connector, integerargument, list, selectedargument, serializable, string, stringargument, transport, util

The Connector.java Java example source code

/*
 * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package com.sun.jdi.connect;

import java.util.Map;
import java.util.List;
import java.io.Serializable;

/**
 * A method of connection between a debugger 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.
 *
 * @see LaunchingConnector
 * @see AttachingConnector
 * @see ListeningConnector
 * @see Connector.Argument
 *
 * @author Gordon Hirsch
 * @since  1.3
 */
@jdk.Exported
public interface Connector {
    /**
     * 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, the Sun connector
     * implementations have names prefixed with "com.sun.jdi.".
     * Not intended for exposure to end-user.
     *
     * @return the name of this connector.
     */
    String name();

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

    /**
     * Returns the transport mechanism used by this connector to establish
     * connections with a target VM.
     *
     * @return the {@link Transport} used by this connector.
     */
    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.
     */
    Map<String,Connector.Argument> defaultArguments();

    /**
     * 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}.
     */
    @jdk.Exported
    public interface Argument extends Serializable {
        /**
         * Returns a short, unique identifier for the argument.
         * Not intended for exposure to end-user.
         *
         * @return the name of this argument.
         */
        String name();

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

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

        /**
         * Returns the current value of the argument. Initially, the
         * default value is returned. If the value is currently unspecified,
         * null is returned.
         *
         * @return the current value of the argument.
         */
        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 - for example,
         * on {@link LaunchingConnector#launch}
         */
        void setValue(String value);

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

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

    /**
     * Specification for and value of a Connector argument,
     * whose value is Boolean.  Boolean values are represented
     * by the localized versions of the strings "true" and "false".
     */
    @jdk.Exported
    public interface BooleanArgument extends Argument {
        /**
         * Sets the value of the argument.
         */
        void setValue(boolean value);

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

        /**
         * Return the string representation of the <code>value
         * parameter.
         * Does not set or examine the current value of <code>this
         * instance.
         * @return the localized String representation of the
         * boolean value.
         */
        String stringValueOf(boolean 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 #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.
         */
        boolean booleanValue();
    }

    /**
     * Specification for and value of a Connector argument,
     * whose value is an integer.  Integer values are represented
     * by their corresponding strings.
     */
    @jdk.Exported
    public 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 - for example,
         * on {@link LaunchingConnector#launch}
         */
        void setValue(int value);

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

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

        /**
         * Return the string representation of the <code>value
         * parameter.
         * Does not set or examine the current value of <code>this
         * instance.
         * @return the String representation of the
         * int value.
         */
        String stringValueOf(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 #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.
         */
        int intValue();

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

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

    /**
     * Specification for and value of a Connector argument,
     * whose value is a String.
     */
    @jdk.Exported
    public interface StringArgument extends Argument {
        /**
         * Performs basic sanity check of argument.
         * @return <code>true always
         */
        boolean isValid(String value);
    }

    /**
     * Specification for and value of a Connector argument,
     * whose value is a String selected from a list of choices.
     */
    @jdk.Exported
    public interface SelectedArgument extends Argument {
        /**
         * Return the possible values for the argument
         * @return {@link List} of {@link String}
         */
        List<String> choices();

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