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 * Represents a BEEP session with another peer. It allows to close the
21 * session or start one or several channels. The Session interface
22 * represents the outgoing view of a BEEP peer. The corresponding
23 * incoming interface is the {@link SessionHandler}.
24 *
25 * @author Simon Raess
26 */
27 public interface Session {
28
29 /**
30 * Gets the list of profiles supported by the remote peer. It may be
31 * that the peer supports additional profiles, which it did not advertise
32 * and which are thus not returned from this method.
33 *
34 * @return an array of advertised profiles by the other peer
35 */
36 String[] getProfiles();
37
38 /**
39 * Tries to start a new channel using the profile identified by the given
40 * uri. The returned Future can be used to wait until the channel has
41 * been established. It returns only after the passed in
42 * {@link ChannelHandler#channelOpened(Channel)} method returns.
43 *
44 * @param profileUri the uri of the profile to be used on the channel
45 * @param handler the channel handler for the new channel
46 * @return a Future that can be used to await the successful establishment
47 * of the channel.
48 */
49 void startChannel(String profileUri, ChannelHandler handler);
50
51 /**
52 * Tries to start a new channel using the profile passed in. Use this
53 * method if you have to pass initialization data along the start
54 * channel request. See {@link #startChannel(String, ChannelHandler)}
55 * for the details.
56 *
57 * @param profile the profile
58 * @param handler the channel handler for the new channel
59 * @return a Future that can be used to await the successfuly establishment
60 * of the channel
61 */
62 void startChannel(ProfileInfo profile, ChannelHandler handler);
63
64 /**
65 * Tries to start a new channel using one of the profiles passed in. Use this
66 * method if you have to pass initialization data along the start
67 * channel request. See {@link #startChannel(String, ChannelHandler)}
68 * for the details.
69 *
70 * @param profiles the profiles from which the other peer can choose
71 * @param factory the factory that creates new ChannelHandlers for the new channel
72 * @return a Future that can be used to await the successfuly establishment
73 * of the channel
74 */
75 void startChannel(ProfileInfo[] profiles, ChannelHandlerFactory factory);
76
77 /**
78 * Closes the session. Note that this method blocks until all outstanding
79 * requests have been sent and all requests received up to the moment
80 * this method is called have been properly replied to. It ignores negative
81 * replies to a close request from the other peer.
82 */
83 void close();
84
85 }