View Javadoc

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  }