001: /*
002: * <copyright>
003: *
004: * Copyright 2000-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.core.servlet;
028:
029: import java.util.Collection;
030:
031: import org.cougaar.core.mts.MessageAddress;
032: import org.cougaar.core.service.LoggingService;
033: import org.cougaar.util.UnaryPredicate;
034:
035: /**
036: * This is a simple API for a <code>Servlet</code> to access
037: * COUGAAR Services, such as the Blackboard.
038: * <p>
039: * This is for Servlets that are loaded by the
040: * <code>SimpleServletComponent</code>. See SimplerServletComponent
041: * for loading details (".ini" usage, etc).
042: * <p>
043: * The Servlet class (e.g. "MyServlet") must have either a
044: * "support" constructor:<pre>
045: * ...
046: * public MyServlet(SimpleServletSupport support) {
047: * // save support for later use
048: * }
049: * ...</pre><br>
050: * or the default constructor:<pre>
051: * ...
052: * public MyServlet() {
053: * // load with no support
054: * }
055: * ...</pre><br>
056: * The default constructor can be used to load pure Servlets (i.e.
057: * Servlets without Cougaar references).
058: * <p>
059: *
060: * @see SimpleServletComponent
061: */
062: public interface SimpleServletSupport {
063:
064: /**
065: * Get the path that this Servlet was loaded under.
066: * <p>
067: * This can also be obtained from the
068: * <tt>HttpServletRequest.getRequestURI()</tt>, which
069: * will be "/$encoded-agent-name/path".
070: */
071: String getPath();
072:
073: /**
074: * Query the blackboard for all Objects that match the
075: * given predicate.
076: * <p>
077: * Each call to "query" is a snapshot of the blackboard
078: * that may contain different information than the last
079: * "query" call, even within the same Servlet
080: * "service(..)" request. The Objects returned should
081: * be considered read-only!
082: * <p>
083: * This is the only blackboard access that is provided
084: * to <i>simple</i> Servlets. Servlets that need
085: * to publish/subscribe/etc will require more complex
086: * transaction open/close logic -- they should
087: * obtain the <code>ServletService</code> directly.
088: * See <code>SimpleServletComponent</code> as a guide.
089: */
090: Collection queryBlackboard(UnaryPredicate pred);
091:
092: /**
093: * Get the URL- and HTML-safe (encoded) name of the
094: * Agent that contains this Servlet instance.
095: * <p>
096: * Equivalent to
097: * <tt>encodeAgentName(getAgentIdentifier().getAddress())</tt>.
098: * <p>
099: * All "/$name/*" URLS must use the encoded Agent name.
100: * In general the raw "agentName" may contain characters
101: * that are not URL/HTML safe, such as:
102: * <ul>
103: * <li>URL reserved characters (" ", ":", "/", etc)</li>
104: * <li>HTML reserved characters (">", "<")</li>
105: * <li>Arbitrary control characters ("\\n", "\\t", etc)</li>
106: * </ul>
107: *
108: * @see #encodeAgentName
109: */
110: String getEncodedAgentName();
111:
112: /**
113: * Get the Agent's identifier for the Agent that contains
114: * this Servlet instance.
115: * <p>
116: * The <tt>getAgentIdentifier().getAddress()</tt> is the
117: * "raw" name of the agent and may contain unsafe URL/HTML
118: * characters.
119: *
120: * @see #getEncodedAgentName
121: */
122: MessageAddress getAgentIdentifier();
123:
124: /**
125: * Obtain access to the logging service.
126: * <p>
127: * This is guaranteed to be non-null.
128: */
129: LoggingService getLog();
130:
131: /**
132: * Utility method to encode an Agent name --
133: * equivalent to <tt>java.net.URLEncoder.encode(name)</tt>.
134: *
135: * @see #getEncodedAgentName
136: */
137: String encodeAgentName(String name);
138:
139: //
140: // add other COUGAAR-specific methods here.
141: //
142: // note that we want this to remain a *simple* API.
143: //
144: }
|