Source Code Cross Referenced for SipListener.java in  » 6.0-JDK-Modules » j2me » gov » nist » siplite » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Java Source Code / Java Documentation
1. 6.0 JDK Core
2. 6.0 JDK Modules
3. 6.0 JDK Modules com.sun
4. 6.0 JDK Modules com.sun.java
5. 6.0 JDK Modules sun
6. 6.0 JDK Platform
7. Ajax
8. Apache Harmony Java SE
9. Aspect oriented
10. Authentication Authorization
11. Blogger System
12. Build
13. Byte Code
14. Cache
15. Chart
16. Chat
17. Code Analyzer
18. Collaboration
19. Content Management System
20. Database Client
21. Database DBMS
22. Database JDBC Connection Pool
23. Database ORM
24. Development
25. EJB Server geronimo
26. EJB Server GlassFish
27. EJB Server JBoss 4.2.1
28. EJB Server resin 3.1.5
29. ERP CRM Financial
30. ESB
31. Forum
32. GIS
33. Graphic Library
34. Groupware
35. HTML Parser
36. IDE
37. IDE Eclipse
38. IDE Netbeans
39. Installer
40. Internationalization Localization
41. Inversion of Control
42. Issue Tracking
43. J2EE
44. JBoss
45. JMS
46. JMX
47. Library
48. Mail Clients
49. Net
50. Parser
51. PDF
52. Portal
53. Profiler
54. Project Management
55. Report
56. RSS RDF
57. Rule Engine
58. Science
59. Scripting
60. Search Engine
61. Security
62. Sevlet Container
63. Source Control
64. Swing Library
65. Template Engine
66. Test Coverage
67. Testing
68. UML
69. Web Crawler
70. Web Framework
71. Web Mail
72. Web Server
73. Web Services
74. Web Services apache cxf 2.0.1
75. Web Services AXIS2
76. Wiki Engine
77. Workflow Engines
78. XML
79. XML UI
Java
Java Tutorial
Java Open Source
Jar File Download
Java Articles
Java Products
Java by API
Photoshop Tutorials
Maya Tutorials
Flash Tutorials
3ds-Max Tutorials
Illustrator Tutorials
GIMP Tutorials
C# / C Sharp
C# / CSharp Tutorial
C# / CSharp Open Source
ASP.Net
ASP.NET Tutorial
JavaScript DHTML
JavaScript Tutorial
JavaScript Reference
HTML / CSS
HTML CSS Reference
C / ANSI-C
C Tutorial
C++
C++ Tutorial
Ruby
PHP
Python
Python Tutorial
Python Open Source
SQL Server / T-SQL
SQL Server / T-SQL Tutorial
Oracle PL / SQL
Oracle PL/SQL Tutorial
PostgreSQL
SQL / MySQL
MySQL Tutorial
VB.Net
VB.Net Tutorial
Flash / Flex / ActionScript
VBA / Excel / Access / Word
XML
XML Tutorial
Microsoft Office PowerPoint 2007 Tutorial
Microsoft Office Excel 2007 Tutorial
Microsoft Office Word 2007 Tutorial
Java Source Code / Java Documentation » 6.0 JDK Modules » j2me » gov.nist.siplite 
Source Cross Referenced  Class Diagram Java Document (Java Doc) 


001:        /*
002:         * Portions Copyright  2000-2007 Sun Microsystems, Inc. All Rights
003:         * Reserved.  Use is subject to license terms.
004:         * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
005:         * 
006:         * This program is free software; you can redistribute it and/or
007:         * modify it under the terms of the GNU General Public License version
008:         * 2 only, as published by the Free Software Foundation.
009:         * 
010:         * This program is distributed in the hope that it will be useful, but
011:         * WITHOUT ANY WARRANTY; without even the implied warranty of
012:         * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
013:         * General Public License version 2 for more details (a copy is
014:         * included at /legal/license.txt).
015:         * 
016:         * You should have received a copy of the GNU General Public License
017:         * version 2 along with this work; if not, write to the Free Software
018:         * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
019:         * 02110-1301 USA
020:         * 
021:         * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
022:         * Clara, CA 95054 or visit www.sun.com if you need additional
023:         * information or have any questions.
024:         */
025:        package gov.nist.siplite;
026:
027:        import gov.nist.siplite.stack.Transaction;
028:        import gov.nist.siplite.stack.ClientTransaction;
029:        import gov.nist.siplite.stack.ServerTransaction;
030:
031:        /**
032:         * This interface represents the application view to a SIP stack
033:         * therefore defines the application's communication channel to the SIP stack.
034:         * This is patterened on the JAIN-SIP SIP-Listener ( but it is not identical
035:         * to it).
036:         *
037:         * @see SipProvider
038:         * @see RequestEvent
039:         * @see ResponseEvent
040:         * @see TimeoutEvent
041:         *
042:         * @version 1.1
043:         */
044:        public interface SipListener {
045:
046:            /**
047:             * Processes a Request received on a SipProvider upon which this SipListener
048:             * is registered.
049:             * <p>
050:             * <b>Handling Requests:</b><br>
051:             * When the application receives a RequestEvent from the SipProvider the
052:             * RequestEvent may or may not belong to an existing dialog of the
053:             * application.
054:             * The application can be determine if the RequestEvent belongs to an
055:             * existing dialog by checking the server transaction of the RequestEvent.
056:             * <ul>
057:             * <li>If the server transaction equals <code>null</code> the
058:             * RequestEvent does
059:             * not belong to an existing dialog and the application must determine how
060:             * to handle the RequestEvent. If the application decides to forward the
061:             * Request statelessly no transactional support is required and it
062:             * can simply
063:             * pass the Request of the RequestEvent as an argument to the
064:             * {@link SipProvider#sendRequest(Request)} method. However if the
065:             * application determines to respond to a Request statefully it must request
066:             * a new server transaction from the
067:             * {@link SipProvider#getNewServerTransaction(Request)} method and use this
068:             * server transaction to send the Response based on the content of
069:             * the Request.
070:             * If the SipProvider throws TransactionAlreadyExistsException when the
071:             * application requests a new server transaction to handle a Request the
072:             * current RequestEvent is a retransmission of the initial request
073:             * from which
074:             * the application hadn't requested a server transaction to handle it, i.e.
075:             * this exception handles the race condition of an application
076:             * informing the
077:             * SipProvider that it will handle a Request and the receipt of a
078:             * retransmission of the Request from the network to the SipProvider.
079:             * <li>If the server transaction <b>does NOT</b> equal
080:             *  <code>null</code> the
081:             * application determines its action to the RequestEvent based on
082:             * the content of the Request information.
083:             * </ul>
084:             * <p>
085:             * <b>User Agent Server (UAS) Behaviour:</b><br>
086:             * A UAS application decides whether to accept the an invitation from a
087:             * UAC. The UAS application can accept the invitation by sending a 2xx
088:             * response to the UAC, a 2xx response to an INVITE transaction establishes
089:             * a session. For 2xx responses, the processing is done by the UAS
090:             * application, to guarantee the three way handshake of an INVITE
091:             * transaction. This specification defines a utility thats enables the
092:             * SipProvider to handle the 2XX processing for an INVITE transaction, see
093:             * the {@link SipStack#isRetransmissionFilterActive()} method. If the
094:             * invitation is not accepted, a 3xx, 4xx, 5xx or 6xx response is sent by
095:             * the application, depending on the reason for
096:             * the rejection. Alternatively before sending a final response, the UAS
097:             * can also send provisional responses (1xx) to advise the UAC of progress
098:             * in contacting the called user. A UAS that receives a CANCEL request for
099:             * an INVITE, but has not yet sent a final response, would "stop ringing"
100:             * and then respond to the INVITE with a specific 487 Error response.
101:             * <p>
102:             * <b>General Proxy behaviour:</b><br>
103:             * In some circumstances, a proxy application MAY forward requests using
104:             * stateful transports without being transaction stateful,
105:             * i.e. using the {@link SipProvider#sendRequest(Request)} method,
106:             * but using TCP as a transport.  For example, a proxy application MAY
107:             * forward a request from one TCP connection to another transaction
108:             * statelessly as long as it places enough information in the message to be
109:             * able to forward the response down the same connection the request arrived
110:             * on. This is the responsibility of the application and not the
111:             * SipProvider.
112:             * Requests forwarded between different types of transports where the
113:             * proxy application takes an active role in ensuring reliable delivery on
114:             * one of the transports must be forwarded using the stateful send methods
115:             * on the SipProvider.
116:             * <p>
117:             * <b>Stateful Proxies:</b><br>
118:             * A stateful proxy MUST create a new server transaction for each new
119:             * request received, either automatically generated by the SipProvider,
120:             * if the request matches an existing dialog or by the an
121:             * application call on the SipProvider if it decides to respond to the
122:             * request statefully. The proxy application determines where to
123:             * route the request, choosing one or more next-hop locations. An outgoing
124:             * request for each next-hop location is processed by its own associated
125:             * client transaction.  The proxy application collects the responses from
126:             * the client transactions and uses them to send responses to the server
127:             * transaction. When an application receives a CANCEL request that matches
128:             * a server transaction, a stateful proxy cancels any pending client
129:             * transactions associated with a response context. A stateful proxy
130:             * responds to the CANCEL rather than simply forwarding a response it would
131:             * receive from a downstream element.
132:             * <p>
133:             * For all new Requests, including any with unknown methods, an element
134:             * intending to stateful proxy the Request determines the target(s) of the
135:             * request. A stateful proxy MAY process the targets in any order.
136:             * A stateful proxy must have a mechanism to maintain the target set as
137:             * responses are received and associate the responses to each forwarded
138:             * request with the original request. For each target, the proxy forwards
139:             * the request following these steps:
140:             * <ul>
141:             * <li>Make a copy of the received request.
142:             * <li>Update the Request-URI.
143:             * <li>Update the Max-Forwards header.
144:             * <li>Optionally add a Record-route header.
145:             * <li>Optionally add additional headers.
146:             * <li>Postprocess routing information.
147:             * <li>Determine the next-hop address, port, and transport.
148:             * <li>Add a Via header.
149:             * <li>Add a Content-Length header if necessary.
150:             * <li>Forward the new request using the
151:             * {@link ClientTransaction#sendRequest()} method.
152:             * <li>Process all responses recieved on the
153:             * {@link SipListener#processResponse(ResponseEvent)} method.
154:             * <li>NOT generate 100 (Trying) responses to non-INVITE requests.
155:             * </ul>
156:             * <p>
157:             * A stateful proxy MAY transition to stateless operation at any time
158:             * during the processing of a request, as long as it did nothing that
159:             * would prevent it from being stateless initially i.e. forking or
160:             * generation of a 100 response. When performing such a transition, any
161:             * state already stored is simply discarded.
162:             * <p>
163:             * <b>Forking Requests:</b><br>
164:             * A stateful proxy application MAY choose to "fork" a request, routing it
165:             * to multiple destinations. Any request that is forwarded to more than
166:             * one location MUST be forwarded using the stateful send methods on the
167:             * SipProvider.
168:             * <p>
169:             * <b>Stateless Proxies:</b><br>
170:             * As a stateless proxy does not have any notion of a transaction, or of
171:             * the response context used to describe stateful proxy behavior,
172:             * <code>requestEvent.getServerTransaction() == null;</code>
173:             * always return <var>true</var>. The transaction layer of the SipProvider
174:             * implementation is by-passed.  For all requests including any with
175:             * unknown methods, an application intending to stateless proxy the request
176:             * MUST:
177:             * <ul>
178:             * <li>Validate the request.
179:             * <li>Preprocess routing information.
180:             * <li>Determine a single target(s) for the request.
181:             * <li>Forward the request to the target using the
182:             * {@link SipProvider#sendRequest(Request)} method.
183:             * <li>NOT perform special processing for CANCEL requests.
184:             * </ul>
185:             *
186:             * @since v1.1
187:             * @param requestEvent - requestEvent fired from the SipProvider to
188:             * the SipListener representing a Request received from the network.
189:             */
190:            public void processRequest(RequestEvent requestEvent);
191:
192:            /**
193:             * Processes a Response received on a SipProvider upon which this
194:             * SipListener is registered.
195:             * <p>
196:             * <b>Handling Responses:</b><br>
197:             * When the application receives a ResponseEvent from the SipProvider the
198:             * ResponseEvent may or may not correlate to an existing Request of the
199:             * application. The application can be determine if the
200:             * ResponseEvent belongs
201:             * to an existing Request by checking the client transaction of the
202:             * ResponseEvent.
203:             * <ul>
204:             * <li>If the the client transaction equals <code>null</code> the
205:             * ResponseEvent does not belong to an existing Request and the Response is
206:             * considered stray, i.e. stray response can be identitied, if
207:             * <code>responseEvent.getClientTransaction() == null;</code>. Handling of
208:             * these "stray" responses is dependent on the application i.e. a
209:             * proxy will forward them statelessly using the
210:             * {@link SipProvider#sendResponse(Response)} method, while a User
211:             * Agent will discard them.
212:             * <li>If the client transaction <b>does NOT</b> equal
213:             * <code>null</code> the
214:             * application determines it action to the ResponseEvent based on the
215:             * content of the Response information.
216:             * </ul>
217:             * <p>
218:             * <b>User Agent Client (UAC) behaviour:</b><br>
219:             * After possibly receiving one or more provisional responses (1xx) to a
220:             * Request, the UAC will get one or more 2xx responses or one non-2xx final
221:             * response. Because of the protracted amount of time it can take
222:             * to receive
223:             * final responses to an INVITE, the reliability mechanisms for INVITE
224:             * transactions differ from those of other requests.
225:             * A UAC needs to send an ACK for every final Response it receives, however
226:             * the procedure for sending the ACK depends on the type of Response. For
227:             * final responses between 300 and 699, the ACK processing is done by the
228:             * transaction layer i.e. handled by the implementation. For 2xx
229:             * responses, the
230:             * ACK processing is done by the UAC application, to guarantee the
231:             * three way
232:             * handshake of an INVITE transaction. This specification defines a utility
233:             * thats enables the SipProvider to handle the ACK processing for an INVITE
234:             * transaction, see the {@link
235:             * SipStack#isRetransmissionFilterActive()} method.
236:             * <br>
237:             * A 2xx response to an INVITE establishes a session, and it also
238:             * creates a dialog between the UAC that issued the INVITE and the UAS
239:             * that generated the 2xx response. Therefore, when multiple 2xx responses
240:             * are received from different remote User Agents, i.e. the INVITE forked,
241:             * each 2xx establishes a different dialog and all these dialogs
242:             * are part of
243:             * the same call. If an INVITE client transaction returns a {@link
244:             * TimeoutEvent}
245:             * rather than a response the UAC acts as if a 408 (Request Timeout)
246:             * response had been received from the UAS.
247:             * <p>
248:             * <b>Stateful Proxies:</b><br>
249:             * A proxy application that handles a response statefully must do the
250:             * following processing:
251:             * <ul>
252:             * <li>Find the appropriate response context.
253:             * <li>Remove the topmost Via header.
254:             * <li>Add the response to the response context.
255:             * <li>Check to determine if this response should be forwarded immediately.
256:             * <li>When necessary, choose the best final response from the
257:             * response context. If no final response has been forwarded after every
258:             * client transaction associated with the response context has been
259:             * terminated, the proxy must choose and forward the "best" response
260:             * from those it has seen so far.
261:             * </ul>
262:             * <p>
263:             * Additionally the following processing MUST be performed on each response
264:             * that is forwarded.
265:             * <ul>
266:             * <li>Aggregate authorization header values if necessary.
267:             * <li>Optionally rewrite Record-Route header values.
268:             * <li>Forward the response using the
269:             * {@link ServerTransaction#sendResponse(Response)} method.
270:             * <li>Generate any necessary CANCEL requests.
271:             * </ul>
272:             * <p>
273:             * <b>Stateless Proxies:</b><br>
274:             * As a stateless proxy does not have any notion of transactions, or of
275:             * the response context used to describe stateful proxy behavior,
276:             * <code>responseEvent.getClientTransaction == null;</code>
277:             * always return <var>true</var>. Response processing does not apply, the
278:             * transaction layer of the SipProvider implementation is by-passed. An
279:             * application intending to stateless proxy the Response MUST:
280:             * <ul>
281:             * <li>Inspect the sent-by value in the first Via header.
282:             * <li>If that address matches the proxy, the proxy MUST remove that header
283:             * from the response.
284:             * <li>Forward the resulting response to the location indicated in the
285:             * next Via header using the
286:             * {@link SipProvider#sendResponse(Response)} method.
287:             * </ul>
288:             *
289:             * @since v1.1
290:             * @param responseEvent - the responseEvent fired from the SipProvider to
291:             * the SipListener representing a Response received from the network.
292:             */
293:            public void processResponse(ResponseEvent responseEvent);
294:
295:            /**
296:             * Processes a retransmit or expiration Timeout of an underlying
297:             * {@link Transaction} handled by this SipListener. This Event notifies the
298:             * application that a retransmission or transaction Timer expired in the
299:             * SipProvider's transaction state machine. The TimeoutEvent encapsulates
300:             * the specific timeout type and the transaction identifier either client
301:             * or server upon which the timeout occured. The type of Timeout can by
302:             * determined by:
303:             * <code>timeoutType = timeoutEvent.getTimeout().getValue();</code>
304:             *
305:             * @param timeoutEvent - the timeoutEvent received indicating either the
306:             * message retransmit or transaction timed out.
307:             */
308:            public void processTimeout(TimeoutEvent timeoutEvent);
309:
310:        }
www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.