001: /*
002: * <copyright>
003: *
004: * Copyright 2000-2007 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.web.redirect;
028:
029: import java.io.IOException;
030: import java.util.List;
031: import java.util.Map;
032: import javax.servlet.ServletException;
033: import javax.servlet.http.HttpServletRequest;
034: import javax.servlet.http.HttpServletResponse;
035:
036: /**
037: * A redirector / tunneler for servlet requests.
038: */
039: public interface ServletRedirector {
040:
041: /**
042: * The request has been redirected or otherwise committed.
043: * <p>
044: * This is the "success" case, even if it calls "res.sendError(..)".
045: */
046: int REDIRECTED = 0;
047:
048: /**
049: * The specified options are not supported by this redirector.
050: * <p>
051: * This case is common if explicit options are specified. Typically a
052: * null options list is treated as a wildcard and always supported.
053: */
054: int NOT_SUPPORTED = 1;
055:
056: /**
057: * The naming entries for the target do not contain a usable entry for
058: * this redirector.
059: * <p>
060: * For example, an HTTP redirector may find that there's no "http" entry
061: * in the naming service for the remote agent.
062: */
063: int NO_NAMING_ENTRIES = 2;
064:
065: /**
066: * A redirection loop has been detected.
067: * <p>
068: * For example, an HTTP redirect might find its own host:port for a "remote"
069: * agent, yet if that agent was local then we wouldn't have called the
070: * redirector.
071: */
072: int DETECTED_LOOP = 3;
073:
074: /**
075: * Some other, non-fatal error.
076: * <p>
077: * For example, the naming entry may be invalid. This is in contrast to a
078: * committed error case, in which case our redirector should throw an
079: * exception or call "res.sendError(..)" and return {@link #REDIRECTED}.
080: */
081: int OTHER_ERROR = 4;
082:
083: /**
084: * Redirect/Tunnel a servlet request to the specified remote agent.
085: * <p>
086: * A standard solution is to lookup the request's scheme in the map and
087: * HTTP-redirect the browser to that remote host:port. Another option is
088: * to tunnel the request for the client.
089: *
090: * @param encName URL-encoded remote agent name.
091: *
092: * @param options URL-decoded redirect control options, as specified on
093: * the request path. For example, "/$_^foo" is parsed as ["_", "^"].
094: * The meaning of these control options is redirector-specific. Typically
095: * these options are only specified to override the default behavior, e.g.
096: * to turn off HTTP-redirects or use a custom redirect/tunnel capability.
097: *
098: * @param namingSupport support API to lookup the encName entries in the
099: * naming service. See {@link ServletEngineService#getNamingEntries}.
100: *
101: * @param req the http request
102: * @param res the http response
103: *
104: * @return {@link #REDIRECTED} if the call was sucessful or otherwise
105: * committed, otherwise one of the other status codes.
106: */
107: int redirect(String encName, List options,
108: NamingSupport namingSupport, HttpServletRequest req,
109: HttpServletResponse res) throws ServletException,
110: IOException;
111:
112: }
|