1 /*
2 * Copyright 2006 Simon Raess
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package net.sf.beep4j;
17
18
19 /**
20 * The SessionHandler represents the incoming view of a BEEP session. It has
21 * several call back methods that correspond to certain events in the lifecycle
22 * of the session. The {@link #connectionEstablished(StartSessionRequest)} method
23 * is invoked when the connection to the other peer has been established.
24 * Its purpose is to register zero or more profiles, which will be advertised
25 * in the greeting message. The {@link #sessionOpened(Session)} method
26 * is invoked when the greeting from the other peer has been received and the
27 * connectionEstablished method has returned. From that point on until the
28 * session is closed (as indicated by {@link #sessionClosed(Session)}) the
29 * session is in an usable state. When the other peer wants to start a
30 * channel the method {@link #startChannel(Session, StartChannelRequest)}
31 * is invoked.
32 *
33 * <p>The order of calls to this method is guaranteed to be as follows:</p>
34 *
35 * <ul>
36 * <li>{@link #connectionEstablished(StartSessionRequest)}</li>
37 * <li>{@link #sessionOpened(Session)}</li>
38 * <li>zero or more {@link #startChannel(Session, StartChannelRequest)}</li>
39 * <li>{@link #sessionClosed(Session)}</li>
40 * </ul>
41 *
42 * <p>It is possible that instead of the last three methods only the
43 * {@link #sessionStartDeclined(int, String)} method is called.</p>
44 *
45 * @author Simon Raess
46 *
47 * @see ch.iserver.beepj.Session
48 */
49 public interface SessionHandler {
50
51 /**
52 * The connectionEstablished method is called by the framework when the
53 * connection was established to the other peer. The purpose of
54 * this method is to send the BEEP greeting message (see 2.3.1.1
55 * of RFC 3080).
56 *
57 * <p>A server typically registers some profiles in this method.</p>
58 * <pre>
59 * public void connectionEstablished(StartSessionRequest s) {
60 * s.registerProfile("http://iana.org/beep/TLS");
61 * }
62 * </pre>
63 *
64 * <p>To send a negative reply, a SessionHandler can cancel the
65 * session startup.</p>
66 * <pre>
67 * public void connectionEstablished(StartSessionRequest s) {
68 * s.cancelSession();
69 * }
70 * </pre>
71 *
72 * @param s the session startup object
73 */
74 void connectionEstablished(StartSessionRequest s);
75
76 /**
77 * Invoked by the framework if the remote peer declines the session
78 * start by sending an error in a negative reply.
79 *
80 * @param code the reason code
81 * @param message the human readable message
82 */
83 void sessionStartDeclined(int code, String message);
84
85 /**
86 * This method is invoked when the session has been established.
87 *
88 * @param s the opened Session
89 */
90 void sessionOpened(Session s);
91
92 /**
93 * This method is invoked when the other peer wants to start
94 * a new channel. The passed in ChannelStartup method should
95 * be used to select a suitable channel and to install a
96 * ChannelHandler.
97 *
98 * <pre>
99 * public void startChannel(StartChannelRequest request) {
100 * request.selectProfile(startup.getProfiles()[0]);
101 * request.setChannelHandler(new MyChannelHandler());
102 * }
103 * </pre>
104 *
105 * Beside accepting the creation of a channel you can also decline
106 * it.
107 *
108 * <pre>
109 * public void startChannel(Session s, StartChannelRequest request) {
110 * request.cancel(550, "still working");
111 * }
112 * </pre>
113 *
114 * Both methods are mutually exclusive. Either you select a profile and
115 * a set a channel handler or you cancel the request.
116 *
117 * @param request all the information about the request to start a channel
118 */
119 void channelStartRequested(StartChannelRequest request);
120
121 /**
122 * This method is invoked when the session is closed.
123 */
124 void sessionClosed();
125
126 }