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 }