001: /*
002: * <copyright>
003: *
004: * Copyright 1997-2004 BBNT Solutions, LLC
005: * under sponsorship of the Defense Advanced Research Projects
006: * Agency (DARPA).
007: *
008: * You can redistribute this software and/or modify it under the
009: * terms of the Cougaar Open Source License as published on the
010: * Cougaar Open Source Website (www.cougaar.org).
011: *
012: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
013: * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
014: * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
015: * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
016: * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
017: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
018: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
019: * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
020: * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
021: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
022: * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
023: *
024: * </copyright>
025: */
026:
027: package org.cougaar.tools.server;
028:
029: import java.net.URL;
030: import java.util.List;
031:
032: /**
033: * Client support to watch remote process activity.
034: * <p>
035: * @see OutputListener
036: */
037: public interface RemoteListenable {
038:
039: /**
040: * List the names of all listeners.
041: * <p>
042: * This is actually a set.
043: */
044: List list() throws Exception;
045:
046: /**
047: * Add a listener URL that will handle (pushed)
048: * OutputBundles from the remote process.
049: * <p>
050: * The "listenerURL" is the client-side URL that will
051: * receive "OutputBundles"s.
052: * <p>
053: * The output sequence is:
054: * <pre>
055: * HTTP header line
056: * (ignorable non-empty header lines)*
057: * empty line
058: * (serialized OutputBundle)*
059: * serialized null
060: * </pre>
061: * e.g., if the client has URL "http://x.com:7000/foo":
062: * <pre>
063: * PUT http://x.com:7000/foo HTTP/1.0
064: *
065: * <i>serialized object(s)</i>
066: * </pre>
067: * <p>
068: * A client can have one (host:port) socket listener
069: * handle multiple RemoteListenables by using a
070: * different URL path for each listener.
071: * <p>
072: * If the connection is lost then a new connection will
073: * be created.
074: */
075: void addListener(URL listenerURL) throws Exception;
076:
077: /**
078: * Remove the URL-listener with the given URL.
079: *
080: * @throws IllegalArgumentException if the listener does not exist
081: */
082: void removeListener(URL listenerURL) throws Exception;
083:
084: /**
085: * Add an OutputListener to listen for (pushed)
086: * OutputBundles from the remote process.
087: * <p>
088: * Note that there is no corresponding<pre>
089: * OutputListener getListener(id);
090: * </pre>.
091: * <p>
092: * If there are multiple simultaneous listeners on the
093: * same process then the specified "id" must be unique.
094: */
095: void addListener(OutputListener ol, String id) throws Exception;
096:
097: /**
098: * Remove the OutputListener with the given "id".
099: *
100: * @throws IllegalArgumentException if the listener does not exist
101: */
102: void removeListener(String id) throws Exception;
103:
104: /**
105: * Get the current OutputPolicy, as set by
106: * <tt>setOutputPolicy(..)</tt>.
107: * <p>
108: * FIXME for now there's only one policy for all the listeners.
109: */
110: OutputPolicy getOutputPolicy() throws Exception;
111:
112: /**
113: * The client can set the OutputPolicy to
114: * configure the output frequency, contents, etc.
115: * <p>
116: * FIXME for now there's only one policy for all the listeners.
117: */
118: void setOutputPolicy(OutputPolicy op) throws Exception;
119:
120: /**
121: * Force the remote process to send any buffered output to the
122: * OutputListener.
123: * <p>
124: * Also see the OutputPolicy, which defines the
125: * non-forced buffering policy.
126: * <p>
127: * FIXME for now the flush will apply to all listeners.
128: * FIXME add flush-token for listener to delineate flush(es)
129: */
130: void flushOutput() throws Exception;
131:
132: }
|