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: Operation.java 1379 2007-10-13 02:00:43Z vlads $
8 */
9
10 package javax.obex;
11
12 import java.io.IOException;
13
14 import javax.microedition.io.ContentConnection;
15
16 /**
17 * The <code>Operation</code> interface provides ways to manipulate a single
18 * OBEX PUT or GET operation. The implementation of this interface sends OBEX
19 * packets as they are built. If during the operation the peer in the operation
20 * ends the operation, an <code>IOException</code> is thrown on the next read
21 * from the input stream, write to the output stream, or call to
22 * <code>sendHeaders()</code>.
23 * <P>
24 * <STRONG>Definition of methods inherited from <code>ContentConnection</code></STRONG>
25 * <P>
26 * <code>getEncoding()</code> will always return <code>null</code>. <BR>
27 * <code>getLength()</code> will return the length specified by the OBEX
28 * Length header or -1 if the OBEX Length header was not included. <BR>
29 * <code>getType()</code> will return the value specified in the OBEX Type
30 * header or <code>null</code> if the OBEX Type header was not included.<BR>
31 * <P>
32 * <STRONG>How Headers are Handled</STRONG>
33 * <P>
34 * As headers are received, they may be retrieved through the
35 * <code>getReceivedHeaders()</code> method. If new headers are set during the
36 * operation, the new headers will be sent during the next packet exchange.
37 * <P>
38 * <STRONG>PUT example</STRONG>
39 * <P>
40 *
41 * <pre>
42 * void putObjectViaOBEX(ClientSession conn, HeaderSet head, byte[] obj) throws IOException {
43 *
44 * // Include the length header
45 * head.setHeader(head.LENGTH, new Long(obj.length));
46 *
47 * // Initiate the PUT request
48 * Operation op = conn.put(head);
49 *
50 * // Open the output stream to put the object to it
51 * DataOutputStream out = op.openDataOutputStream();
52 *
53 * // Send the object to the server
54 * out.write(obj);
55 *
56 * // End the transaction
57 * out.close();
58 * op.close();
59 * }
60 * </pre>
61 *
62 * <P>
63 * <STRONG>GET example</STRONG>
64 * <P>
65 *
66 * <pre>
67 * byte[] getObjectViaOBEX(ClientSession conn, HeaderSet head) throws IOException {
68 *
69 * // Send the initial GET request to the server
70 * Operation op = conn.get(head);
71 *
72 * // Retrieve the length of the object being sent back
73 * int length = op.getLength();
74 *
75 * // Create space for the object
76 * byte[] obj = new byte[length];
77 *
78 * // Get the object from the input stream
79 * DataInputStream in = trans.openDataInputStream();
80 * in.read(obj);
81 *
82 * // End the transaction
83 * in.close();
84 * op.close();
85 *
86 * return obj;
87 * }
88 * </pre>
89 *
90 * <H3>Client PUT Operation Flow</H3>
91 * For PUT operations, a call to <code>close()</code> the
92 * <code>OutputStream</code> returned from <code>openOutputStream()</code>
93 * or <code>openDataOutputStream()</code> will signal that the request is
94 * done. (In OBEX terms, the End-Of-Body header should be sent and the final bit
95 * in the request will be set.) At this point, the reply from the server may
96 * begin to be processed. A call to <code>getResponseCode()</code> will do an
97 * implicit close on the <code>OutputStream</code> and therefore signal that
98 * the request is done.
99 * <H3>Client GET Operation Flow</H3>
100 * For GET operation, a call to <code>openInputStream()</code> or
101 * <code>openDataInputStream()</code> will signal that the request is done.
102 * (In OBEX terms, the final bit in the request will be set.) A call to
103 * <code>getResponseCode()</code> will cause an implicit close on the
104 * <code>InputStream</code>. No further data may be read at this point.
105 *
106 * @version 1.0 February 11, 2002
107 */
108 public interface Operation extends ContentConnection {
109
110 /**
111 * Sends an ABORT message to the server. By calling this method, the
112 * corresponding input and output streams will be closed along with this
113 * object. No headers are sent in the abort request. This will end the
114 * operation since <code>close()</code> will be called by this method.
115 *
116 * @exception IOException
117 * if the transaction has already ended or if an OBEX server
118 * calls this method
119 */
120 public void abort() throws IOException;
121
122 /**
123 * Returns the headers that have been received during the operation.
124 * Modifying the object returned has no effect on the headers that are sent
125 * or retrieved.
126 *
127 * @return the headers received during this <code>Operation</code>
128 *
129 * @exception IOException
130 * if this <code>Operation</code> has been closed
131 */
132 public HeaderSet getReceivedHeaders() throws IOException;
133
134 /**
135 * Specifies the headers that should be sent in the next OBEX message that
136 * is sent.
137 *
138 * @param headers
139 * the headers to send in the next message
140 *
141 * @exception IOException
142 * if this <code>Operation</code> has been closed or the
143 * transaction has ended and no further messages will be
144 * exchanged
145 *
146 * @exception IllegalArgumentException
147 * if <code>headers</code> was not created by a call to
148 * <code>ServerRequestHandler.createHeaderSet()</code> or
149 * <code>ClientSession.createHeaderSet()</code>
150 *
151 * @exception NullPointerException
152 * if <code>headers</code> if <code>null</code>
153 */
154 public void sendHeaders(HeaderSet headers) throws IOException;
155
156 /**
157 * Returns the response code received from the server. Response codes are
158 * defined in the <code>ResponseCodes</code> class.
159 *
160 * @see ResponseCodes
161 *
162 * @return the response code retrieved from the server
163 *
164 * @exception IOException
165 * if an error occurred in the transport layer during the
166 * transaction; if this object was created by an OBEX server
167 */
168 public int getResponseCode() throws IOException;
169 }