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: ClientSession.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>ClientSession</code> interface provides methods for OBEX
17 * requests. This interface provides a way to define headers for any OBEX
18 * operation. OBEX operations are CONNECT, SETPATH, PUT, GET and DISCONNECT. For
19 * PUTs and GETs, this interface will return a <code>javax.obex.Operation</code>
20 * object to complete the operations. For CONNECT, DISCONNECT, and SETPATH
21 * operations, this interface will complete the operation and return the result
22 * in a <code>HeaderSet</code> object.
23 * <P>
24 * <STRONG>Connection ID and Target Headers</STRONG>
25 * <P>
26 * According to the IrOBEX specification, a packet may not contain a Connection
27 * ID and Target header. Since the Connection ID header is managed by the
28 * implementation, it will not send a Connection ID header if a Connection ID
29 * was specified in a packet that has a Target header. In other words, if an
30 * application adds a Target header to a <code>HeaderSet</code> object used in
31 * an OBEX operation and a Connection ID was specified, no Connection ID will be
32 * sent in the packet containing the Target header.
33 * <P>
34 * <STRONG>CREATE-EMPTY and PUT-DELETE Requests</STRONG>
35 * <P>
36 * To perform a CREATE-EMPTY request, the client must call the
37 * <code>put()</code> method. With the <code>Operation</code> object
38 * returned, the client must open the output stream by calling
39 * <code>openOutputStream()</code> and then close the stream by calling
40 * <code>close()</code> on the <code>OutputStream</code> without writing any
41 * data. Using the <code>DataOutputStream</code> returned from
42 * <code>openDataOutputStream()</code> works the same way.
43 * <P>
44 * There are two ways to perform a PUT-DELETE request. The <code>delete()</code>
45 * method is one way to perform a PUT-DELETE request. The second way to perform
46 * a PUT-DELETE request is by calling <code>put()</code> and never calling
47 * <code>openOutputStream()</code> or <code>openDataOutputStream()</code> on
48 * the <code>Operation</code> object returned from <code>put()</code>.
49 * <P>
50 * <STRONG>PUT example</STRONG>
51 * <P>
52 *
53 * <pre>
54 * void putObjectViaOBEX(ClientSession conn, HeaderSet head, byte[] obj) throws IOException {
55 *
56 * // Include the length header
57 * head.setHeader(HeaderSet.LENGTH, new Long(obj.length));
58 *
59 * // Initiate the PUT request
60 * Operation op = conn.put(head);
61 *
62 * // Open the output stream to put the object to it
63 * OutputStream out = op.openOutputStream();
64 *
65 * // Send the object to the server
66 * out.write(obj);
67 *
68 * // End the transaction
69 * out.close();
70 * op.close();
71 * }
72 * </pre>
73 *
74 * <P>
75 * <STRONG>GET example</STRONG>
76 * <P>
77 *
78 * <pre>
79 * byte[] getObjectViaOBEX(ClientSession conn, HeaderSet head) throws IOException {
80 *
81 * // Send the initial GET request to the server
82 * Operation op = conn.get(head);
83 *
84 * // Get the object from the input stream
85 * InputStream in = op.openInputStream();
86 *
87 * ByteArrayOutputStream out = new ByteArrayOutputStream();
88 * int data = in.read();
89 * while (data != -1) {
90 * out.write((byte) data);
91 * data = in.read();
92 * }
93 *
94 * // End the transaction
95 * in.close();
96 * op.close();
97 *
98 * byte[] obj = out.toByteArray();
99 * out.close();
100 *
101 * return obj;
102 * }
103 * </pre>
104 *
105 * @version 1.0 February 11, 2002
106 */
107 public interface ClientSession extends Connection {
108
109 /**
110 * Sets the <code>Authenticator</code> to use with this connection. The
111 * <code>Authenticator</code> allows an application to respond to
112 * authentication challenge and authentication response headers. If no
113 * <code>Authenticator</code> is set, the response to an authentication
114 * challenge or authentication response header is implementation dependent.
115 *
116 * @param auth
117 * the <code>Authenticator</code> to use for this connection
118 *
119 * @exception NullPointerException
120 * if <code>auth</code> is <code>null</code>
121 */
122 public void setAuthenticator(Authenticator auth);
123
124 /**
125 * Creates a <code>javax.obex.HeaderSet</code> object. This object can be
126 * used to define header values in a request.
127 *
128 * @see HeaderSet
129 *
130 * @return a new <code>javax.obex.HeaderSet</code> object
131 */
132 public HeaderSet createHeaderSet();
133
134 /**
135 * Sets the connection ID header to include in the request packets. If a
136 * connection ID is set, it will be sent in each request to the server
137 * except for the CONNECT request. An application only needs to set the
138 * connection ID if it is trying to operate with different targets over the
139 * same transport layer connection. If a client receives a connection ID
140 * from the server, the implementation will continue to use that connection
141 * ID until the application changes it or until the connection is closed.
142 *
143 * @param id
144 * the connection ID to use
145 *
146 * @exception IllegalArgumentException
147 * if <code>id</code> is not in the range 0 to 2<sup>32</sup>-1
148 */
149 public void setConnectionID(long id);
150
151 /**
152 * Retrieves the connection ID that is being used in the present connection.
153 * This method will return -1 if no connection ID is being used.
154 *
155 * @return the connection ID being used or -1 if no connection ID is being
156 * used
157 */
158 public long getConnectionID();
159
160 /**
161 * Completes an OBEX CONNECT operation. If the <code>headers</code>
162 * argument is <code>null</code>, no headers will be sent in the request.
163 * This method will never return <code>null</code>.
164 * <P>
165 * This method must be called and a successful response code of
166 * <code>OBEX_HTTP_OK</code> must be received before <code>put()</code>,
167 * <code>get()</code>, <code>setPath()</code>, <code>delete()</code>,
168 * or <code>disconnect()</code> may be called. Similarly, after a
169 * successful call to <code>disconnect()</code>, this method must be
170 * called before calling <code>put()</code>, <code>get()</code>,
171 * <code>setPath()</code>, <code>delete()</code>, or
172 * <code>disconnect()</code>.
173 *
174 * @param headers
175 * the headers to send in the CONNECT request
176 *
177 * @return the headers that were returned from the server
178 *
179 * @exception IOException
180 * if an error occurred in the transport layer; if the client
181 * is already in an operation; if this method had already
182 * been called with a successful response code of
183 * <code>OBEX_HTTP_OK</code> and calls to
184 * <code>disconnect()</code> have not returned a response
185 * code of <code>OBEX_HTTP_OK</code>; if the headers
186 * defined in <code>headers</code> exceed the max packet
187 * length
188 *
189 * @exception IllegalArgumentException
190 * if <code>headers</code> was not created by a call to
191 * <code>createHeaderSet()</code>
192 */
193 public HeaderSet connect(HeaderSet headers) throws IOException;
194
195 /**
196 * Completes an OBEX DISCONNECT operation. If the <code>headers</code>
197 * argument is <code>null</code>, no headers will be sent in the request.
198 * This method will end the session. A new session may be started by calling
199 * <code>connect()</code>. This method will never return
200 * <code>null</code>.
201 *
202 * @param headers
203 * the header to send in the DISCONNECT request
204 *
205 * @return the headers returned by the server
206 *
207 * @exception IOException
208 * if an error occurred in the transport layer; if the client
209 * is already in an operation; if an OBEX connection does not
210 * exist because <code>connect()</code> has not been
211 * called; if <code>disconnect()</code> has been called and
212 * received a response code of <code>OBEX_HTTP_OK</code>
213 * after the last call to <code>connect()</code>; if the
214 * headers defined in <code>headers</code> exceed the max
215 * packet length
216 *
217 * @exception IllegalArgumentException
218 * if <code>headers</code> were not created by a call to
219 * <code>createHeaderSet()</code>
220 */
221 public HeaderSet disconnect(HeaderSet headers) throws IOException;
222
223 /**
224 * Completes an OBEX SETPATH operation. This method will never return
225 * <code>null</code>.
226 *
227 * @param backup
228 * if <code>true</code>, instructs the server to back up one
229 * directory before moving to the directory specified in name
230 * (similar to cd .. on PCs); if <code>false</code>, apply
231 * <code>name</code> to the current directory
232 *
233 * @param create
234 * if <code>true</code>, instructs the server to create the
235 * directory if it does not exist; if <code>false</code>,
236 * instruct the server to return an error code if the directory
237 * does not exist
238 *
239 * @param headers
240 * the headers to include in the SETPATH request
241 *
242 * @return the headers that were returned from the server
243 *
244 * @exception IOException
245 * if an error occurred in the transport layer; if the client
246 * is already in an operation; if an OBEX connection does not
247 * exist because <code>connect()</code> has not been
248 * called; if <code>disconnect()</code> had been called and
249 * a response code of <code>OBEX_HTTP_OK</code> was
250 * received; if the headers defined in <code>headers</code>
251 * exceed the max packet length
252 *
253 * @exception IllegalArgumentException
254 * if <code>headers</code> were not created by a call to
255 * <code>createHeaderSet()</code>
256 */
257 public HeaderSet setPath(HeaderSet headers, boolean backup, boolean create) throws IOException;
258
259 /**
260 * Performs an OBEX DELETE operation. This method will never return
261 * <code>null</code>.
262 *
263 * @param headers
264 * the header to send in the DELETE request
265 *
266 * @return the headers returned by the server
267 *
268 * @exception IOException
269 * if an error occurred in the transport layer; if the client
270 * is already in an operation; if an OBEX connection does not
271 * exist because <code>connect()</code> has not been
272 * called; if <code>disconnect()</code> had been called and
273 * a response code of <code>OBEX_HTTP_OK</code> was
274 * received; if the headers defined in <code>headers</code>
275 * exceed the max packet length
276 *
277 * @exception IllegalArgumentException
278 * if <code>headers</code> were not created by a call to
279 * <code>createHeaderSet()</code>
280 */
281 public HeaderSet delete(HeaderSet headers) throws IOException;
282
283 /**
284 * Performs an OBEX GET operation. This method will send the OBEX headers
285 * provided to the server and return an <code>Operation</code> object to
286 * continue with the operation. This method will never return
287 * <code>null</code>.
288 *
289 * @see Operation
290 *
291 * @param headers
292 * the OBEX headers to send as part of the initial GET request
293 *
294 * @return the OBEX operation that will complete the GET request
295 *
296 * @exception IOException
297 * if an error occurred in the transport layer; if an OBEX
298 * connection does not exist because <code>connect()</code>
299 * has not been called; if <code>disconnect()</code> had
300 * been called and a response code of
301 * <code>OBEX_HTTP_OK</code> was received; if
302 * <code>connect()</code> has not been called; if the
303 * client is already in an operation;
304 *
305 * @exception IllegalArgumentException
306 * if <code>headers</code> were not created by a call to
307 * <code>createHeaderSet()</code>
308 */
309 public Operation get(HeaderSet headers) throws IOException;
310
311 /**
312 * Performs an OBEX PUT operation. This method will send the OBEX headers
313 * provided to the server and return an <code>Operation</code> object to
314 * continue with the PUT operation. This method will never return
315 * <code>null</code>.
316 *
317 * @see Operation
318 *
319 * @param headers
320 * the OBEX headers to send in the initial PUT request
321 *
322 * @return the operation object used to complete the PUT request
323 *
324 * @exception IOException
325 * if an error occurred in the transport layer; if an OBEX
326 * connection does not exist because <code>connect()</code>
327 * has not been called; if <code>disconnect()</code> had
328 * been called and a response code of
329 * <code>OBEX_HTTP_OK</code> was received; if
330 * <code>connect()</code> has not been called; if the
331 * client is already in an operation;
332 *
333 * @exception IllegalArgumentException
334 * if <code>headers</code> were not created by a call to
335 * <code>createHeaderSet()</code>
336 */
337 public Operation put(HeaderSet headers) throws IOException;
338 }