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.lib.contract;
028:
029: import org.cougaar.util.UnaryPredicate;
030:
031: import org.w3c.dom.Document;
032: import org.w3c.dom.Element;
033:
034: /**
035: * An extended <code>UnaryPredicate</code> with improved <tt>toString<tt>,
036: * XML generation, and new "implies" capability.
037: * <p>
038: * <code>Operator</code>s feature improved:
039: * <ul>
040: * <li><tt>toString</tt> in "paren" or "xml" formats</li>
041: * <li>added XML generation (<tt>getXML</tt>)</li>
042: * <li>(most important) comparison capabilities based upon the
043: * behavior of the <code>Operator</code>
044: * (<tt>implies</tt>, <tt>allows</tt>, <tt>equals</tt>)</li>
045: * </ul>
046: * <p>
047: * The comparison methods will be used for automated analysis, such as
048: * the ability to generate <code>Plugin</code> "contracts" of
049: * publish/subscribe behavior.
050: * <p>
051: * <b>Note:</b> The default implementation of <code>Operator</code>
052: * is currently kept in the utility module as "org.cougaar.lib.contract.lang" --
053: * see the "index.html" file there for language details.
054: * <p>
055: * @see OperatorFactory
056: */
057: public interface Operator extends UnaryPredicate {
058: /**
059: * Constants for <code>Operator</code> <tt>parse</tt> and
060: * <tt>toString</tt> style.
061: */
062: int PAREN_FLAG = (1 << 0);
063: int XML_FLAG = (1 << 1);
064: int PRETTY_FLAG = (1 << 2);
065: int VERBOSE_FLAG = (1 << 3);
066:
067: /**
068: * Default style for <tt>toString</tt> -- currently pretty-printed XML.
069: */
070: int DEFAULT_STYLE = (XML_FLAG | PRETTY_FLAG);
071:
072: /**
073: * <tt>execute</tt> method from <code>UnaryPredicate</code>.
074: */
075: boolean execute(final Object o);
076:
077: /**
078: * <tt>operate</tt> method acts like <tt>execute</tt>, but returns
079: * an <code>Object</code> -- <code>UnaryPredicate</code> users should
080: * use <tt>execute</tt> instead!
081: */
082: Object operate(final Object o);
083:
084: /**
085: * Sets a constant value in the <code>Operator</code>, which is accessed
086: * internally via <tt>(get "key")</tt>.
087: * <p><pre>
088: * For example, a paren-style predicate might be
089: * <tt>(and (isString) (equals (get "mystr")))</tt>
090: * and parsed into <code>Operator</code> op. One can then set
091: * the value of variable "mystr" to be the <code>String</code>
092: * "foo" via
093: * <tt>op.setConst("mystr", "foo")</tt>
094: * and the predicate will behave as
095: * <tt>(and (isString) (equals (get "foo")))</tt>
096: * <p>
097: * One can also specify the expected type of the constant to be
098: * other than <code>String</code> within the predicate via
099: * <tt>(and (isInteger) (equals (get "myint" "Integer")))</tt>
100: * and then set it via
101: * <tt>op.setConst("mystr", new Integer(123))</tt>
102: * <p>
103: * The goal is to allow predicates to be used as simple parameterized
104: * templates.
105: * <p>
106: * @param key the "get" constant identifier
107: * @param val the new value of the constant
108: */
109: void setConst(final String key, final Object val);
110:
111: /**
112: * <pre>
113: * "(this.implies(oper))" is defined as:
114: * for all Objects <i>o1..on</i>,
115: * if <tt>(this.execute(<i>oi</i>) == true)</tt>
116: * then <tt>(oper.execute(<i>oi</i>) == true)</tt>.
117: * </pre>
118: * <p>
119: * Note that there might never be an Object where <tt>this.execute(o)</tt>
120: * is <tt>true</tt>, and <tt>oper</tt> might match other Objects.
121: * <p>
122: * One can use "implies" to see if the given <tt>oper</tt> <u>will</u>
123: * "fire" if <tt>this</tt> Operator fires.
124: *
125: * @see #allows
126: * @see #equals
127: */
128: boolean implies(final Operator oper);
129:
130: /**
131: * Equivalent to <tt>oper.implies(this)</tt>.
132: */
133: boolean impliedBy(final Operator oper);
134:
135: /**
136: * <pre>
137: * "(this.allows(oper))" is defined as:
138: * there exists an Object <i>o</i> such that
139: * <tt>((this.execute(<i>o</i>) == true) &&
140: * (oper.execute(<i>o</i>) == true))</tt>.
141: * </pre>
142: * <p>
143: * Note that this Object might never arise in practice, but
144: * the two <code>Operator</code>s are at least logically compatable.
145: * <p>
146: * One often uses <tt>publishOp.allows(subscribeOp)</tt>, since we
147: * are looking to see if any Object <u>might</u> pass both the publishOp
148: * and the subscribeOp. Although it's logically equivalent
149: * to test <tt>subscribeOp.allows(publishOp)</tt>, the prior form
150: * is likely faster and better supported.
151: *
152: * @see #implies
153: * @see #equals
154: */
155: boolean allows(final Operator oper);
156:
157: /**
158: * <pre>
159: * "(this.equals(oper))" is defined as:
160: * for all Objects <i>o1..on</i>,
161: * <tt>(this.execute(<i>oi</i>) == oper.execute(<i>oi</i>))</tt>.
162: * </pre>
163: * <p>
164: * Note that real "program" equivalency is NP-complete (Halting problem),
165: * so this is at best an approximation! The same caveat goes for
166: * <tt>implies</tt> and <tt>allows</tt>.
167: *
168: * @see #implies
169: * @see #allows
170: */
171: boolean equals(final Operator oper);
172:
173: /**
174: * Convert <code>this</code> to a <code>String</code>.
175: *
176: * @param style use a bit-mix of <tt>*_FLAG</tt> constants, such as
177: * (XML_FLAG | VERBOSE_FLAG) or
178: * (PAREN_FLAG | PRETTY_FLAG), etc
179: */
180: String toString(final int style);
181:
182: /**
183: * Get an XML <code>Element</code> representation in the given <tt>style</tt>.
184: * <p>
185: * @param style currently only VERBOSE_FLAG is used
186: */
187: Element getXML(Document doc, final int style);
188:
189: /**
190: * Get an XML <code>Element</code> representation in the
191: * <tt>DEFAULT_STYLE</tt>.
192: */
193: Element getXML(Document doc);
194: }
|