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.internal.profile;
17
18 import java.net.SocketAddress;
19
20 import net.sf.beep4j.ChannelHandler;
21 import net.sf.beep4j.CloseChannelCallback;
22 import net.sf.beep4j.Message;
23 import net.sf.beep4j.ProfileInfo;
24 import net.sf.beep4j.Reply;
25 import net.sf.beep4j.SessionHandler;
26 import net.sf.beep4j.internal.CloseCallback;
27 import net.sf.beep4j.internal.SessionManager;
28
29 /**
30 * Interface of the channel management profile, which is used on channel 0
31 * of every BEEP session. Channel 0 is a bit special because it exists
32 * in every BEEP session as soon as the session is established.
33 *
34 * @author Simon Raess
35 */
36 public interface ChannelManagementProfile {
37
38 /**
39 * Invoked by the framework to initialize the channel and to get
40 * the ChannelHandler for the profile.
41 *
42 * @param manager the SessionManager to be used by the profile
43 * @return the ChannelHandler for the profile
44 */
45 ChannelHandler createChannelHandler(SessionManager manager);
46
47 /**
48 * Invoked by the session when the connection has been established.
49 * The profile must pass this event to the SessionHandler. Depending
50 * on the response of the application, either a greeting or an
51 * error is sent to the ResponseHandler.
52 * @param address address of remote peer
53 * @param handler the SessionHandler of the session
54 * @param response the ResponseHandler to be used to generate a response
55 *
56 * @return true iff the connection is established. Returning false from
57 * this method will drop the connection.
58 */
59 boolean connectionEstablished(SocketAddress address, SessionHandler handler,
60 Reply response);
61
62 /**
63 * Invoked by the session when a greeting has been received during
64 * the session startup. Parses the given message into a Greeting object.
65 *
66 * @param message the message to be parsed
67 * @return the parsed Greeting object
68 */
69 Greeting receivedGreeting(Message message);
70
71 /**
72 * Invoked by the session when an error has been received during
73 * the session startup.
74 * Parses the given message into a BEEPError object.
75 *
76 * @param message the message to be parsed
77 * @return the parsed BEEPError object
78 */
79 BEEPError receivedError(Message message);
80
81 /**
82 * Sends a start channel message to the other peer.
83 *
84 * @param channelNumber the channel number of the new peer
85 * @param infos the ProfileInfos to be passed inside the profile element in
86 * the request
87 * @param callback the callback that is invoked when the response is received
88 */
89 void startChannel(int channelNumber, ProfileInfo[] infos, StartChannelCallback callback);
90
91 /**
92 * Send a close channel message. The corresponding method is invoked on
93 * the callback to notify this peer about the outcome of the close
94 * request.
95 *
96 * @param channelNumber the channel to be closed
97 * @param callback the callback that is invoked when the response is received
98 */
99 void closeChannel(int channelNumber, CloseChannelCallback callback);
100
101 /**
102 * Closes the session. The BEEP specification notes that it is possible
103 * for a BEEP peer to decline session closing. However, this does not
104 * seem to make a lot of sense. So, if this method is invoked, the session
105 * is always closed.
106 *
107 * @param callback the callback used to notify about the response
108 */
109 void closeSession(CloseCallback callback);
110
111 }