1 /**
2 * Java docs licensed under the Apache License, Version 2.0
3 * http://www.apache.org/licenses/LICENSE-2.0
4 * (c) Copyright 2001, 2002 Motorola, Inc. ALL RIGHTS RESERVED.
5 *
6 *
7 * @version $Id: SessionNotifier.java 1379 2007-10-13 02:00:43Z vlads $
8 */
9 package javax.obex;
10
11 import java.io.IOException;
12
13 import javax.microedition.io.Connection;
14
15 /**
16 * The <code>SessionNotifier</code> interface defines a connection notifier
17 * for server-side OBEX connections. When a <code>SessionNotifier</code> is
18 * created and calls <code>acceptAndOpen()</code>, it will begin listening
19 * for clients to create a connection at the transport layer. When the transport
20 * layer connection is received, the <code>acceptAndOpen()</code> method will
21 * return a <code>javax.microedition.io.Connection</code> that is the
22 * connection to the client. The <code>acceptAndOpen()</code> method also
23 * takes a <code>ServerRequestHandler</code> argument that will process the
24 * requests from the client that connects to the server.
25 *
26 * @version 1.0 February 11, 2002
27 */
28 public interface SessionNotifier extends Connection {
29
30 /**
31 * Waits for a transport layer connection to be established and specifies
32 * the handler to handle the requests from the client. No authenticator is
33 * associated with this connection, therefore, it is implementation
34 * dependent as to how an authentication challenge and authentication
35 * response header will be received and processed.
36 * <P>
37 * <H4>Additional Note for OBEX over Bluetooth</H4>
38 * If this method is called on a <code>SessionNotifier</code> object that
39 * does not have a <code>ServiceRecord</code> in the SDDB, the
40 * <code>ServiceRecord</code> for this object will be added to the SDDB.
41 * This method requests the BCC to put the local device in connectable mode
42 * so that it will respond to connection attempts by clients.
43 * <P>
44 * The following checks are done to verify that the service record provided
45 * is valid. If any of these checks fail, then a
46 * <code>ServiceRegistrationException</code> is thrown.
47 * <UL>
48 * <LI>ServiceClassIDList and ProtocolDescriptorList, the mandatory service
49 * attributes for a <code>btgoep</code> service record, must be present in
50 * the <code>ServiceRecord</code> associated with this notifier.
51 * <LI>L2CAP, RFCOMM and OBEX must all be in the ProtocolDescriptorList
52 * <LI>The <code>ServiceRecord</code> associated with this notifier must
53 * not have changed the RFCOMM server channel number
54 * </UL>
55 * <P>
56 * This method will not ensure that <code>ServiceRecord</code> associated
57 * with this notifier is a completely valid service record. It is the
58 * responsibility of the application to ensure that the service record
59 * follows all of the applicable syntactic and semantic rules for service
60 * record correctness.
61 * <p>
62 * Note : once an application invokes {@code close()} on any
63 * {@code L2CAPConnectionNotifier}, {@code SessionNotifier}, or
64 * {@code StreamConnectionNotifer} instance, all pending
65 * {@code acceptAndOpen()} methods that have been invoked previously on that
66 * instance MUST throw {@code InterruptedIOException}. This mechanism
67 * provides an application with the means to cancel any outstanding
68 * {@code acceptAndOpen()} method calls
69 *
70 * @param handler
71 * the request handler that will respond to OBEX requests
72 *
73 * @return the connection to the client
74 *
75 * @exception IOException
76 * if an error occurs in the transport layer
77 *
78 * @exception NullPointerException
79 * if <code>handler</code> is <code>null</code>
80 *
81 * @exception ServiceRegistrationException
82 * if the structure of the associated service record is
83 * invalid or if the service record could not be added
84 * successfully to the local SDDB. The structure of service
85 * record is invalid if the service record is missing any
86 * mandatory service attributes, or has changed any of the
87 * values described above which are fixed and cannot be
88 * changed. Failures to add the record to the SDDB could be
89 * due to insufficient disk space, database locks, etc.
90 *
91 * @exception BluetoothStateException
92 * if the server device could not be placed in connectable
93 * mode because the device user has configured the device to
94 * be non-connectable
95 */
96 public Connection acceptAndOpen(ServerRequestHandler handler) throws IOException;
97
98 /**
99 * Waits for a transport layer connection to be established and specifies
100 * the handler to handle the requests from the client and the
101 * <code>Authenticator</code> to use to respond to authentication
102 * challenge and authentication response headers.
103 * <P>
104 * <H4>Additional Note for OBEX over Bluetooth</H4>
105 * If this method is called on a <code>SessionNotifier</code> object that
106 * does not have a <code>ServiceRecord</code> in the SDDB, the
107 * <code>ServiceRecord</code> for this object will be added to the SDDB.
108 * This method requests the BCC to put the local device in connectable mode
109 * so that it will respond to connection attempts by clients.
110 * <P>
111 * The following checks are done to verify that the service record provided
112 * is valid. If any of these checks fail, then a
113 * <code>ServiceRegistrationException</code> is thrown.
114 * <UL>
115 * <LI>ServiceClassIDList and ProtocolDescriptorList, the mandatory service
116 * attributes for a <code>btgoep</code> service record, must be present in
117 * the <code>ServiceRecord</code> associated with this notifier.
118 * <LI>L2CAP, RFCOMM and OBEX must all be in the ProtocolDescriptorList
119 * <LI>The <code>ServiceRecord</code> associated with this notifier must
120 * not have changed the RFCOMM server channel number
121 * </UL>
122 * <P>
123 * This method will not ensure that <code>ServiceRecord</code> associated
124 * with this notifier is a completely valid service record. It is the
125 * responsibility of the application to ensure that the service record
126 * follows all of the applicable syntactic and semantic rules for service
127 * record correctness.
128 * <p>
129 * Note : once an application invokes {@code close()} on any
130 * {@code L2CAPConnectionNotifier}, {@code SessionNotifier}, or
131 * {@code StreamConnectionNotifer} instance, all pending
132 * {@code acceptAndOpen()} methods that have been invoked previously on that
133 * instance MUST throw {@code InterruptedIOException}. This mechanism
134 * provides an application with the means to cancel any outstanding
135 * {@code acceptAndOpen()} method calls
136 *
137 * @param handler
138 * the request handler that will respond to OBEX requests
139 *
140 * @param auth
141 * the <code>Authenticator</code> to use with this connection;
142 * if <code>null</code> then no <code>Authenticator</code>
143 * will be used
144 *
145 * @return the connection to the client
146 *
147 * @exception IOException
148 * if an error occurs in the transport layer
149 *
150 * @exception NullPointerException
151 * if <code>handler</code> is <code>null</code>
152 *
153 * @exception ServiceRegistrationException
154 * if the structure of the associated service record is
155 * invalid or if the service record could not be added
156 * successfully to the local SDDB. The structure of service
157 * record is invalid if the service record is missing any
158 * mandatory service attributes, or has changed any of the
159 * values described above which are fixed and cannot be
160 * changed. Failures to add the record to the SDDB could be
161 * due to insufficient disk space, database locks, etc.
162 *
163 * @exception BluetoothStateException
164 * if the server device could not be placed in connectable
165 * mode because the device user has configured the device to
166 * be non-connectable
167 */
168 public Connection acceptAndOpen(ServerRequestHandler handler, Authenticator auth) throws IOException;
169 }