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: /**
030: * Immutable class that allows the client to indicate its listening
031: * preferences to the server (buffering, frequency, etc).
032: * <p>
033: * The client can send a OutputPolicy to the RemoteHost when
034: * it creates the RemoteProcess or can later send a new
035: * OutputPolicy to a running RemoteProcess to alter its
036: * preferences.
037: *
038: * @see OutputListener
039: * @see RemoteProcess
040: */
041: public final class OutputPolicy implements java.io.Serializable {
042:
043: /** @see #getBufferSize() */
044: private final int bufferSize;
045:
046: //
047: // can add more here...
048: //
049:
050: public OutputPolicy() {
051: this (10);
052: }
053:
054: public OutputPolicy(int bufferSize) {
055: this .bufferSize = bufferSize;
056: }
057:
058: /**
059: * NodeEvent buffering size and policy<pre>:
060: *
061: * > 1: The server will buffer process output until at most that many
062: * are ready to be sent in a
063: * <tt>OutputListener.handleAll(..)</tt> --
064: * The server can impose an upper-bound that is less than
065: * Integer.MAX_VALUE at it's discretion (For example, never
066: * buffer more than 1000 NodeEvents) and/or flush a smaller
067: * number of buffered NodeEvents at any time (For example, the
068: * server can send if it's memory is running low)
069: *
070: * 1 or 0: No buffering -- the server will use
071: * <tt>OutputListener.handle(..)</tt> to send each NodeEvent
072: * separately, which is significantly less efficent than "> 1"
073: * but allows for continual updates
074: *
075: * < 0: Similar to the "> 1" case, but the server will discard
076: * buffered NodeEvents in excess of the Math.abs(..) of the
077: * specified amount instead of pushing them on the Client,
078: * which means that the Client must use
079: * <tt>RemoteProcess.flushOutput()</tt> to periodically
080: * request the buffered NodeEvents -- For example, "-100" tells
081: * the server to buffer at most 100 output and then discard
082: * to prevent overflow, where the server might decide to throw
083: * away the oldest 25 NodeEvents in the buffer if the buffer
084: * size grows over 100
085: * <pre>
086: * .
087: * <p>
088: * These definitions are intentionally ambiguous to prevent the Client
089: * from burdening the server. If the Client requires a more strict
090: * definition (time-frequency, etc) then it must poll.
091: * <p>
092: * The Client can use <tt>RemoteProcess.flushOutput()</tt> to
093: * flush all buffered NodeEvents.
094: * <p>
095: * Note that NodeEvent's of type <tt>NodeEvent.HEARTBEAT</tt> are
096: * <u>not</u> buffered -- these simply allow the server to track the
097: * existence of the Client and destroy itself if the Client dies!
098: */
099: public int getBufferSize() {
100: // FIXME make in terms of OutputBundle bytes!
101: return bufferSize;
102: }
103:
104: public String toString() {
105: return "OutputPolicy {" + "\n bufferSize: " + getBufferSize()
106: + "\n}";
107: }
108: }
|