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 33 package javax.obex; 34 35 import java.io.DataInputStream; 36 import java.io.DataOutputStream; 37 import java.io.IOException; 38 import java.io.InputStream; 39 import 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 */ 118 public 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
