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 * Represents a request to start a new channel by the other peer.
20 * This request may be cancelled or accepted by selecting a profile
21 * from a list of profiles. If you take no action, the request
22 * will be cancelled, the channel not created.
23 *
24 * @author Simon Raess
25 */
26 public interface StartChannelRequest {
27
28 /**
29 * Gets the list of acceptable profiles sent as part of the start
30 * channel request.
31 *
32 * @return the array of acceptable profiles
33 */
34 ProfileInfo[] getProfiles();
35
36 /**
37 * Determines whether there is a profile element with the
38 * given profile uri.
39 *
40 * @param profileUri the profile uri
41 * @return true iff a profile info object with the given uri is available
42 */
43 boolean hasProfile(String profileUri);
44
45 /**
46 * Gets the ProfileInfo for the given profile uri. If there is no
47 * ProfileInfo object matching the uri, an IllegalArgumentException
48 * is thrown. This method does not return null.
49 *
50 * @param profileUri the profile uri
51 * @return the ProfileInfo object matching the given profile uri
52 * @throws IllegalArgumentException if the profile info element is missing
53 */
54 ProfileInfo getProfile(String profileUri);
55
56 /**
57 * Selects one particular profile from the list of profiles.
58 * The acceptable list of profiles can be retrieved from the
59 * {@link #getProfiles()} method. If you pass in a profile
60 * which is not in the list of profiles, this method will
61 * throw an exception.
62 *
63 * @param profile the selected profile for the channel
64 * @param handler the channel handler for the new channel
65 */
66 void selectProfile(ProfileInfo profile, ChannelHandler handler);
67
68 /**
69 * Cancels the request to start a new channel. An error element in a negative
70 * reply is sent to the other peer and the channel won't
71 * be created.
72 *
73 * @param code the reply code
74 * @param message the diagnostic message
75 */
76 void cancel(int code, String message);
77
78 }