001: /*
002: * Copyright 1998-2004 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package com.sun.jdi.connect;
027:
028: import java.util.Map;
029: import java.io.IOException;
030: import com.sun.jdi.VirtualMachine;
031:
032: /**
033: * A connector which listens for a connection initiated by a target VM.
034: *
035: * @author Gordon Hirsch
036: * @since 1.3
037: */
038: public interface ListeningConnector extends Connector {
039: /**
040: * Indicates whether this listening connector supports multiple
041: * connections for a single argument map. If so, a call to
042: * {@link #startListening} may allow
043: * multiple target VM to become connected.
044: *
045: * @return <code>true</code> if multiple connections are supported;
046: * <code>false</code> otherwise.
047: */
048: boolean supportsMultipleConnections();
049:
050: /**
051: * Listens for one or more connections initiated by target VMs.
052: * The connector uses the given argument map
053: * in determining the address at which to listen or else it generates
054: * an appropriate listen address. In either case, an address string
055: * is returned from this method which can be used in starting target VMs
056: * to identify this connector. The format of the address string
057: * is connector, transport, and, possibly, platform dependent.
058: * <p>
059: * The argument map associates argument name strings to instances
060: * of {@link Connector.Argument}. The default argument map for a
061: * connector can be obtained through {@link Connector#defaultArguments}.
062: * Argument map values can be changed, but map entries should not be
063: * added or deleted.
064: * <p>
065: * This method does not return a {@link VirtualMachine}, and, normally,
066: * returns before any target VM initiates
067: * a connection. The connected target is obtained through
068: * {@link #accept} (using the same argument map as is passed to this
069: * method).
070: * <p>
071: * If <code>arguments</code> contains addressing information. and
072: * only one conection will be accepted, the {@link #accept accept} method
073: * can be called immediately without calling this method.
074: *
075: * @return the address at which the connector is listening
076: * for a connection.
077: * @throws java.io.IOException when unable to start listening.
078: * Specific exceptions are dependent on the Connector implementation
079: * in use.
080: * @throws IllegalConnectorArgumentsException when one of the
081: * connector arguments is invalid.
082: */
083: String startListening(
084: Map<String, ? extends Connector.Argument> arguments)
085: throws IOException, IllegalConnectorArgumentsException;
086:
087: /**
088: * Cancels listening for connections. The given argument map should match
089: * the argument map given for a previous {@link #startListening} invocation.
090: *
091: * @throws java.io.IOException when unable to stop listening.
092: * Specific exceptions are dependent on the Connector implementation
093: * in use.
094: * @throws IllegalConnectorArgumentsException when one of the
095: * connector arguments is invalid.
096: */
097: void stopListening(
098: Map<String, ? extends Connector.Argument> arguments)
099: throws IOException, IllegalConnectorArgumentsException;
100:
101: /**
102: * Waits for a target VM to attach to this connector.
103: *
104: * @throws TransportTimeoutException when the Connector encapsulates
105: * a transport that supports a timeout when accepting, a
106: * {@link Connector.Argument} representing a timeout has been set
107: * in the argument map, and a timeout occurs whilst waiting for
108: * the target VM to connect.
109: * @throws java.io.IOException when unable to accept.
110: * Specific exceptions are dependent on the Connector implementation
111: * in use.
112: * @throws IllegalConnectorArgumentsException when one of the
113: * connector arguments is invalid.
114: */
115: VirtualMachine accept(
116: Map<String, ? extends Connector.Argument> arguments)
117: throws IOException, IllegalConnectorArgumentsException;
118:
119: }
|