001: /* ====================================================================
002: The Jicarilla Software License
003:
004: Copyright (c) 2003 Leo Simons.
005: All rights reserved.
006:
007: Permission is hereby granted, free of charge, to any person obtaining
008: a copy of this software and associated documentation files (the
009: "Software"), to deal in the Software without restriction, including
010: without limitation the rights to use, copy, modify, merge, publish,
011: distribute, sublicense, and/or sell copies of the Software, and to
012: permit persons to whom the Software is furnished to do so, subject to
013: the following conditions:
014:
015: The above copyright notice and this permission notice shall be
016: included in all copies or substantial portions of the Software.
017:
018: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
019: EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
020: MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
021: IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
022: CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
023: TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
024: SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
025: ==================================================================== */
026: package org.jicarilla.http;
027:
028: import java.nio.ByteBuffer;
029:
030: /**
031: * The handler gets notified whenever the parser finds a new
032: * element of a message. Handlers do *not* need to be
033: * threadsafe.
034: *
035: * @author <a href="lsimons at jicarilla dot org">Leo Simons</a>
036: * @version $Id: HTTPHandler.java,v 1.5 2004/04/03 10:13:23 lsimons Exp $
037: */
038: public interface HTTPHandler {
039: /**
040: * This method will be called by the parser to signal that
041: * it will start providing the data of a new message that
042: * is being received.
043: */
044: void newMessage();
045:
046: /**
047: * This will be the second method called. In the case of
048: * a request, this field will container the request
049: * method. In the case of a response, this will be the
050: * HTTP version.
051: *
052: * @param firstField the value of the first field
053: */
054: void foundStartLineFirstField(ByteBuffer firstField);
055:
056: /**
057: * This will be the third method called. In the case of
058: * a request, this field will contain the request
059: * URI. In the case of a response, this field will contain
060: * the status code.
061: *
062: * @param secondField the value of the second field
063: */
064: void foundStartLineSecondField(ByteBuffer secondField);
065:
066: /**
067: * this will be the fourth method called. In the case of a
068: * request, this field will contain the version. In the case
069: * of a response, this field will contain the reason phrase.
070: *
071: * @param thirdField the value of the third field
072: */
073: void foundStartLineThirdField(ByteBuffer thirdField);
074:
075: /**
076: * This method will be called zero or more times, once
077: * for each header name, after the start line
078: * has been parsed. It will be followed by a call to the
079: * <code>foundHeaderValue()</code> method.
080: *
081: * @param header the name of the header that was found
082: */
083: void foundHeaderName(ByteBuffer header);
084:
085: /**
086: * This method will be called zero or more times, once
087: * for each header value, after the start line
088: * has been parsed. It will always follow immediately after
089: * the <code>foundHeaderName()</code> has been called.
090: *
091: * @param value the value of the header that was found
092: */
093: void foundHeaderValue(ByteBuffer value);
094:
095: /**
096: * This method will be called once by the parser, after
097: * all the headers have been found. If the return value
098: * is {@link HTTPParser.BODY_TYPE_NONE}, it will be
099: * followed by a call to {@link #endMessage()}. If the
100: * return value is {@link HTTPParser.BODY_TYPE_NORMAL}, it
101: * will be followed by a call to {@link #getBodySize()}. If
102: * the return value is {@link HTTPParser.BODY_TYPE_CHUNKING},
103: * it will be followed by one or more calls to
104: * {@link #foundBody(ByteBuffer)}.
105: *
106: * @return an integer representing the body type that the
107: * parser should attempt to retrieve. Valid values are
108: * {@link HTTPParser.BODY_TYPE_NONE},
109: * {@link HTTPParser.BODY_TYPE_NORMAL} and
110: * {@link HTTPParser.BODY_TYPE_CHUNKING}.
111: */
112: int getBodyType();
113:
114: /**
115: * This method will be caleld once by the parser to determine
116: * the size of the expected body, if and only if the call to
117: * {@link #getBodyType()} returned {@link HTTPParser.BODY_TYPE_NORMAL}.
118: *
119: * @return an integer indicating the expected size of the body,
120: * in bytes.
121: */
122: int getBodySize();
123:
124: /**
125: * This method will be called zero or more times, after
126: * the request or response line and the headers have been
127: * parsed. It will always follow after a call to
128: * <code>foundHeaderValue()</code>.
129: *
130: * @param buffer part of the body of the message. Note
131: * that decoding of any Chunked transfer codings will
132: * have been done already.
133: */
134: void foundBody(ByteBuffer buffer);
135:
136: /**
137: * This method will be called by the parser if
138: * {@link #getBodyType()} returns
139: * {@link HTTPParser.BODY_TYPE_CHUNKING} to determine whether
140: * any trailers will be present. It will be followed by a call
141: * to the <code>getTrailerNames()</code> method if and only if
142: * this method returns true. It will be followed by a call to
143: * the <code>endMessage()</code> method if and only if this
144: * method returns false.
145: *
146: * @return true if there are trailers present, false otherwise.
147: */
148: boolean hasTrailers();
149:
150: /**
151: * This method will be called once by the parser directly after
152: * {@link #hasTrailers()} if and only if that method returned
153: * true.
154: *
155: * @return a non-empty array of non-null strings representing
156: * the trailers that will be present.
157: */
158: String[] getTrailerNames();
159:
160: /**
161: * This method will be called one or more times, once
162: * for each trailer name, after the body
163: * has been parsed, if and only if {@link #hasTrailers()} returned
164: * true. It will be followed by a call to the
165: * <code>foundTrailerValue()</code> method. Only trailer
166: * names that have been returned from the parser's call to
167: * {@link #getTrailerNames()} will be provided.
168: *
169: * @param trailer the name of the trailer that was found.
170: */
171: void foundTrailerName(ByteBuffer trailer);
172:
173: /**
174: * This method will be called one or more times, once
175: * for each footer value, after the body has been parsed, if and
176: * only if {@link #hasTrailers()} returned
177: * true. It will always follow immediately after
178: * the <code>foundTrailerName()</code> has been called.
179: *
180: * @param value the value of the trailer that was found.
181: */
182: void foundTrailerValue(ByteBuffer value);
183:
184: /**
185: * This method will be called by the parser to signal that
186: * the current message has ended. It will always be called
187: * exactly once.
188: */
189: void endMessage();
190:
191: }
|