001: /*
002: * <copyright>
003: *
004: * Copyright 2003-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.lib.aggagent.query;
028:
029: import java.io.Serializable;
030:
031: import org.cougaar.lib.aggagent.session.XmlTransferable;
032: import org.cougaar.lib.aggagent.util.InverseSax;
033:
034: /**
035: * The Alert class is the abstract superclass of all result set monitors.
036: * Each implementation is responsible for maintaining its own status regarding
037: * the corresponding result set. At first, this will be a simple boolean
038: * status: either the alert is tripped or not. However, more complicated
039: * recording apparati may be supported (or even required) in the future.
040: * <br><br>
041: * When new information becomes available, the handleUpdate method should be
042: * called. Specific implementations will examine the result set and take the
043: * appropriate action, which may include updating the Alert's status and/or
044: * producing events.
045: * <br><br>
046: * At present there is no additional support for Alert activities, so all
047: * necessary work must be done in the Alert implementations.
048: */
049: public abstract class Alert implements XmlTransferable, Serializable {
050: public static String ALERT_TAG = "alert";
051: private static String NAME_ATT = "name";
052: private static String QUERY_ATT = "query_id";
053: private static String ALERTED_ATT = "alerted";
054:
055: private boolean alerted = false;
056: private QueryResultAdapter query = null;
057: private String name = null;
058:
059: public void setName(String n) {
060: name = n;
061: }
062:
063: public String getName() {
064: return name;
065: }
066:
067: /**
068: * Specify the query (etc.) which the Alert is responsible for monitoring.
069: * In future implementations, this coupling may be handled differently. In
070: * particular, different subclasses of AggregationResultSet may be supported
071: * with class-specific handlers. For now, only one type is available, and
072: * hence only one type is expected.
073: */
074: public void setQueryAdapter(QueryResultAdapter s) {
075: query = s;
076: }
077:
078: /**
079: * Provide access to the QueryResultAdapter monitored by this Alert.
080: */
081: public QueryResultAdapter getQueryAdapter() {
082: return query;
083: }
084:
085: /**
086: * Provide access to the query ID associated with this alert. The default
087: * implementation is to obtain this from the resident query, but subclasses
088: * may have different behavior.
089: */
090: public String getQueryId() {
091: return query.getID();
092: }
093:
094: /**
095: * Set the alerted status of this Alert. This method is declared
096: * <it>public</it> rather than <it>protected</it> so that scripts can
097: * access it. In general, however, it should not be called by other
098: * agencies.
099: */
100: public void setAlerted(boolean f) {
101: alerted = f;
102: }
103:
104: /**
105: * Report the status of this Alert. Either the alert has been tripped
106: * (return true) or it hasn't (return false).
107: */
108: public boolean isAlerted() {
109: return alerted;
110: }
111:
112: /**
113: * <p>
114: * Notify the Alert that the relevant result set has been updated. This
115: * method returns true if the state of the Alert was changed during the
116: * operation and false otherwise. The bulk of the responsibility is
117: * delegated to the abstract handleUpdate() method. Concrete Alert classes
118: * should provide the appropriate implementation for that method.
119: * </p><p>
120: * The update() method is intentionally not declared <it>final</it> so that
121: * subclasses can use a different strategy for reporting changes, possibly
122: * relating to class-specific state.
123: * </p>
124: */
125: public boolean update() {
126: boolean oldAlerted = isAlerted();
127: handleUpdate();
128: return oldAlerted != isAlerted();
129: }
130:
131: /**
132: * Convert this Alert to an XML format for transfer to clients.
133: */
134: public String toXml() {
135: InverseSax doc = new InverseSax();
136: includeXml(doc);
137: return doc.toString();
138: }
139:
140: public void includeXml(InverseSax doc) {
141: doc.addElement(ALERT_TAG);
142: doc.addAttribute(NAME_ATT, getName());
143: doc.addAttribute(QUERY_ATT, getQueryId());
144: doc.addAttribute(ALERTED_ATT, String.valueOf(isAlerted()));
145: includeXmlBody(doc);
146: doc.endElement();
147: }
148:
149: protected void includeXmlBody(InverseSax doc) {
150: }
151:
152: /**
153: * Handle incoming data and adjust the local state. This method is declared
154: * public so that scripts can access it. Otherwise, it is usually invoked
155: * through the update() method.
156: */
157: public abstract void handleUpdate();
158: }
|