1/*
2 * Copyright (c) 2008-2009, Motorola, Inc.
3 *
4 * All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are met:
8 *
9 * - Redistributions of source code must retain the above copyright notice,
10 * this list of conditions and the following disclaimer.
11 *
12 * - Redistributions in binary form must reproduce the above copyright notice,
13 * this list of conditions and the following disclaimer in the documentation
14 * and/or other materials provided with the distribution.
15 *
16 * - Neither the name of the Motorola, Inc. nor the names of its contributors
17 * may be used to endorse or promote products derived from this software
18 * without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
24 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
25 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
26 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
27 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
28 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
29 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
30 * POSSIBILITY OF SUCH DAMAGE.
31 */
32
33package javax.obex;
34
35import java.io.DataInputStream;
36import java.io.DataOutputStream;
37import java.io.IOException;
38import java.io.InputStream;
39import java.io.OutputStream;
40
41/**
42 * The <code>Operation</code> interface provides ways to manipulate a single
43 * OBEX PUT or GET operation. The implementation of this interface sends OBEX
44 * packets as they are built. If during the operation the peer in the operation
45 * ends the operation, an <code>IOException</code> is thrown on the next read
46 * from the input stream, write to the output stream, or call to
47 * <code>sendHeaders()</code>.
48 * <P>
49 * <STRONG>Definition of methods inherited from <code>ContentConnection</code>
50 * </STRONG>
51 * <P>
52 * <code>getEncoding()</code> will always return <code>null</code>. <BR>
53 * <code>getLength()</code> will return the length specified by the OBEX Length
54 * header or -1 if the OBEX Length header was not included. <BR>
55 * <code>getType()</code> will return the value specified in the OBEX Type
56 * header or <code>null</code> if the OBEX Type header was not included.<BR>
57 * <P>
58 * <STRONG>How Headers are Handled</STRONG>
59 * <P>
60 * As headers are received, they may be retrieved through the
61 * <code>getReceivedHeaders()</code> method. If new headers are set during the
62 * operation, the new headers will be sent during the next packet exchange.
63 * <P>
64 * <STRONG>PUT example</STRONG>
65 * <P>
66 * <PRE>
67 * void putObjectViaOBEX(ClientSession conn, HeaderSet head, byte[] obj) throws IOException {
68 *     // Include the length header
69 *     head.setHeader(head.LENGTH, new Long(obj.length));
70 *     // Initiate the PUT request
71 *     Operation op = conn.put(head);
72 *     // Open the output stream to put the object to it
73 *     DataOutputStream out = op.openDataOutputStream();
74 *     // Send the object to the server
75 *     out.write(obj);
76 *     // End the transaction
77 *     out.close();
78 *     op.close();
79 * }
80 * </PRE>
81 * <P>
82 * <STRONG>GET example</STRONG>
83 * <P>
84 * <PRE>
85 * byte[] getObjectViaOBEX(ClientSession conn, HeaderSet head) throws IOException {
86 *     // Send the initial GET request to the server
87 *     Operation op = conn.get(head);
88 *     // Retrieve the length of the object being sent back
89 *     int length = op.getLength();
90 *     // Create space for the object
91 *     byte[] obj = new byte[length];
92 *     // Get the object from the input stream
93 *     DataInputStream in = trans.openDataInputStream();
94 *     in.read(obj);
95 *     // End the transaction
96 *     in.close();
97 *     op.close();
98 *     return obj;
99 * }
100 * </PRE>
101 *
102 * <H3>Client PUT Operation Flow</H3> For PUT operations, a call to
103 * <code>close()</code> the <code>OutputStream</code> returned from
104 * <code>openOutputStream()</code> or <code>openDataOutputStream()</code> will
105 * signal that the request is done. (In OBEX terms, the End-Of-Body header
106 * should be sent and the final bit in the request will be set.) At this point,
107 * the reply from the server may begin to be processed. A call to
108 * <code>getResponseCode()</code> will do an implicit close on the
109 * <code>OutputStream</code> and therefore signal that the request is done.
110 * <H3>Client GET Operation Flow</H3> For GET operation, a call to
111 * <code>openInputStream()</code> or <code>openDataInputStream()</code> will
112 * signal that the request is done. (In OBEX terms, the final bit in the request
113 * will be set.) A call to <code>getResponseCode()</code> will cause an implicit
114 * close on the <code>InputStream</code>. No further data may be read at this
115 * point.
116 * @hide
117 */
118public interface Operation {
119
120    /**
121     * Sends an ABORT message to the server. By calling this method, the
122     * corresponding input and output streams will be closed along with this
123     * object. No headers are sent in the abort request. This will end the
124     * operation since <code>close()</code> will be called by this method.
125     * @throws IOException if the transaction has already ended or if an OBEX
126     *         server calls this method
127     */
128    void abort() throws IOException;
129
130    /**
131     * Returns the headers that have been received during the operation.
132     * Modifying the object returned has no effect on the headers that are sent
133     * or retrieved.
134     * @return the headers received during this <code>Operation</code>
135     * @throws IOException if this <code>Operation</code> has been closed
136     */
137    HeaderSet getReceivedHeader() throws IOException;
138
139    /**
140     * Specifies the headers that should be sent in the next OBEX message that
141     * is sent.
142     * @param headers the headers to send in the next message
143     * @throws IOException if this <code>Operation</code> has been closed or the
144     *         transaction has ended and no further messages will be exchanged
145     * @throws IllegalArgumentException if <code>headers</code> was not created
146     *         by a call to <code>ServerRequestHandler.createHeaderSet()</code>
147     *         or <code>ClientSession.createHeaderSet()</code>
148     * @throws NullPointerException if <code>headers</code> if <code>null</code>
149     */
150    void sendHeaders(HeaderSet headers) throws IOException;
151
152    /**
153     * Returns the response code received from the server. Response codes are
154     * defined in the <code>ResponseCodes</code> class.
155     * @see ResponseCodes
156     * @return the response code retrieved from the server
157     * @throws IOException if an error occurred in the transport layer during
158     *         the transaction; if this object was created by an OBEX server
159     */
160    int getResponseCode() throws IOException;
161
162    String getEncoding();
163
164    long getLength();
165
166    int getHeaderLength();
167
168    String getType();
169
170    InputStream openInputStream() throws IOException;
171
172    DataInputStream openDataInputStream() throws IOException;
173
174    OutputStream openOutputStream() throws IOException;
175
176    DataOutputStream openDataOutputStream() throws IOException;
177
178    void close() throws IOException;
179
180    int getMaxPacketSize();
181
182    public void noBodyHeader();
183}
184